pixi-task: Instructions file for Claude Code

Lean MCP Server Implementation Framework

Overview

This document provides a comprehensive framework for implementing "Lean MCP Servers" - a revolutionary approach to MCP server development that reduces context consumption by 95%+ while maintaining 100% functionality through the meta-tool pattern.

🚨 CRITICAL PROBLEM SOLVED

Traditional MCP Server Issue:

• Each MCP server exposes 10-50 verbose tool definitions
• Context consumption: 20-50K tokens per server
• With 10+ servers: 200K+ tokens just for tool definitions
• Result: Agents hit context limits before any real work begins

Lean MCP Solution:

• Expose only 3 meta-tools instead of 10+ verbose tools
• Context consumption: ~500 tokens per server (95%+ reduction)
• With 10+ servers: ~5K tokens total
• Result: Agents can focus on actual work, not parsing tool definitions

Architecture Pattern: Meta-Tool Discovery

The Three Meta-Tools

Every Lean MCP server exposes exactly these 3 meta-tools:

{
  "discover_tools": {
    "description": "Get available tools with minimal context consumption",
    "parameters": {"pattern": "string"}
  },
  "get_tool_spec": {
    "description": "Get full specification for specific tool", 
    "parameters": {"tool_name": "string"}
  },
  "execute_tool": {
    "description": "Execute tool with parameters",
    "parameters": {"tool_name": "string", "parameters": "object"}
  }
}

Context Impact: ~500 tokens total (vs 20-50K for traditional)

Agent Workflow Pattern

# Step 1: Discover relevant tools (minimal context)
tools = mcp_server.discover_tools(pattern="session")
# Context: ~150 tokens

# Step 2: Get specification for chosen tool (on-demand)
spec = mcp_server.get_tool_spec("session_track_execution") 
# Context: ~300 tokens

# Step 3: Execute tool with parameters
result = mcp_server.execute_tool("session_track_execution", {
    "agent_name": "test-runner",
    "step_data": {"phase": "start", "command": "pytest"}
})
# Context: Standard execution

# Total Context: ~500 tokens (vs 20-50K traditional)