MCP Ahrefs

🚀 MCP Ahrefs

MCP Ahrefs 是用於 SAAGA 的服務器，它藉助先進的框架和工具，為用戶提供便捷、高效且功能豐富的 MCP 服務體驗。

🚀 快速開始

藉助 AI 助手開啟項目

若你在開始使用時需要幫助，可以讓你的 AI 代碼助手來引導你！ 你只需告知你的 AI 助手：“我有一個 MCP Ahrefs 項目。請閱讀並遵循 WORKING_WITH_SAAGA_PROMPT.md 來幫助我理解和使用這個 MCP 服務器。”

如需快速參考，.ai-prompts.md 文件包含了關鍵模式的精簡版本。

如需詳細的技術文檔，請參閱 docs/DECORATOR_PATTERNS.md。

✨ 主要特性

• FastMCP 集成：採用現代 MCP 框架，支持雙傳輸模式。
• SAAGA 裝飾器：具備自動異常處理、日誌記錄和並行處理功能。
• 平臺感知配置：實現跨平臺的配置管理。
• Streamlit 管理界面：提供基於 Web 的配置和監控接口。
• SQLite 日誌記錄：通過數據庫持久化實現全面的日誌記錄。

📦 安裝指南

前提條件

• Python 3.12 或更高版本
• UV - 一個極快的 Python 包管理器

從源代碼安裝

# 安裝 UV（如果尚未安裝）
curl -LsSf https://astral.sh/uv/install.sh | sh  # 在 macOS/Linux 上
# 或者訪問 https://github.com/astral-sh/uv 獲取 Windows 安裝說明

git clone <your-repository-url>
cd mcp_ahrefs
uv venv
uv sync

開發環境安裝

git clone <your-repository-url>
cd mcp_ahrefs
uv venv
uv sync --extra dev

💻 使用示例

運行 MCP 服務器

1. STDIO 模式（適用於如 Claude Desktop 等 MCP 客戶端）

# 使用默認設置運行
uv run python -m mcp_ahrefs.server.app

# 使用自定義日誌級別運行
uv run python -m mcp_ahrefs.server.app --log-level DEBUG

# 直接運行服務器
uv run python mcp_ahrefs/server/app.py

uv run mcp_ahrefs-server

2. SSE 模式（適用於基於 Web 的客戶端）

# 使用 SSE 傳輸運行
uv run python -m mcp_ahrefs.server.app --transport sse --port 3001

# 使用自定義主機和端口運行
uv run python -m mcp_ahrefs.server.app --transport sse --host 0.0.0.0 --port 8080

命令行選項

uv run python -m mcp_ahrefs.server.app --help

可用選項：

• --transport：選擇 "stdio"（默認）或 "sse"
• --host：SSE 傳輸綁定的主機（默認：127.0.0.1）
• --port：SSE 傳輸綁定的端口（默認：3001）
• --log-level：日誌級別 - DEBUG、INFO、WARNING、ERROR（默認：INFO）

MCP 客戶端配置

Claude Desktop 配置

在你的 Claude Desktop MCP 設置 (claude_desktop_config.json) 中添加以下內容：

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_ahrefs.server.app"],
      "cwd": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs"
    }
  }
}

高級配置選項

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": [
        "run", "python", "-m", "mcp_ahrefs.server.app",
        "--log-level", "DEBUG"
      ],
      "cwd": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs",
      "env": {
        "UV_PROJECT_ENVIRONMENT": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs/.venv"
      }
    }
  }
}

使用系統 Python（替代方案）

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "/Users/jakub/Ragnarson/saaga/mcp_ahrefs/.venv/bin/python",
      "args": ["-m", "mcp_ahrefs.server.app"]
    }
  }
}

使用 uv 工具

{
  "mcpServers": {
    "mcp_ahrefs": {
      "command": "uv",
      "args": ["--directory=/Users/jakub/Ragnarson/saaga/mcp_ahrefs", "run" ,"mcp_ahrefs-server"]
    }
  }
}

配置文件位置

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

管理界面

啟動 Streamlit 管理界面：

uv run streamlit run mcp_ahrefs/ui/app.py

儀表盤

儀表盤提供：

• 即時服務器狀態監控
• 項目信息和配置概述
• 快速訪問常用操作
• 系統資源使用情況

配置編輯器

配置編輯器具有：

• 即時配置編輯和驗證
• 顯示待更改的差異預覽
• 導出/導入功能（JSON 和 YAML 格式）
• 確認對話框下的恢復默認設置
• 自動服務器重啟通知

日誌查看器

日誌查看器包括：

• 日期範圍過濾以進行歷史分析
• 狀態過濾（成功/錯誤/全部）
• 特定工具過濾
• 導出功能以進行進一步分析
• 即時日誌更新

📚 詳細文檔

藉助 MCP 檢查器進行測試

準備好測試你的 MCP 服務器了嗎？ MCP 檢查器指南 提供：

• 帶有虛擬環境故障排除的分步設置說明
• 所有包含工具的測試示例
• 並行工具的 JSON 模式說明
• 常見問題和解決方案

快速開始：

source .venv/bin/activate  # 或者使用：uv shell
uv run mcp dev mcp_ahrefs/server/app.py

使用 Claude CLI 進行測試

本項目包含一個方便的測試腳本，用於使用 Claude 測試你的 MCP 服務器：

# 使用簡單提示進行測試
./test_mcp_with_claude.sh "List all available tools"

# 測試特定工具
./test_mcp_with_claude.sh "Run the echo_tool with message 'Hello World'"

# 使用多個工具進行測試
./test_mcp_with_claude.sh "Test calculate_fibonacci with n=10 and echo_tool with message 'Done'"

# 在 Windows 上
.\test_mcp_with_claude.ps1 "List all available tools"

該腳本自動執行以下操作：

• 使用生成的 mcp.integration_test.json 配置（由 cookiecutter 創建）
• 使用 Sonnet 模型運行 Claude
• 包含正確的 MCP 配置標誌
• 提供彩色輸出以提高可讀性

MCP 集成測試

本項目包含全面的集成測試，可驗證工具與真實 MCP 客戶端交互時是否正常工作：

運行集成測試

# 運行所有集成測試
test-mcp-integration

# 運行並輸出詳細信息
test-mcp-integration --verbose

# 測試特定工具
test-mcp-integration --tool echo_tool

# 列出所有可用工具
test-mcp-integration --list

# 也提供跨平臺腳本
./test_mcp_integration.sh        # Unix/Mac
.\test_mcp_integration.ps1        # Windows

測試內容

集成測試驗證：

• 工具發現：所有工具都可通過正確的模式被發現（無 "kwargs" 參數）
• 參數轉換：來自 MCP 的字符串參數會轉換為適當的類型
• 錯誤處理：無效參數和異常會返回正確的錯誤響應
• SAAGA 集成：裝飾器在完整的 MCP 協議流程中正常工作
• 協議合規性：工具與真實 MCP 客戶端連接正常工作

為新工具生成測試

當你添加新工具時，為其生成集成測試：

# 生成測試模板
generate-mcp-tests my_new_tool

# 這將創建一個你可以自定義的測試模板
# 將其添加到 tests/integration/test_mcp_integration.py

集成測試與單元測試

• 單元測試 (test_decorators.py)：單獨測試 SAAGA 裝飾器
• 集成測試 (test_mcp_integration.py)：使用真實客戶端測試完整的 MCP 協議流程

運行兩個測試套件以確保全面覆蓋：

# 運行所有測試
pytest

# 僅運行單元測試
pytest tests/test_decorators.py

# 僅運行集成測試
test-mcp-integration

AI 助手說明

當在 AI 代碼助手（如 Claude、Cursor 或 GitHub Copilot）中使用此 MCP Ahrefs MCP 服務器時：

理解服務器架構

此服務器使用 SAAGA 裝飾器，自動將所有 MCP 工具包裝為：

• 異常處理：捕獲所有錯誤並作為結構化錯誤響應返回
• 全面日誌記錄：記錄所有工具調用的時間和參數
• 可選並行處理：標記為並行執行的工具將併發運行

AI 助手的關鍵點

1. 工具註冊模式：工具已使用裝飾器註冊。請勿手動使用裝飾器包裝工具 - 這在 server/app.py 中自動處理。
2. 參數類型：MCP 從客戶端傳遞所有參數為字符串。確保你的工具處理類型轉換：

def my_tool(count: str) -> dict:
    # 將字符串轉換為整數
    count_int = int(count)
    return {"result": count_int * 2}

3. 錯誤處理：工具可以自由拋出異常 - 異常處理裝飾器將捕獲它們並返回正確的錯誤響應。
4. 異步支持：支持同步和異步工具。裝飾器自動檢測並處理兩種模式。
5. 日誌記錄：在特定平臺的數據目錄中查看日誌以進行調試：

• macOS：~/Library/Application Support/mcp_ahrefs/logs.db
• Linux：~/.local/share/mcp_ahrefs/logs.db
• Windows：%APPDATA%/mcp_ahrefs/logs.db

常見任務

添加新工具：

# 在 mcp_ahrefs/tools/my_new_tool.py 中
def my_new_tool(param: str) -> dict:
    """此工具的功能描述。"""
    # 實現
    return {"result": "processed"}

# 在 mcp_ahrefs/tools/__init__.py 中
from .my_new_tool import my_new_tool
example_tools.append(my_new_tool)

使用 MCP 檢查器進行測試：

# 從項目根目錄
uv run mcp dev mcp_ahrefs/server/app.py

調試工具：

1. 檢查 SQLite 日誌中的錯誤消息
2. 使用 --log-level DEBUG 運行以輸出詳細信息
3. 直接使用 MCP 檢查器測試以查看參數處理情況

配置

配置文件存儲在特定平臺的位置：

• macOS：~/Library/Application Support/mcp_ahrefs/
• Linux：~/.local/share/mcp_ahrefs/
• Windows：%APPDATA%/mcp_ahrefs/

配置選項

• log_level：日誌級別（INFO）
• log_retention_days：日誌保留天數（30）
• server_port：HTTP 服務器端口（3001）

開發

項目結構

mcp_ahrefs/
├── mcp_ahrefs/
│   ├── config.py              # 平臺感知配置
│   ├── server/
│   │   └── app.py             # 帶有裝飾器的 FastMCP 服務器
│   ├── tools/                 # 你的 MCP 工具
│   ├── decorators/            # SAAGA 裝飾器
│   └── ui/                    # Streamlit 管理界面
├── tests/                     # 測試套件
├── docs/                      # 文檔
└── pyproject.toml            # 項目配置

添加新工具

1. 在 mcp_ahrefs/tools/ 中創建一個新的 Python 文件
2. 定義你的工具函數
3. 在 server/app.py 中導入並註冊它

示例：

# mcp_ahrefs/tools/my_tool.py
def my_tool(message: str) -> str:
    """示例 MCP 工具。"""
    return f"Processed: {message}"

# 服務器將自動應用 SAAGA 裝飾器

運行測試

pytest tests/

代碼質量

本項目使用多個代碼質量工具：

# 格式化代碼
black mcp_ahrefs/
isort mcp_ahrefs/

# 代碼檢查
flake8 mcp_ahrefs/
mypy mcp_ahrefs/

SAAGA 裝飾器

此服務器自動將三個關鍵裝飾器應用於你的 MCP 工具：

1. 異常處理程序：優雅的錯誤處理和日誌記錄
2. 工具記錄器：全面記錄到 SQLite 數據庫
3. 並行化：為計算密集型工具提供可選的並行處理

日誌記錄

日誌存儲在 SQLite 數據庫中，具有以下模式：

• timestamp：工具調用的時間
• tool_name：MCP 工具的名稱
• duration_ms：執行時間（毫秒）
• status：成功/失敗狀態
• input_args：工具輸入參數
• output_summary：工具輸出摘要
• error_message：錯誤詳細信息（如果有）

🔧 技術細節

本項目使用 SAAGA MCP 服務器 Cookie Cutter 模板生成，包含了豐富的技術細節和功能實現。服務器採用了 SAAGA 裝飾器，對 MCP 工具進行了自動包裝，實現了異常處理、日誌記錄和並行化等功能。同時，項目還支持多種測試方式，包括 MCP 檢查器測試、Claude CLI 測試以及全面的集成測試和單元測試，確保了工具的穩定性和可靠性。此外，項目的配置管理、代碼質量工具的使用以及跨平臺的支持，都體現了其在技術實現上的嚴謹性和專業性。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

支持

如有問題和疑問：

• 在 GitHub 上創建一個問題
• 查看 docs/ 目錄中的文檔
• 查看測試套件以獲取使用示例

致謝

• FastMCP 提供 MCP 框架
• SAAGA 提供裝飾器模式
• Cookiecutter 提供模板系統