MCP Ahrefs

MCP Ahrefs

用于SAAGA的Ahrefs MCP服务器

快速开始使用AI助手

需要帮助开始吗？ 让你的AI编码助手指导你！

只需告诉你的AI助手： *“我有一个MCP Ahrefs项目。请阅读并关注 工作环境_工作环境\_ AAGA_PROMPT.md 以帮助我理解和使用此MCP服务器。"*

供快速参考，the .ai-prompts.md 该文件包含密钥模式的压缩版本。

详细的技术文档，请参阅 docs/DECORATOR_PATTERNS.md.

MCP检验员测试

准备好测试您的MCP服务器了吗？ 这 MCP检查员指南 提供：

• 虚拟环境故障排除的分步设置说明
• 所有包含工具的测试示例
• 并行工具的JSON模式指令
• 常见问题和解决方案

快速启动：

source .venv/bin/activate  # Or use: uv shell
uv run mcp dev mcp_ahrefs/server/app.py

使用Claude CLI进行测试

此项目包括一个方便的测试脚本，用于使用Claude测试您的MCP服务器：

# Test with a simple prompt
./test_mcp_with_claude.sh "List all available tools"

# Test a specific tool
./test_mcp_with_claude.sh "Run the echo_tool with message 'Hello World'"

# Test with multiple tools
./test_mcp_with_claude.sh "Test calculate_fibonacci with n=10 and echo_tool with message 'Done'"

# On Windows
.\test_mcp_with_claude.ps1 "List all available tools"

脚本会自动执行以下操作：

• 使用生成的 mcp.integration_test.json 配置（由cookiecutter创建）
• 用Sonnet模型运行Claude
• 包括正确的MCP配置标志
• 提供彩色输出以提高可读性

MCP集成测试

该项目包括全面的集成测试，验证工具在真实的MCP客户端交互中是否正常工作：

运行集成测试

# Run all integration tests
test-mcp-integration

# Run with verbose output
test-mcp-integration --verbose

# Test specific tool
test-mcp-integration --tool echo_tool

# List all available tools
test-mcp-integration --list

# Cross-platform scripts also available
./test_mcp_integration.sh        # Unix/Mac
.\test_mcp_integration.ps1        # Windows

测试内容

集成测试验证：

• 工具发现：所有工具都可以通过正确的模式发现（没有“kwargs”参数）
• 参数转换：MCP中的字符串参数被转换为适当的类型
• 错误处理：无效参数和异常返回正确的错误响应
• SAAGA集成：装饰器在完整的MCP协议流中正常工作
• 协议遵从：工具适用于真实的MCP客户端连接

为新工具生成测试

添加新工具时，为其生成集成测试：

# Generate test template
generate-mcp-tests my_new_tool

# This creates a test template you can customize
# Add it to tests/integration/test_mcp_integration.py

集成与单元测试

• 单元测试 (test_decorators.py)：单独测试SAAGA装饰器
• 集成测试 (test_mcp_integration.py)：使用真实客户端测试完整的MCP协议流

运行两个测试套件以确保完全覆盖：

# Run all tests
pytest

# Run only unit tests
pytest tests/test_decorators.py

# Run only integration tests
test-mcp-integration

概述

此MCP服务器是使用SAAGA MCP服务器Cookie切割器模板生成的。它包括：

• FastMCP集成：具有双传输支持的现代MCP框架
• SAAGA装饰：自动异常处理、日志记录和并行化
• 平台感知配置：跨平台配置管理
• 流线型管理界面：基于Web的配置和监控界面
• SQLite日志记录：具有数据库持久性的全面日志记录

安装

先决条件

• Python 3.12或更高版本
• 紫外线的 -一个速度极快的Python包管理器

从源代码安装

# Install UV (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh  # On macOS/Linux
# Or visit https://github.com/astral-sh/uv for Windows instructions

git clone 
cd mcp_ahrefs
uv venv
uv sync

开发安装

git clone 
cd mcp_ahrefs
uv venv
uv sync --extra dev

用法

运行MCP服务器

服务器可以在两种模式下运行：

1.STDIO模式（适用于Claude Desktop等MCP客户端）

# Run with default settings
uv run python -m mcp_ahrefs.server.app

# Run with custom log level
uv run python -m mcp_ahrefs.server.app --log-level DEBUG

# Run the server directly
uv run python mcp_ahrefs/server/app.py

uv run mcp_ahrefs-server

2.SSE模式（适用于基于网络的客户端）

# Run with SSE transport
uv run python -m mcp_ahrefs.server.app --transport sse --port 3001

# Run with custom host and port
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：日志记录级别-调试、信息、警告、错误（默认值：信息）

MCP客户端配置

Claude桌面配置

将以下内容添加到您的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
• 视窗: %APPDATA%/Claude/claude_desktop_config.json

管理用户界面

启动Streamlit管理界面：

uv run streamlit run mcp_ahrefs/ui/app.py

仪表盘

Streamlit Admin UI Dashboard

仪表板提供：

• 实时服务器状态监控
• 项目信息和配置概述
• 快速访问常见操作
• 系统资源使用情况

配置编辑器

Streamlit Admin UI Configuration

配置编辑器具有以下功能：

• 实时配置编辑与验证
• 显示待定更改的差异预览
• 导出/导入功能（JSON和YAML格式）
• 通过确认对话框重置为默认值
• 自动服务器重启通知

日志查看器

Streamlit Admin UI Logs

日志查看器包括：

• 历史分析的日期范围过滤
• 状态筛选（成功/错误/全部）
• 工具特定过滤
• 出口能力以供进一步分析
• 实时日志更新

AI助手说明

在AI编码助手（如Claude、Cursor或GitHub Copilot）中使用此MCP Ahrefs MCP服务器时：

了解服务器体系结构

此服务器使用SAAGA装饰器，自动将所有MCP工具包装为：

• 异常处理：所有错误都会被捕获并作为结构化错误响应返回
• 综合录井：所有工具调用都记录了时间和参数
• 可选并行化：标记为并行执行的工具同时运行

AI助手的关键点

1. 工具注册模式：工具已向已应用的装饰器注册。不要用装饰器手动包装工具——这是在中自动处理的 server/app.py.

1. 参数类型：MCP将所有参数作为字符串从客户端传递。确保您的工具处理类型转换：

   def my_tool(count: str) -> dict:
       # Convert string to int
       count_int = int(count)
       return {"result": count_int * 2}

1. 错误处理：工具可以自由地引发异常——exception_handler装饰器将捕获它们并返回正确的错误响应。

1. 异步支持：支持同步和异步工具。装饰器会自动检测和处理这两种模式。

1. 日志记录：检查平台特定数据目录中的日志以进行调试：

- macOS： ~/Library/Application Support/mcp_ahrefs/logs.db - Linux： ~/.local/share/mcp_ahrefs/logs.db - 窗户： %APPDATA%/mcp_ahrefs/logs.db

常见任务

添加新工具：

# In mcp_ahrefs/tools/my_new_tool.py
def my_new_tool(param: str) -> dict:
    """Description of what this tool does."""
    # Implementation
    return {"result": "processed"}

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

MCP检验员测试：

# From the project root
uv run mcp dev mcp_ahrefs/server/app.py

调试工具：

1. 检查SQLite日志中的错误消息
2. 与一起跑步 --log-level DEBUG 用于详细输出
3. 直接与MCP检查员进行测试，查看参数处理情况

重要实施注意事项

• 服务器使用标准MCP SDK(from mcp.server.fastmcp import FastMCP)
• 通过仔细的装饰器实现来保留函数签名
• 这 register_tools() 功能在 server/app.py 处理所有装饰器应用程序
• 工具应该返回JSON可序列化的Python对象（dict、list、str、int等）

配置

配置文件存储在平台特定的位置：

• macOS: ~/Library/Application Support/mcp_ahrefs/
• Linux: ~/.local/share/mcp_ahrefs/
• 视窗: %APPDATA%/mcp_ahrefs/

配置选项

• log_level：日志记录级别（INFO）
• log_retention_days：保留日志的天数（30）
• server_port：HTTP服务器端口（3001）

发展

项目结构

mcp_ahrefs/
├── mcp_ahrefs/
│   ├── config.py              # Platform-aware configuration
│   ├── server/
│   │   └── app.py             # FastMCP server with decorators
│   ├── tools/                 # Your MCP tools
│   ├── decorators/            # SAAGA decorators
│   └── ui/                    # Streamlit admin UI
├── tests/                     # Test suite
├── docs/                      # Documentation
└── pyproject.toml            # Project configuration

添加新工具

1. 在中创建一个新的Python文件 mcp_ahrefs/tools/
2. 定义您的工具功能
3. 导入并注册 server/app.py

例子：

# mcp_ahrefs/tools/my_tool.py
def my_tool(message: str) -> str:
    """Example MCP tool."""
    return f"Processed: {message}"

# The server will automatically apply SAAGA decorators

运行测试

pytest tests/

代码质量

此项目使用了几个代码质量工具：

# Format code
black mcp_ahrefs/
isort mcp_ahrefs/

# Lint code
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：错误详细信息（如有）

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 运行测试套件
6. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

• 在GitHub上创建问题
• 查看文档 docs/ 目录
• 查看测试套件中的使用示例

致谢

• FastMCP 对于MCP框架
• 萨加 用于装饰图案
• 厨师切菜机 对于模板系统