codemesh CLAUDE.md

CodeMesh MCP Server

CodeMesh is a "Code Mode" MCP server that executes TypeScript code against multiple MCP tools. Think of it as a universal adapter that lets agents write code to orchestrate ANY MCP server.

🎯 Core Concept

Instead of exposing individual MCP tools, CodeMesh provides:

1. discover-tools - See what's available (context-efficient overview)
2. get-tool-apis - Get TypeScript APIs for specific tools
3. execute-code - Execute TypeScript that calls multiple tools
4. add-augmentation - Document unclear outputs (self-improving!)

🏗️ Project Structure

packages/
├── codemesh-server/    # Main CodeMesh MCP server
├── client/             # CLI for testing
├── example-server/     # Demo HTTP server
├── weather-server/     # Demo stdio server
└── geocode-server/     # Demo stdio server

🚀 Key Features

Multi-Server Support

• ✅ HTTP, stdio, and websocket transports
• ✅ Connect to multiple servers simultaneously
• ✅ Execute code that calls tools from different servers
• ✅ Works with any MCP-compliant server

Context Efficiency

• ✅ Tiered discovery prevents context pollution
• ✅ Load only the tool APIs you need
• ✅ Single execute-code tool vs dozens of individual tools

Self-Improving Architecture 🎉

• ✅ Auto-augmentation: Agents document unclear outputs
• ✅ // EXPLORING comment: Triggers mandatory documentation workflow
• ✅ Nuclear option: Returns ERROR until augmentation created
• ✅ Proven effective: Agent B one-shotted what Agent A struggled with!
• ✅ Knowledge compounds: Each exploration helps future agents

Security

• ✅ MCP SDK compliant env var handling
• ✅ Environment variable substitution: ${VAR:-default}
• ✅ Principle of least privilege
• ✅ Safe to commit configs (use env vars for secrets)

📝 Auto-Augmentation Workflow

The Problem: Agents trial-and-error unclear tool outputs instead of documenting them.

The Solution: Make exploration without documentation an ERROR!