npm package: @garyellow/mianshiya-mcp
Description: MCP Server for Mianshiya interview questions and question banks - supporting search, browse and detailed information retrieval
Author: garyellow
Latest version: 0.1.1

# Mianshiya MCP Server

一個為面試鴨（Mianshiya）平台設計的 Model Context Protocol (MCP) 服務器，讓 AI 應用能夠訪問豐富的面試題庫和問題資源。基於 TypeScript 構建，支援現代 MCP 最佳實踐。

## ✨ 功能特色

- 🔍 **搜尋面試題目** - 根據關鍵字快速找到相關題目，顯示核心資訊（難度、標籤、權限）
- 📚 **瀏覽題庫** - 分頁瀏覽所有可用的題庫，支援關鍵字過濾，精簡顯示重要資訊
- 🎯 **查詢題庫內容** - 獲取特定題庫中的所有題目，簡潔清晰的格式
- 🚀 **雙包管理器支援** - 支援 npm/npx 和 bun/bunx
- ⚡ **TypeScript 實現** - 型別安全、現代化架構
- 🛡️ **強化錯誤處理** - 完整的參數驗證和錯誤回饋
- 📝 **優化輸出格式** - 移除冗餘資訊，專注核心內容

## 📦 安裝方式

### 使用 npm

```bash
# 直接執行
npx mianshiya-mcp
```

### 使用 bun

```bash
# 直接執行
bunx mianshiya-mcp
```

### 從源碼安裝

```bash
git clone <repository-url>
cd mianshiya-mcp
npm install
npm run build
npm start
```

## ⚙️ 配置說明

### Claude Desktop 配置

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "mianshiya": {
      "command": "npx",
      "args": ["mianshiya-mcp"]
    }
  }
}
```

如果使用 bun：

```json
{
  "mcpServers": {
    "mianshiya": {
      "command": "bunx",
      "args": ["mianshiya-mcp"]
    }
  }
}
```

### Cherry Studio 配置

```json
{
  "mcpServers": {
    "mianshiyaServer": {
      "command": "bun",
      "args": ["run", "dist/index.js"],
      "env": {},
      "cwd": "/path/to/mianshiya-mcp"
    }
  }
}
```

### Cursor IDE 配置

在 MCP 設定中新增相同配置即可。

## 🛠️ 可用工具

### 1. searchQuestions
根據關鍵字搜尋面試題目，返回簡潔有用的資訊。

**參數：**
- `searchText` (string): 搜尋關鍵字，例如：Java、Spring Boot、React
- `limit` (number, 可選): 返回結果數量，預設 5，最多 200

**輸出格式：**
- 題目標題和權限標記（🆓 免費 / 🔒 VIP專屬）
- 難度等級和主要標籤（最多3個）
- 直接訪問連結

**示例：**
```
searchQuestions(searchText="Java多線程", limit=10)
```

### 2. browseQuestionBanks
分頁瀏覽題庫，支援可選的關鍵字過濾，顯示精簡資訊。

**參數：**
- `current` (number, 可選): 當前頁碼，從 1 開始，預設 1
- `pageSize` (number, 可選): 每頁數量，預設 10，最多 200
- `keyword` (string, 可選): 搜尋關鍵字，用於過濾題庫標題、描述或標籤

**輸出格式：**
- 題庫ID、標題和描述
- 主要標籤（最多3個）和題目數量
- 瀏覽數統計

**示例：**
```
browseQuestionBanks(current=1, pageSize=20, keyword="Java")
```

### 3. getQuestionBankQuestions
獲取特定題庫中的題目，顯示核心資訊。

**參數：**
- `questionBankId` (string): 題庫 ID，可從 browseQuestionBanks 工具獲取
- `current` (number, 可選): 當前頁碼，從 1 開始，預設 1
- `pageSize` (number, 可選): 每頁數量，預設 20，最多 200

**輸出格式：**
- 題目標題和難度等級
- 主要標籤（最多3個）和權限資訊
- 直接訪問連結

**示例：**
```
getQuestionBankQuestions(questionBankId="1787463103423897602", current=1, pageSize=30)
```

## 🏗️ 開發指南

### 環境要求

- Node.js >= 18.0.0
- npm 或 bun

### 開發設置

```bash
# 克隆倉庫
git clone <repository-url>
cd mianshiya-mcp

# 安裝依賴
npm install
# 或
bun install

# 開發模式
npm run dev
# 或
bun run dev

# 建置專案
npm run build

# 代碼格式化
npm run format

# 代碼檢查
npm run lint

# 執行測試
npm run test:basic
npm run test:comprehensive
```

### 專案結構

```
mianshiya-mcp/
├── src/
│   └── index.ts              # 主要服務器代碼
├── dist/                     # 編譯輸出目錄
├── .github/                  # GitHub 配置
│   └── copilot-instructions.md
├── package.json              # 專案配置
├── tsconfig.json             # TypeScript 配置
├── eslint.config.js          # ESLint 配置
├── .prettierrc.json          # Prettier 配置
├── test-*.mjs                # 測試文件
└── README.md                 # 文檔
```

## 🌐 API 說明

本服務器使用面試鴨的公開 API：

- 搜尋題目：`POST https://api.mianshiya.com/api/question/search`
- 題庫列表：`POST https://api.mianshiya.com/api/question_bank/list/page/vo`
- 題庫題目：`POST https://api.mianshiya.com/api/question_bank/list_question`

## 🔧 MCP 最佳實踐

本專案遵循 MCP 協議的最佳實踐：

- ✅ **標準化錯誤處理** - 使用 `isError` 標記和統一錯誤格式
- ✅ **完整參數驗證** - JSON Schema 驗證所有輸入參數
- ✅ **資源限制** - 合理的分頁和限制設置
- ✅ **描述性工具名稱** - 清晰的工具和參數描述
- ✅ **一致的回應格式** - 標準化的 content 結構

## 🎯 使用範例

```typescript
// 搜尋 Java 相關題目
await searchQuestions({
  searchText: "Java多線程",
  limit: 5
});

// 瀏覽包含 "Spring" 的題庫
await browseQuestionBanks({
  keyword: "Spring",
  current: 1,
  pageSize: 10
});

// 獲取特定題庫的題目
await getQuestionBankQuestions({
  questionBankId: "1787463103423897602",
  current: 1,
  pageSize: 20
});
```

## 📄 授權條款

MIT License

## 🤝 貢獻指南

歡迎提交 Issue 和 Pull Request！

1. Fork 本倉庫
2. 創建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 開啟 Pull Request

## 🆘 支援

如果遇到問題，請：

1. 檢查 [Issues](https://github.com/your-repo/mianshiya-mcp/issues) 中是否有類似問題
2. 創建新的 Issue 詳細描述問題
3. 提供錯誤日誌和環境信息

## 🔗 相關連結

- [Java 版 MCP Server](https://github.com/yuyuanweb/mcp-mianshiya-server) - 原始參考實現
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - 官方 TypeScript SDK
- [面試鴨平台](https://www.mianshiya.com/) - 面試題庫來源
- [MCP 協議文檔](https://modelcontextprotocol.io/) - 協議官方文檔

---

*本專案非面試鴨官方專案，僅為第三方 MCP 服務器實現。*