kicad-mcp-server/docs/mcp-router-guide.md

# MCP Tool Router Pattern Guide

A practical guide for building MCP servers with 50-500+ tools without destroying context windows or confusing the LLM.

---

## The Problem

When your MCP server exposes too many tools:

1. **Token bloat**: 50 tools ≈ 30-50K tokens consumed before the user says anything
2. **Selection errors**: Claude sees `add_component`, `place_component`, `add_footprint`, `place_footprint` and guesses wrong
3. **Context starvation**: Less room for actual conversation and results
4. **Accuracy degradation**: More tools = more confusion about which to use

Real-world example: A KiCAD MCP server with 52 tools consumes ~40K tokens. An IDA Pro MCP server could easily hit 100+ tools.

---

## Solution Overview

Implement a **router pattern** within your MCP server that:

1. Exposes only essential tools directly (10-15 tools)
2. Provides discovery tools for everything else
3. Routes execution through a single `execute_tool` endpoint

**Result**: Claude sees ~18 tools instead of 100+, but can still access everything.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     MCP Client (Claude)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Your MCP Server                         │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              DIRECT TOOLS (Always Visible)              ││
│  │  • create_project    • open_project    • save_project   ││
│  │  • add_component     • add_track       • get_info       ││
│  │  • (10-15 high-frequency tools)                         ││
│  └─────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────┐│
│  │                    ROUTER TOOLS                         ││
│  │  • list_tool_categories   • get_category_tools          ││
│  │  • execute_tool           • search_tools                ││
│  └─────────────────────────────────────────────────────────┘│
│                              │                               │
│                              ▼                               │
│  ┌─────────────────────────────────────────────────────────┐│
│  │              ROUTED TOOLS (Hidden)                      ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   ││
│  │  │  export  │ │   drc    │ │  zones   │ │ advanced │   ││
│  │  │ (8 tools)│ │(5 tools) │ │(6 tools) │ │(12 tools)│   ││
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘   ││
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐                ││
│  │  │schematic │ │  layers  │ │ graphics │  ... more      ││
│  │  │(15 tools)│ │(4 tools) │ │(10 tools)│                ││
│  │  └──────────┘ └──────────┘ └──────────┘                ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
```

---

## Implementation

### Step 1: Define Your Tool Registry

Create a central registry that organizes all tools by category.

```typescript
// src/tools/registry.ts

export interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: {
    type: "object";
    properties: Record<string, unknown>;
    required?: string[];
  };
  handler: (params: any) => Promise<any>;
}

export interface ToolCategory {
  name: string;
  description: string;
  tools: ToolDefinition[];
}

// Define all your categories
export const toolCategories: ToolCategory[] = [
  {
    name: "export",
    description: "Generate output files: Gerber, drill, BOM, PDF, 3D models (STEP/VRML), SVG",
    tools: [
      {
        name: "export_gerber",
        description: "Export Gerber files for PCB fabrication",
        inputSchema: {
          type: "object",
          properties: {
            output_dir: {
              type: "string",
              description: "Output directory path",
            },
            layers: {
              type: "array",
              items: { type: "string" },
              description: "Layers to export (default: all copper + silkscreen + mask)",
            },
            format: {
              type: "string",
              enum: ["rs274x", "x2"],
              description: "Gerber format version",
            },
          },
          required: ["output_dir"],
        },
        handler: async (params) => {
          // Your implementation
          return { success: true, files: ["..."] };
        },
      },
      {
        name: "export_drill",
        description: "Export Excellon drill files",
        inputSchema: {
          type: "object",
          properties: {
            output_dir: { type: "string" },
            format: { type: "string", enum: ["excellon", "excellon2"] },
          },
          required: ["output_dir"],
        },
        handler: async (params) => {
          /* ... */
        },
      },
      {
        name: "export_bom",
        description: "Export bill of materials as CSV or XML",
        inputSchema: {
          /* ... */
        },
        handler: async (params) => {
          /* ... */
        },
      },
      // ... more export tools
    ],
  },
  {
    name: "drc",
    description:
      "Design rule checking: clearance validation, electrical rules, manufacturing constraints",
    tools: [
      {
        name: "run_drc",
        description: "Run full design rule check on current board",
        inputSchema: {
          type: "object",
          properties: {
            report_all: {
              type: "boolean",
              description: "Report all violations or stop at first",
            },
          },
        },
        handler: async (params) => {
          /* ... */
        },
      },
      {
        name: "get_drc_errors",
        description: "Get current DRC violations without re-running check",
        inputSchema: { type: "object", properties: {} },
        handler: async (params) => {
          /* ... */
        },
      },
      {
        name: "set_design_rules",
        description: "Configure design rules: clearance, track width, via size, etc.",
        inputSchema: {
          type: "object",
          properties: {
            min_clearance: { type: "number", description: "Minimum clearance in mm" },
            min_track_width: { type: "number", description: "Minimum track width in mm" },
            min_via_diameter: { type: "number", description: "Minimum via diameter in mm" },
            min_via_drill: { type: "number", description: "Minimum via drill size in mm" },
          },
        },
        handler: async (params) => {
          /* ... */
        },
      },
    ],
  },
  {
    name: "zones",
    description: "Copper zones/pours: ground planes, power fills, keep-out areas",
    tools: [
      {
        name: "add_zone",
        description: "Add copper zone/pour to PCB",
        inputSchema: {
          type: "object",
          properties: {
            net_name: { type: "string", description: "Net to connect (e.g., 'GND', 'VCC')" },
            layer: { type: "string", description: "Layer name (e.g., 'F.Cu', 'B.Cu')" },
            points: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  x: { type: "number" },
                  y: { type: "number" },
                },
              },
              description: "Polygon vertices in mm",
            },
            priority: { type: "number", description: "Fill priority (higher fills first)" },
          },
          required: ["net_name", "layer", "points"],
        },
        handler: async (params) => {
          /* ... */
        },
      },
      {
        name: "fill_zones",
        description: "Recalculate and fill all copper zones",
        inputSchema: { type: "object", properties: {} },
        handler: async (params) => {
          /* ... */
        },
      },
      {
        name: "remove_zone",
        description: "Remove a copper zone by ID",
        inputSchema: {
          type: "object",
          properties: {
            zone_id: { type: "string", description: "Zone identifier" },
          },
          required: ["zone_id"],
        },
        handler: async (params) => {
          /* ... */
        },
      },
    ],
  },
  // Add more categories...
];
```

### Step 2: Build Lookup Maps

Create efficient lookups for routing.

```typescript
// src/tools/registry.ts (continued)

// Build lookup maps at module load time
const categoryMap = new Map<string, ToolCategory>();
const toolMap = new Map<string, { category: string; tool: ToolDefinition }>();

export function initializeRegistry() {
  for (const category of toolCategories) {
    categoryMap.set(category.name, category);
    for (const tool of category.tools) {
      toolMap.set(tool.name, { category: category.name, tool });
    }
  }
}

export function getCategory(name: string): ToolCategory | undefined {
  return categoryMap.get(name);
}

export function getTool(name: string): { category: string; tool: ToolDefinition } | undefined {
  return toolMap.get(name);
}

export function getAllCategories(): ToolCategory[] {
  return toolCategories;
}

export function searchTools(query: string): Array<{
  category: string;
  tool: string;
  description: string;
}> {
  const q = query.toLowerCase();
  const matches: Array<{ category: string; tool: string; description: string }> = [];

  for (const category of toolCategories) {
    for (const tool of category.tools) {
      if (
        tool.name.toLowerCase().includes(q) ||
        tool.description.toLowerCase().includes(q) ||
        category.name.toLowerCase().includes(q)
      ) {
        matches.push({
          category: category.name,
          tool: tool.name,
          description: tool.description,
        });
      }
    }
  }

  return matches;
}

// Initialize on load
initializeRegistry();
```

### Step 3: Create Router Tools

These are the tools that enable discovery and execution.

```typescript
// src/tools/router.ts

import { getAllCategories, getCategory, getTool, searchTools } from "./registry.js";

export const routerTools = {
  list_tool_categories: {
    name: "list_tool_categories",
    description:
      "List all available tool categories. Use this to discover what operations " +
      "are available beyond the basic tools exposed directly.",
    inputSchema: {
      type: "object" as const,
      properties: {},
      required: [],
    },
    handler: async () => {
      const categories = getAllCategories();
      return {
        total_categories: categories.length,
        total_tools: categories.reduce((sum, c) => sum + c.tools.length, 0),
        categories: categories.map((c) => ({
          name: c.name,
          description: c.description,
          tool_count: c.tools.length,
        })),
      };
    },
  },

  get_category_tools: {
    name: "get_category_tools",
    description:
      "Get detailed information about tools in a specific category, " +
      "including their parameters. Use after list_tool_categories to " +
      "see what's available in a category.",
    inputSchema: {
      type: "object" as const,
      properties: {
        category: {
          type: "string",
          description: "Category name from list_tool_categories",
        },
      },
      required: ["category"],
    },
    handler: async (params: { category: string }) => {
      const category = getCategory(params.category);
      if (!category) {
        return {
          error: `Unknown category: ${params.category}`,
          available_categories: getAllCategories().map((c) => c.name),
        };
      }
      return {
        category: category.name,
        description: category.description,
        tools: category.tools.map((t) => ({
          name: t.name,
          description: t.description,
          parameters: t.inputSchema,
        })),
      };
    },
  },

  execute_tool: {
    name: "execute_tool",
    description:
      "Execute a tool from any category. First use list_tool_categories " +
      "and get_category_tools to discover available tools and their parameters.",
    inputSchema: {
      type: "object" as const,
      properties: {
        tool_name: {
          type: "string",
          description: "Tool name (from get_category_tools)",
        },
        params: {
          type: "object",
          description: "Tool parameters (see get_category_tools for schema)",
        },
      },
      required: ["tool_name"],
    },
    handler: async (input: { tool_name: string; params?: Record<string, unknown> }) => {
      const entry = getTool(input.tool_name);
      if (!entry) {
        return {
          error: `Unknown tool: ${input.tool_name}`,
          hint: "Use list_tool_categories and get_category_tools to find available tools",
        };
      }

      try {
        const result = await entry.tool.handler(input.params || {});
        return {
          tool: input.tool_name,
          category: entry.category,
          result,
        };
      } catch (err) {
        return {
          error: `Tool execution failed: ${(err as Error).message}`,
          tool: input.tool_name,
          category: entry.category,
        };
      }
    },
  },

  search_tools: {
    name: "search_tools",
    description:
      "Search for tools by keyword across all categories. " +
      "Useful when you know what you want to do but not which category it's in.",
    inputSchema: {
      type: "object" as const,
      properties: {
        query: {
          type: "string",
          description: "Search term (e.g., 'gerber', 'zone', 'differential', 'export')",
        },
      },
      required: ["query"],
    },
    handler: async (params: { query: string }) => {
      const matches = searchTools(params.query);
      return {
        query: params.query,
        count: matches.length,
        matches: matches.slice(0, 20), // Limit results
      };
    },
  },
};
```

### Step 4: Define Direct Tools

These are your high-frequency tools that stay visible always.

```typescript
// src/tools/direct.ts

import { ToolDefinition } from "./registry.js";

// These tools are ALWAYS visible to Claude - no routing needed
// Pick your 10-15 most common operations

export const directTools: ToolDefinition[] = [
  // === PROJECT LIFECYCLE ===
  {
    name: "create_project",
    description: "Create a new project with initial files and configuration",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Project name" },
        path: { type: "string", description: "Directory path for project" },
        template: {
          type: "string",
          description: "Optional template to use",
          enum: ["blank", "arduino", "raspberry-pi"],
        },
      },
      required: ["name", "path"],
    },
    handler: async (params) => {
      // Implementation
      return { success: true, project_path: `${params.path}/${params.name}` };
    },
  },
  {
    name: "open_project",
    description: "Open an existing project",
    inputSchema: {
      type: "object",
      properties: {
        path: { type: "string", description: "Path to project file or directory" },
      },
      required: ["path"],
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "save_project",
    description: "Save all project files",
    inputSchema: {
      type: "object",
      properties: {},
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "get_project_info",
    description: "Get current project information: path, files, status",
    inputSchema: {
      type: "object",
      properties: {},
    },
    handler: async (params) => {
      /* ... */
    },
  },

  // === PRIMARY OPERATIONS (your core workflow) ===
  {
    name: "add_component",
    description: "Add a component at specified position",
    inputSchema: {
      type: "object",
      properties: {
        type: { type: "string", description: "Component type or library reference" },
        reference: { type: "string", description: "Reference designator (e.g., R1, U1)" },
        x: { type: "number", description: "X position" },
        y: { type: "number", description: "Y position" },
        rotation: { type: "number", description: "Rotation in degrees", default: 0 },
      },
      required: ["type", "reference", "x", "y"],
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "move_component",
    description: "Move a component to new position",
    inputSchema: {
      type: "object",
      properties: {
        reference: { type: "string", description: "Component reference (e.g., R1)" },
        x: { type: "number", description: "New X position" },
        y: { type: "number", description: "New Y position" },
      },
      required: ["reference", "x", "y"],
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "list_components",
    description: "List all components with their positions and properties",
    inputSchema: {
      type: "object",
      properties: {
        filter: { type: "string", description: "Optional filter (e.g., 'R*' for resistors)" },
      },
    },
    handler: async (params) => {
      /* ... */
    },
  },

  // === SECONDARY OPERATIONS (still common) ===
  {
    name: "add_connection",
    description: "Add a connection/trace between two points",
    inputSchema: {
      type: "object",
      properties: {
        start: {
          type: "object",
          properties: { x: { type: "number" }, y: { type: "number" } },
        },
        end: {
          type: "object",
          properties: { x: { type: "number" }, y: { type: "number" } },
        },
        net: { type: "string", description: "Net name" },
      },
      required: ["start", "end"],
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "list_nets",
    description: "List all nets/connections",
    inputSchema: {
      type: "object",
      properties: {},
    },
    handler: async (params) => {
      /* ... */
    },
  },
  {
    name: "get_info",
    description: "Get general information about current state",
    inputSchema: {
      type: "object",
      properties: {},
    },
    handler: async (params) => {
      /* ... */
    },
  },
];
```

### Step 5: Register with MCP Server

Wire everything together in your main server file.

```typescript
// src/index.ts

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

import { directTools } from "./tools/direct.js";
import { routerTools } from "./tools/router.js";
import { initializeRegistry } from "./tools/registry.js";

// Initialize the tool registry
initializeRegistry();

const server = new Server(
  {
    name: "your-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  },
);

// Combine all visible tools
const allVisibleTools = [...directTools, ...Object.values(routerTools)];

// Build a handler map for quick lookup
const toolHandlers = new Map<string, (params: any) => Promise<any>>();

for (const tool of directTools) {
  toolHandlers.set(tool.name, tool.handler);
}
for (const tool of Object.values(routerTools)) {
  toolHandlers.set(tool.name, tool.handler);
}

// List tools handler - returns only direct + router tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: allVisibleTools.map((tool) => ({
      name: tool.name,
      description: tool.description,
      inputSchema: tool.inputSchema,
    })),
  };
});

// Call tool handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  const handler = toolHandlers.get(name);
  if (!handler) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: `Unknown tool: ${name}`,
            hint: "Use list_tool_categories and search_tools to find available tools",
          }),
        },
      ],
      isError: true,
    };
  }

  try {
    const result = await handler(args || {});
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: `Tool execution failed: ${(error as Error).message}`,
          }),
        },
      ],
      isError: true,
    };
  }
});

// Start the server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running on stdio");
}

main().catch(console.error);
```

---

## Choosing Direct vs Routed Tools

### Direct Tools (Always Visible)

Include tools that are:

- Used in 80%+ of sessions
- Essential for basic workflows
- Required for project lifecycle (open, save, create)
- Needed for the core operation loop

**Examples by domain:**

| Domain       | Direct Tools                                                                                                                     |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **KiCAD**    | create_project, open_project, save_project, add_component, move_component, add_track, list_components, list_nets, get_board_info |
| **IDA Pro**  | open_database, save_database, get_function, list_functions, add_comment, rename, get_xrefs, decompile                            |
| **Git**      | status, add, commit, push, pull, checkout, branch, log                                                                           |
| **Database** | connect, query, list_tables, describe_table                                                                                      |

### Routed Tools (Hidden Behind Router)

Include tools that are:

- Used in <50% of sessions
- Part of specialized workflows
- End-of-workflow operations (export, report)
- Advanced features
- Bulk or batch operations

**Examples:**

| Category          | Why Route It                 |
| ----------------- | ---------------------------- |
| `export`          | Only used at end of workflow |
| `drc/validation`  | Used during review phase     |
| `advanced_*`      | Specialty operations         |
| `bulk_*`          | Batch operations             |
| `config/settings` | One-time setup               |

---

## Category Design Guidelines

### Good Category Names

- Short, memorable (1-2 words)
- Verb-oriented or domain-specific
- Clear scope

```
✓ export, import, drc, zones, routing, schematic, layers, analysis
✗ miscellaneous, utilities, other, stuff, tools2
```

### Good Category Descriptions

Include:

- What the category does
- Key operations included
- When you'd use it

```typescript
// Good
{
  name: "export",
  description: "Generate manufacturing files: Gerber, drill, BOM, PDF, 3D models (STEP/VRML), SVG"
}

// Bad
{
  name: "export",
  description: "Export tools"
}
```

### Suggested Category Structure (Generic)

```typescript
const categories = [
  // Core operations (might be direct tools instead)
  { name: "project", description: "Project lifecycle: create, open, save, close" },

  // Domain-specific operations
  { name: "analysis", description: "Analyze and inspect: find patterns, validate, check" },
  { name: "modification", description: "Modify and transform: edit, rename, restructure" },
  { name: "navigation", description: "Navigate and search: find, list, filter, locate" },

  // Output operations
  { name: "export", description: "Export and generate: reports, files, documentation" },
  { name: "import", description: "Import from external sources: files, formats, APIs" },

  // Configuration
  { name: "config", description: "Configuration and settings: preferences, rules, templates" },

  // Advanced/specialized
  { name: "advanced", description: "Advanced operations: batch processing, automation, scripting" },
];
```

---

## IDA Pro Example Structure

For an IDA Pro MCP server with 100+ tools:

### Direct Tools (~12)

```typescript
const directTools = [
  "open_database", // Load IDB
  "save_database", // Save IDB
  "get_function", // Get function by address/name
  "list_functions", // List all functions
  "decompile", // Decompile function (Hex-Rays)
  "add_comment", // Add comment at address
  "rename", // Rename address/function
  "get_xrefs_to", // Get cross-references to address
  "get_xrefs_from", // Get cross-references from address
  "get_strings", // List strings
  "search_bytes", // Search for byte pattern
  "get_segments", // List segments
];
```

### Routed Categories

```typescript
const categories = [
  {
    name: "disassembly",
    description: "Disassembly operations: undefine, make code/data, change types",
    tools: ["make_code", "make_data", "undefine", "set_type", "make_array", "make_struct"],
  },
  {
    name: "functions",
    description: "Function management: create, delete, modify boundaries, set types",
    tools: ["create_function", "delete_function", "set_func_end", "set_func_type", "add_func_arg"],
  },
  {
    name: "types",
    description: "Type system: structs, enums, typedefs, parse headers",
    tools: ["create_struct", "add_struct_member", "create_enum", "parse_header", "import_types"],
  },
  {
    name: "patching",
    description: "Binary patching: modify bytes, assemble, apply patches",
    tools: ["patch_bytes", "patch_word", "patch_dword", "assemble", "apply_patches"],
  },
  {
    name: "scripting",
    description: "IDAPython scripting: run scripts, evaluate expressions",
    tools: ["run_script", "eval_python", "get_global", "set_global"],
  },
  {
    name: "signatures",
    description: "Signatures and patterns: FLIRT, Lumina, create signatures",
    tools: ["apply_flirt", "query_lumina", "create_sig", "find_pattern"],
  },
  {
    name: "debugging",
    description: "Debugger control: breakpoints, stepping, memory",
    tools: ["set_breakpoint", "step_into", "step_over", "read_memory", "write_memory", "get_regs"],
  },
  {
    name: "export",
    description: "Export: ASM listing, pseudocode, database info, reports",
    tools: ["export_asm", "export_c", "export_json", "generate_report"],
  },
  {
    name: "import",
    description: "Import: symbols, types, comments from external sources",
    tools: ["import_symbols", "import_pdb", "import_map", "import_comments"],
  },
  {
    name: "analysis",
    description: "Analysis control: reanalyze, find patterns, auto-analysis settings",
    tools: ["reanalyze", "find_crypto", "find_strings", "analyze_calls", "set_analysis_options"],
  },
];
```

---

## Usage Flow Examples

### Example 1: User wants to export Gerbers

```
User: "Export gerbers for this board"

Claude's thinking:
1. Don't see an export_gerber tool directly
2. Call search_tools({ query: "gerber" })
   → Returns: { category: "export", tool: "export_gerber", ... }
3. Call execute_tool({ tool_name: "export_gerber", params: { output_dir: "./gerbers" }})
   → Returns: { success: true, files: [...] }

Claude: "I've exported the Gerber files to ./gerbers/"
```

### Example 2: User wants to place a component

```
User: "Add a 0805 resistor at position 10,20"

Claude's thinking:
1. See add_component in direct tools
2. Call add_component({ type: "R_0805", reference: "R1", x: 10, y: 20 })
   → Returns: { success: true, reference: "R1" }

Claude: "Added R1 (0805 resistor) at position (10, 20)"
```

### Example 3: User wants to do something unfamiliar

```
User: "I need to add length matching to these traces"

Claude's thinking:
1. Don't see length matching in direct tools
2. Call search_tools({ query: "length matching" })
   → Returns: { category: "advanced_routing", tool: "add_length_tuning", ... }
3. Call get_category_tools({ category: "advanced_routing" })
   → Returns full parameter schema for add_length_tuning
4. Call execute_tool({ tool_name: "add_length_tuning", params: {...} })

Claude: "I've added length tuning meanders to match the trace lengths"
```

---

## Testing Your Router

### Unit Tests

```typescript
// tests/router.test.ts

import { describe, it, expect } from "vitest";
import { searchTools, getCategory, getTool, getAllCategories } from "../src/tools/registry.js";
import { routerTools } from "../src/tools/router.js";

describe("Tool Registry", () => {
  it("should find tools by keyword", () => {
    const results = searchTools("export");
    expect(results.length).toBeGreaterThan(0);
    expect(results.some((r) => r.tool.includes("export"))).toBe(true);
  });

  it("should return category info", () => {
    const category = getCategory("export");
    expect(category).toBeDefined();
    expect(category!.tools.length).toBeGreaterThan(0);
  });

  it("should return tool info with category", () => {
    const tool = getTool("export_gerber");
    expect(tool).toBeDefined();
    expect(tool!.category).toBe("export");
  });
});

describe("Router Tools", () => {
  it("list_tool_categories returns all categories", async () => {
    const result = await routerTools.list_tool_categories.handler({});
    expect(result.categories.length).toBe(getAllCategories().length);
  });

  it("get_category_tools returns tools for valid category", async () => {
    const result = await routerTools.get_category_tools.handler({
      category: "export",
    });
    expect(result.tools).toBeDefined();
    expect(result.tools.length).toBeGreaterThan(0);
  });

  it("get_category_tools returns error for invalid category", async () => {
    const result = await routerTools.get_category_tools.handler({
      category: "nonexistent",
    });
    expect(result.error).toBeDefined();
  });

  it("execute_tool runs valid tool", async () => {
    const result = await routerTools.execute_tool.handler({
      tool_name: "export_gerber",
      params: { output_dir: "/tmp/test" },
    });
    expect(result.error).toBeUndefined();
  });

  it("execute_tool returns error for invalid tool", async () => {
    const result = await routerTools.execute_tool.handler({
      tool_name: "nonexistent_tool",
      params: {},
    });
    expect(result.error).toBeDefined();
  });
});
```

### Integration Test

Test with an actual MCP client:

```bash
# Using MCP Inspector
npx @modelcontextprotocol/inspector your-server

# Or with Claude Desktop - add to config
{
  "mcpServers": {
    "your-server": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}
```

---

## Advanced: Combining with Anthropic's Tool Search Tool

If you control the client (building your own app with Claude API), you can use Anthropic's native Tool Search Tool for even better results:

```python
import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["advanced-tool-use-2025-11-20"],
    tools=[
        # Tool search tool for dynamic discovery
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        # Always-loaded tools
        {
            "name": "create_project",
            "description": "Create new project",
            "input_schema": {...},
            "defer_loading": False  # Always visible
        },
        # Deferred tools - only loaded when searched
        {
            "name": "export_gerber",
            "description": "Export Gerber files for PCB fabrication",
            "input_schema": {...},
            "defer_loading": True  # Hidden until searched
        },
        # ... 100 more deferred tools
    ],
    messages=[{"role": "user", "content": "Export gerbers for my board"}]
)
```

This approach works at the API level rather than MCP level, giving you:

- Native search with regex or BM25
- Automatic tool expansion
- Works with any MCP client

See [Tool Search Tool Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) for details.

---

## References

### MCP Documentation

- [MCP Specification](https://modelcontextprotocol.io/specification/2025-03-26)
- [MCP Tools Documentation](https://modelcontextprotocol.info/docs/concepts/tools/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP GitHub Organization](https://github.com/modelcontextprotocol)

### Anthropic Advanced Tool Use

- [Advanced Tool Use Blog Post](https://www.anthropic.com/engineering/advanced-tool-use)
- [Tool Search Tool Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)
- [Programmatic Tool Calling Documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling)
- [Claude Code Issue: Tool Search Support](https://github.com/anthropics/claude-code/issues/12836)

### Example Implementations

- [KiCAD MCP Server](https://github.com/mixelpixx/KiCAD-MCP-Server) - 52+ tools with natural language PCB design
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Official reference implementations

---

## Checklist

Before shipping your router-based MCP server:

- [ ] Direct tools cover 80% of common use cases
- [ ] Categories have clear, descriptive names
- [ ] Category descriptions explain what's included
- [ ] All tools have good descriptions
- [ ] `search_tools` finds tools by common keywords
- [ ] `execute_tool` handles errors gracefully
- [ ] Unit tests pass for registry and router
- [ ] Tested with actual MCP client (Claude Desktop, Cline, etc.)
- [ ] README documents the router pattern for users

---

## Summary

| Before                   | After                 |
| ------------------------ | --------------------- |
| 100 tools visible        | 15-18 tools visible   |
| ~60K+ tokens consumed    | ~10K tokens consumed  |
| Tool selection confusion | Clear categories      |
| Context starvation       | Room for conversation |

The router pattern gives you unlimited tool capacity while keeping Claude focused and efficient.