ajarbot/MCP_MIGRATION.md

MCP Tools Migration Guide

Overview

Successfully migrated file/system tools to MCP (Model Context Protocol) servers for better performance and integration with Claude Agent SDK.

Architecture

MCP Tools (In-Process - No API Costs)

File: mcp_tools.py Server: file_system (v1.0.0)

These tools run directly in the Python process using the Claude Agent SDK:

• ✅ read_file - Read file contents
• ✅ write_file - Create/overwrite files
• ✅ edit_file - Replace text in files
• ✅ list_directory - List directory contents
• ✅ run_command - Execute shell commands

Benefits:

• Zero per-token API costs when using Agent SDK
• Better performance (no IPC overhead)
• Direct access to application state
• Simpler deployment (single process)

Traditional Tools (API-Based - Consumes Tokens)

File: tools.py

These tools require external APIs and fall back to Direct API even in Agent SDK mode:

• 🌤️ get_weather - OpenWeatherMap API
• 📧 send_email, read_emails, get_email - Gmail API
• 📅 read_calendar, create_calendar_event, search_calendar - Google Calendar API
• 👤 create_contact, list_contacts, get_contact - Google People API

Why not MCP?: These tools need OAuth state, external API calls, and async HTTP clients that are better suited to the traditional tool execution model.

Model Configuration

Agent SDK Mode (DEFAULT)

USE_AGENT_SDK=true  # Default

Model Configuration:

• Default: claude-sonnet-4-5-20250929 (all operations - chat, tools, coding)
• Optional: claude-opus-4-6 (requires USE_OPUS_FOR_TOOLS=true, only for extremely intensive tasks)

Usage:

• Regular chat: Uses Sonnet (flat-rate, no API costs)
• File operations: Uses Sonnet via MCP tools (flat-rate, no API costs)
• Google/Weather: Uses Sonnet via Direct API fallback (requires ANTHROPIC_API_KEY, consumes tokens)
• Intensive tasks: Optionally enable Opus with USE_OPUS_FOR_TOOLS=true (flat-rate, no extra cost)

Cost Structure:

• Chat + MCP tools: Flat-rate subscription (Pro plan)
• Traditional tools (Google/Weather): Pay-per-token at Sonnet rates (requires API key)

Direct API Mode

USE_DIRECT_API=true
Model: claude-sonnet-4-5-20250929  # Cost-effective (never uses Opus - too expensive)

Usage:

• All operations: Pay-per-token
• Requires: ANTHROPIC_API_KEY in .env
• All tools: Traditional execution (same token cost)

Implementation Details

MCP Server Integration

In llm_interface.py:

from mcp_tools import file_system_server

options = ClaudeAgentOptions(
    mcp_servers={"file_system": file_system_server},
    allowed_tools=[
        "read_file", "write_file", "edit_file",
        "list_directory", "run_command"
    ],
)

response = await query(
    messages=sdk_messages,
    max_tokens=max_tokens,
    options=options,
)

Tool Definition Format

MCP Tool Example:

@tool(
    name="read_file",
    description="Read the contents of a file.",
    input_schema={"file_path": str},
)
async def read_file_tool(args: Dict[str, Any]) -> Dict[str, Any]:
    return {
        "content": [{"type": "text", "text": "..."}],
        "isError": False  # Optional
    }

Traditional Tool Example:

{
    "name": "send_email",
    "description": "Send an email from the bot's Gmail account.",
    "input_schema": {
        "type": "object",
        "properties": {"to": {"type": "string"}, ...},
        "required": ["to", "subject", "body"]
    }
}

Future Enhancements

Potential MCP Candidates

• Weather tool (if we cache API responses in-process)
• Memory search tools (direct DB access)
• Configuration management tools

Google Tools Migration (Optional)

To fully migrate Google tools to MCP, we would need to:

1. Embed OAuth manager in MCP server lifecycle
2. Handle async HTTP clients within MCP context
3. Manage token refresh in-process

Recommendation: Keep Google tools as traditional tools for now. The complexity of OAuth state management outweighs the token cost savings for infrequent API calls.

Testing

# Test MCP server creation
python -c "from mcp_tools import file_system_server; print(file_system_server)"

# Test Agent SDK with Opus
python -c "import os; os.environ['USE_AGENT_SDK']='true'; from llm_interface import LLMInterface; llm = LLMInterface(provider='claude'); print(f'Model: {llm.model}')"

# Expected: Model: claude-opus-4-6

References

• Claude Agent SDK Docs: https://github.com/anthropics/claude-agent-sdk
• MCP Protocol: https://modelcontextprotocol.io
• Tool Decorators: claude_agent_sdk.tool, create_sdk_mcp_server