MCP Ahrefs

# AI Assistant Context for MCP Ahrefs ## Quick Start for AI Assistants This is an MCP (Model Context Protocol) server built with SAAGA decorators. Here's what you need to know: ### Architecture Overview ``` MCP Client (Claude/Cursor) → MCP Server → SAAGA Decorators → Your Tools ``` ### Key Concepts 1. **Automatic Decorators**: All tools are automatically wrapped with: - `@exception_handler` - Catches errors and returns structured responses - `@tool_logger` - Logs execution with timing to SQLite - `@parallelize` - ONLY for tools in `parallel_example_tools` 2. **Function Signatures Are Preserved**: Unlike typical decorator patterns, these preserve the original function signatures for MCP introspection. 3. **String Parameters**: MCP passes all parameters as strings. Your tools must handle conversion. ### Common Tasks #### Adding a New Regular Tool ```python # In mcp_ahrefs/tools/my_tools.py def my_new_tool(input_text: str) -> dict: """Process text and return results.""" # Convert parameters if needed return {"result": input_text.upper()} # In mcp_ahrefs/tools/__init__.py from .my_tools import my_new_tool example_tools.append(my_new_tool) ``` #### Adding a Parallel Processing Tool ```python # ONLY for batch/independent operations! def batch_processor(items: List[str]) -> List[dict]: """Process multiple items independently.""" return [process_item(item) for item in items] # In tools/__init__.py parallel_example_tools.append(batch_processor) ``` #### Testing Tools ```bash # Use MCP Inspector mcp dev # Check logs sqlite3 ~/Library/Application\ Support/mcp_ahrefs/logs.db ``` ### Important Implementation Details 1. **Do NOT manually apply decorators** - The server does this automatically 2. **Do NOT create wrapper functions** - This breaks parameter introspection 3. **Do NOT use `**kwargs`** in tool signatures - Use explicit parameters 4. **Do NOT parallelize sequential operations** - Only independent batch operations ### File Locations - **Tools**: `mcp_ahrefs/tools/` - **Server**: `mcp_ahrefs/server/app.py` - **Decorators**: `mcp_ahrefs/decorators/` - **Config**: Platform-specific (see README) - **Logs**: Platform-specific SQLite database ### Debugging Issues 1. **"kwargs" in MCP Inspector**: Function signature is hidden by wrapper 2. **Type errors**: Remember to convert string parameters 3. **Parallel tool not working**: Check if it's in `parallel_example_tools` 4. **Decorator not applied**: Check tool registration in `app.py` ### Error Handling Tools can raise exceptions freely: ```python def my_tool(value: str) -> dict: if not value: raise ValueError("Value required") # Decorator handles this return {"processed": value} ``` The exception handler will catch and format the error for MCP clients. ### Quick Reference - **Decorator Order**: exception_handler → tool_logger → parallelize → function - **Transport Modes**: STDIO (for desktop clients) or SSE (for web) - **Testing**: Use `mcp dev` for MCP Inspector - **Logs**: Check SQLite database for execution history For more details, see `docs/DECORATOR_PATTERNS.md`.