MCP Ahrefs

Ahrefs MCP Server for SAAGA

Quick Start with AI Assistant

Need help getting started? Have your AI coding assistant guide you!

Simply tell your AI assistant: "I have a MCP Ahrefs project. Please read and follow WORKING_WITH_SAAGA_PROMPT.md to help me understand and work with this MCP server."

For quick reference, the .ai-prompts.md file contains a condensed version of key patterns.

For detailed technical documentation, see docs/DECORATOR_PATTERNS.md.

Testing with MCP Inspector

Ready to test your MCP server? The MCP Inspector Guide provides:

• Step-by-step setup instructions with virtual environment troubleshooting
• Test examples for all included tools
• JSON mode instructions for parallel tools
• Common issues and solutions

Quick start:

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

Testing with Claude CLI

This project includes a convenient test script for testing your MCP server with Claude:

# 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"

The script automatically:

• Uses the generated mcp.integration_test.json configuration (created by cookiecutter)
• Runs Claude with the Sonnet model
• Includes proper MCP configuration flags
• Provides colored output for better readability

MCP Integration Testing

This project includes comprehensive integration tests that validate tools work correctly with real MCP client interactions:

Running Integration Tests

# 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

What's Tested

The integration tests validate:

• Tool Discovery: All tools are discoverable with correct schemas (no "kwargs" parameters)
• Parameter Conversion: String parameters from MCP are converted to appropriate types
• Error Handling: Invalid parameters and exceptions return proper error responses
• SAAGA Integration: Decorators work correctly in the full MCP protocol flow
• Protocol Compliance: Tools work with real MCP client connections

Generating Tests for New Tools

When you add a new tool, generate integration tests for it:

# 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

Integration vs Unit Tests

• Unit Tests (test_decorators.py): Test SAAGA decorators in isolation
• Integration Tests (test_mcp_integration.py): Test complete MCP protocol flow with real client

Run both test suites to ensure full coverage:

# Run all tests
pytest

# Run only unit tests
pytest tests/test_decorators.py

# Run only integration tests
test-mcp-integration

Overview

This MCP server was generated using the SAAGA MCP Server Cookie Cutter template. It includes:

• FastMCP Integration: Modern MCP framework with dual transport support
• SAAGA Decorators: Automatic exception handling, logging, and parallelization
• Platform-Aware Configuration: Cross-platform configuration management
• Streamlit Admin UI: Web-based configuration and monitoring interface
• SQLite Logging: Comprehensive logging with database persistence

Installation

Prerequisites

• Python 3.12 or higher
• UV - An extremely fast Python package manager

Install from Source

# 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 <your-repository-url>
cd mcp_ahrefs
uv venv
uv sync

Development Installation

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

Usage

Running the MCP Server

The server can be run in two modes:

1. STDIO Mode (for MCP clients like Claude Desktop)

# 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 Mode (for web-based clients)

# 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

Command Line Options

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

Available options:

• --transport: Choose between "stdio" (default) or "sse"
• --host: Host to bind to for SSE transport (default: 127.0.0.1)
• --port: Port to bind to for SSE transport (default: 3001)
• --log-level: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)

MCP Client Configuration

Claude Desktop Configuration

Add the following to your Claude Desktop MCP settings (claude_desktop_config.json):

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

Advanced Configuration Options

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

Using with System Python (Alternative)

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

Using with uv tool

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

Configuration File Locations

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

Admin UI

Launch the Streamlit admin interface:

uv run streamlit run mcp_ahrefs/ui/app.py

Dashboard

The dashboard provides:

• Real-time server status monitoring
• Project information and configuration overview
• Quick access to common actions
• System resource usage

Configuration Editor

The configuration editor features:

• Live configuration editing with validation
• Diff preview showing pending changes
• Export/import functionality (JSON & YAML formats)
• Reset to defaults with confirmation dialog
• Automatic server restart notifications

Log Viewer

The log viewer includes:

• Date range filtering for historical analysis
• Status filtering (success/error/all)
• Tool-specific filtering
• Export capabilities for further analysis
• Real-time log updates

AI Assistant Instructions

When working with this MCP Ahrefs MCP server in an AI coding assistant (like Claude, Cursor, or GitHub Copilot):

Understanding the Server Architecture

This server uses SAAGA decorators that automatically wrap all MCP tools with:

• Exception handling: All errors are caught and returned as structured error responses
• Comprehensive logging: All tool invocations are logged with timing and parameters
• Optional parallelization: Tools marked for parallel execution run concurrently

Key Points for AI Assistants

1. Tool Registration Pattern: Tools are registered with decorators already applied. Do NOT manually wrap tools with decorators - this is handled automatically in server/app.py.

2. Parameter Types: MCP passes all parameters as strings from the client. Ensure your tools handle type conversion:

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

3. Error Handling: Tools can raise exceptions freely - the exception_handler decorator will catch them and return proper error responses.

4. Async Support: Both sync and async tools are supported. The decorators automatically detect and handle both patterns.

5. Logging: Check logs at the platform-specific data directory for debugging:

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

Common Tasks

Adding a new tool:

# 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)

Testing with MCP Inspector:

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

Debugging a tool:

1. Check the SQLite logs for error messages
2. Run with --log-level DEBUG for verbose output
3. Test directly with MCP Inspector to see parameter handling

Important Implementation Notes

• The server uses the standard MCP SDK (from mcp.server.fastmcp import FastMCP)
• Function signatures are preserved through careful decorator implementation
• The register_tools() function in server/app.py handles all decorator application
• Tools should return JSON-serializable Python objects (dict, list, str, int, etc.)

Configuration

Configuration files are stored in platform-specific locations:

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

Configuration Options

• log_level: Logging level (INFO)
• log_retention_days: Days to retain logs (30)
• server_port: HTTP server port (3001)

Development

Project Structure

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

Adding New Tools

1. Create a new Python file in mcp_ahrefs/tools/
2. Define your tool function
3. Import and register it in server/app.py

Example:

# 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

Running Tests

pytest tests/

Code Quality

This project uses several code quality tools:

# Format code
black mcp_ahrefs/
isort mcp_ahrefs/

# Lint code
flake8 mcp_ahrefs/
mypy mcp_ahrefs/

SAAGA Decorators

This server automatically applies three key decorators to your MCP tools:

1. Exception Handler: Graceful error handling with logging
2. Tool Logger: Comprehensive logging to SQLite database
3. Parallelize: Optional parallel processing for compute-intensive tools

Logging

Logs are stored in a SQLite database with the following schema:

• timestamp: When the tool was called
• tool_name: Name of the MCP tool
• duration_ms: Execution time in milliseconds
• status: Success/failure status
• input_args: Tool input arguments
• output_summary: Summary of tool output
• error_message: Error details (if any)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the documentation in the docs/ directory
• Review the test suite for usage examples

Acknowledgments

• FastMCP for the MCP framework
• SAAGA for the decorator patterns
• Cookiecutter for the templating system