MCP Context Optimizer

Solve the context window bloat problem when working with large MCP tool collections through progressive disclosure and hierarchical indexing.

Problem Statement

Large MCP implementations (like Miyabi with 172 tools across 22 categories) can overwhelm the context window:

• All tool definitions load into main context
• Token consumption increases dramatically
• Risk of selecting wrong tools
• Slower response times

Solution: Progressive Disclosure Pattern

┌─────────────────────────────────────────────────────────────┐
│  Level 1: Category Index (Always Loaded)                    │
│  ~200 tokens - 22 categories with descriptions              │
├─────────────────────────────────────────────────────────────┤
│  Level 2: Tool Index (On-Demand)                            │
│  ~50 tokens per category - tool names + short descriptions  │
├─────────────────────────────────────────────────────────────┤
│  Level 3: Full Tool Schema (On-Demand)                      │
│  Variable - complete parameters and usage                   │
└─────────────────────────────────────────────────────────────┘

Quick Reference: Miyabi MCP Categories

| Category | Count | Primary Use Case | |----------|-------|------------------| | github | 21 | Issues, PRs, workflows, releases | | git | 19 | Version control operations | | network | 15 | Connectivity, diagnostics | | process | 14 | Process management | | tmux | 10 | Terminal multiplexer | | resource | 10 | CPU, memory, disk monitoring | | file | 10 | File operations | | docker | 10 | Container management | | speckit | 9 | Spec-driven development | | claude | 8 | Claude Code session | | log | 7 | Log analysis | | k8s | 6 | Kubernetes | | db | 6 | Database operations | | compose | 4 | Docker Compose | | time | 4 | Time utilities | | gen | 4 | UUID, password, hash | | linux | 3 | Systemd services | | mcp | 3 | Tool discovery | | calc | 3 | Math calculations | | think | 3 | Reasoning chains | | windows | 2 | Windows services | | health | 1 | System health |

Workflow: Tool Discovery Protocol

Step 1: Identify Category

User Request → Parse Intent → Match Category

Category Matching Rules:

• Git operations (commit, branch, diff) → git
• GitHub (PR, issue, workflow) → github
• Container (docker run, logs) → docker
• System monitoring (CPU, memory) → resource
• File operations (read, search) → file
• Network (ping, port check) → network

Step 2: Search Within Category

// Use mcp_search_tools with category filter
miyabi:mcp_search_tools({
  category: "docker",
  query: "logs"  // optional refinement
})

Step 3: Get Full Tool Info

// Only load full schema when needed
miyabi:mcp_get_tool_info({
  tool: "docker_logs"
})

Implementation Patterns

Pattern 1: Intent-Based Routing

## User says: "Check container logs for errors"

1. Parse: container + logs → category: docker
2. Search: mcp_search_tools(category: "docker", query: "logs")
3. Result: docker_logs tool
4. Load: mcp_get_tool_info("docker_logs")
5. Execute: docker_logs(container: "x", tail: 100)

Pattern 2: Multi-Category Workflow

## User says: "Deploy and verify"

1. Parse: deploy → docker/compose, verify → health/network
2. Workflow:
   a. compose_up (compose category)
   b. network_port_check (network category)
   c. docker_logs (docker category)
   d. health_check (health category)

Pattern 3: Fallback Search

## When category unclear:

1. Use broad search: mcp_search_tools(query: "user's keywords")
2. Review results
3. Narrow if needed

Best Practices

DO:

• ✅ Start with category identification
• ✅ Use mcp_search_tools before loading full schemas
• ✅ Cache frequently used tool info in conversation
• ✅ Combine related tools in single workflow

DON'T:

• ❌ Load all 172 tool definitions upfront
• ❌ Guess tool names without searching
• ❌ Repeat tool info lookups in same conversation
• ❌ Use broad search when category is known

Tool Discovery Commands

List All Categories

miyabi:mcp_list_categories()

Search Tools

miyabi:mcp_search_tools({
  category: "git",      // optional filter
  query: "branch"       // optional keyword
})

Get Tool Details

miyabi:mcp_get_tool_info({
  tool: "git_branch_list"
})

Context Budget Guidelines

| Scenario | Token Budget | Strategy | |----------|-------------|----------| | Simple task | ~500 | Direct tool call | | Multi-step | ~1000 | Category + 2-3 tools | | Complex workflow | ~2000 | Full tool chain | | Exploration | ~300 | Category list only |

Integration with Other Skills

With full-dev-cycle Skill

1. mcp-context-optimizer identifies tools
2. full-dev-cycle executes workflow
3. Progressive loading throughout

With miyabi-agent-orchestration

1. Lead agent uses optimizer for tool selection
2. Sub-agents receive only needed tool schemas
3. Reduced context per agent

Troubleshooting

"Can't find the right tool"

1. Check category mapping above
2. Try broader search query
3. List all tools in suspected category

"Context too large"

1. Use mcp_list_categories first (lowest token cost)
2. Filter by category before detailed search
3. Don't request tool info until needed

"Tool doesn't exist"

1. Verify category with mcp_list_categories
2. Search without typos
3. Check if tool is platform-specific (linux/windows)

Metrics for Success

• Token Reduction: 60-80% vs loading all tools
• Accuracy: Higher tool selection accuracy
• Speed: Faster response with targeted loading
• Scalability: Works with 100+ tools

Future Enhancements

• [ ] Auto-categorization from natural language
• [ ] Tool usage frequency caching
• [ ] Cross-category tool suggestions
• [ ] Workflow template library