apifox-mcp-server 0.1.2
Apifox MCP Server - Expose Apifox API documentation to MCP clients
License: MIT
Requires Python: >=3.12

# Apifox MCP 伺服器

一個模型上下文協議（MCP）伺服器，將 Apifox API 文檔暴露給 MCP 客戶端，如 Cursor 和 Claude Desktop。此 Python 實現支援 `uvx` 安裝，並使用環境變數進行配置。

## 🎯 功能特色

- **簡易安裝**：使用 `uvx` 安裝和執行 - 無需手動設定
- **環境變數配置**：使用 `APIFOX_PROJECT_ID` 和 `APIFOX_ACCESS_TOKEN` 進行配置
- **全面的 API 存取**：存取所有 API 端點、資料夾和結構描述
- **智慧快取**：內建快取機制，可配置 TTL
- **搜尋功能**：按名稱、描述、路徑或標籤搜尋 API
- **資源瀏覽**：透過 MCP 資源瀏覽專案結構
- **錯誤處理**：強健的錯誤處理和日誌記錄

## 🚀 快速開始

### 前置需求

- Python 3.10 或更高版本
- 已安裝 `uvx`（推薦）或 `pip`
- 具有 API 存取權限的 Apifox 帳戶

### 使用 uvx 安裝（推薦）

```bash
# 使用 uvx 直接安裝和執行
uvx apifox-mcp-server
```

### 使用 pip 安裝

```bash
# 從 PyPI 安裝
pip install apifox-mcp-server

# 執行伺服器
apifox-mcp-server
```

## 🔧 配置設定

### 環境變數

設定以下環境變數：

```bash
# 必需
export APIFOX_ACCESS_TOKEN="your-access-token-here"
export APIFOX_PROJECT_ID="your-project-id-here"

# 可選
export APIFOX_API_BASE_URL="https://api.apifox.com"  # 預設值
```

### 取得您的憑證

1. **存取權杖**：
   - 開啟 Apifox
   - 將滑鼠懸停在右上角的頭像上
   - 點擊「帳號設定」→「API 存取權杖」
   - 建立新的 API 存取權杖

2. **專案 ID**：
   - 開啟您的 Apifox 專案
   - 點擊左側邊欄的「專案設定」
   - 從「基本設定」頁面複製專案 ID

## 🔌 MCP 客戶端配置

### Cursor

將以下內容新增到您的 `~/.cursor/mcp.json` 或 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "Apifox API Documentation": {
      "command": "uvx",
      "args": ["apifox-mcp-server@latest"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "your-access-token",
        "APIFOX_PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

### Claude Desktop

將以下內容新增到您的 MCP 配置：

```json
{
  "mcpServers": {
    "apifox": {
      "command": "uvx",
      "args": ["apifox-mcp-server@latest"],
      "env": {
        "APIFOX_ACCESS_TOKEN": "your-access-token",
        "APIFOX_PROJECT_ID": "your-project-id"
      }
    }
  }
}
```

### VSCode 搭配 Cline

1. 開啟 Cline 面板
2. 前往 MCP Server → Configure MCP Server
3. 新增上述配置

## 🛠️ 可用工具

MCP 伺服器提供以下工具：

- **`get_project_info`**：取得基本專案資訊
- **`list_api_endpoints`**：列出所有 API 端點，支援可選篩選
- **`get_api_detail`**：取得特定 API 的詳細資訊
- **`list_folders`**：列出專案中的所有資料夾
- **`list_schemas`**：列出所有資料結構描述/模型
- **`search_apis`**：按名稱、描述、路徑或標籤搜尋 API
- **`refresh_cache`**：清除快取以強制取得新資料

## 📚 可用資源

- **`apifox://project`**：專案概覽和資訊
- **`apifox://endpoints`**：按資料夾組織的完整 API 端點清單

## 💡 使用範例

### 搭配 AI 助手

1. **從 API 文檔生成程式碼**：
   ```
   "使用 Apifox MCP 取得使用者 API 端點，並為所有模型生成 TypeScript 介面"
   ```

2. **搜尋特定 API**：
   ```
   "在 Apifox 專案中搜尋所有與身份驗證相關的 API"
   ```

3. **生成 API 客戶端程式碼**：
   ```
   "取得使用者登入 API 的詳細資訊，並生成 Python 客戶端函數"
   ```

### 直接工具使用

```python
# 取得專案資訊
await get_project_info()

# 列出所有 GET 端點
await list_api_endpoints(method="GET")

# 搜尋與使用者相關的 API
await search_apis("user", "name,path")

# 取得詳細的 API 資訊
await get_api_detail("api-id-here")
```

## 🔄 快取管理

伺服器包含智慧快取功能：

- **預設 TTL**：1 小時（3600 秒）
- **自動過期**：舊的快取項目會自動移除
- **手動重新整理**：使用 `refresh_cache` 工具清除快取
- **按請求快取**：每個 API 端點都會分別快取

## 🐛 疑難排解

### 常見問題

1. **「需要 APIFOX_ACCESS_TOKEN 環境變數」**
   - 確保您已設定 `APIFOX_ACCESS_TOKEN` 環境變數
   - 驗證權杖有效且具有必要的權限

2. **「需要 APIFOX_PROJECT_ID 環境變數」**
   - 設定 `APIFOX_PROJECT_ID` 環境變數
   - 確保專案 ID 正確

3. **「無法取得專案資訊」**
   - 檢查您的網路連線
   - 驗證 API 基礎 URL 是否正確
   - 確保您的存取權杖有權限存取該專案

4. **快取問題**
   - 使用 `refresh_cache` 工具清除過時資料
   - 檢查 Apifox 中的 API 資料是否已更新

### 除錯模式

設定 `MCP_DEBUG` 環境變數以啟用詳細日誌記錄：

```bash
export MCP_DEBUG=true
uvx apifox-mcp-server
```

## 🤝 貢獻

歡迎貢獻！請隨時提交 Pull Request。

## 📄 授權條款

此專案採用 MIT 授權條款 - 詳情請參閱 LICENSE 檔案。

## 🙏 致謝

- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP 框架
- [Apifox](https://apifox.com) - API 文檔平台
- [Model Context Protocol](https://modelcontextprotocol.io) - 協議規範