MCP Ahrefs

探索

MCP Ahrefs

MCP Ahrefs是一个基于SAAGA框架的MCP服务器项目，提供工具集成、异常处理、日志记录和并行处理功能，支持通过Claude等客户端进行交互测试。

开发者工具研究与数据 #工具集成 #异常处理 #日志记录 #并行处理 .Python

评分 : 2分

下载量 : 6.7K

更新时间 : 2025-08-11

打开站点

安装

复制以下命令到你的Client进行配置

{
  "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"
      }
    }
  }
}

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

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

注意：您的密钥属于敏感信息，请勿与任何人分享。

🚀 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 助手的关键点

工具注册模式：工具已使用装饰器注册。请勿手动使用装饰器包装工具 - 这在 server/app.py 中自动处理。
参数类型：MCP 从客户端传递所有参数为字符串。确保你的工具处理类型转换：

def my_tool(count: str) -> dict:
    # 将字符串转换为整数
    count_int = int(count)
    return {"result": count_int * 2}

错误处理：工具可以自由抛出异常 - 异常处理装饰器将捕获它们并返回正确的错误响应。
异步支持：支持同步和异步工具。装饰器自动检测并处理两种模式。
日志记录：在特定平台的数据目录中查看日志以进行调试：

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

调试工具：

检查 SQLite 日志中的错误消息
使用 --log-level DEBUG 运行以输出详细信息
直接使用 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            # 项目配置

添加新工具

在 mcp_ahrefs/tools/ 中创建一个新的 Python 文件
定义你的工具函数
在 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 工具：

异常处理程序：优雅的错误处理和日志记录
工具记录器：全面记录到 SQLite 数据库
并行化：为计算密集型工具提供可选的并行处理

日志记录

日志存储在 SQLite 数据库中，具有以下模式：

timestamp：工具调用的时间
tool_name：MCP 工具的名称
duration_ms：执行时间（毫秒）
status：成功/失败状态
input_args：工具输入参数
output_summary：工具输出摘要
error_message：错误详细信息（如果有）

🔧 技术细节

本项目使用 SAAGA MCP 服务器 Cookie Cutter 模板生成，包含了丰富的技术细节和功能实现。服务器采用了 SAAGA 装饰器，对 MCP 工具进行了自动包装，实现了异常处理、日志记录和并行化等功能。同时，项目还支持多种测试方式，包括 MCP 检查器测试、Claude CLI 测试以及全面的集成测试和单元测试，确保了工具的稳定性和可靠性。此外，项目的配置管理、代码质量工具的使用以及跨平台的支持，都体现了其在技术实现上的严谨性和专业性。