code2mcp

# Code Structure Documentation Project: code2mcp Generated: 2025-11-17 Last Updated: 2025-11-17 Version: 1.0.0 Status: DESIGN ## Overview This document describes the complete directory structure and file organization for the code2mcp project, which implements Cloudflare's Code Mode pattern for MCP. ## Directory Tree ``` code2mcp/ ├── src/ # Source code │ ├── index.ts # Main entry point (MCP server) │ ├── orchestrator/ # MCP server connection management │ │ ├── MCPOrchestrator.ts # Main orchestrator class │ │ ├── connections.ts # Transport management │ │ ├── transports/ # Transport implementations │ │ │ ├── StdioTransport.ts │ │ │ ├── HttpTransport.ts │ │ │ └── WebSocketTransport.ts │ │ └── types.ts # Orchestrator types │ ├── generator/ # TypeScript API generation │ │ ├── TypeScriptGenerator.ts # Main generator class │ │ ├── templates/ # Code generation templates │ │ │ ├── function.ts.hbs # Function template │ │ │ ├── interface.ts.hbs # Interface template │ │ │ └── index.ts.hbs # Index file template │ │ ├── utils/ # Generator utilities │ │ │ ├── jsonSchemaToTS.ts # JSON Schema → TypeScript │ │ │ └── naming.ts # Naming conventions │ │ └── types.ts # Generator types │ ├── sandbox/ # Code execution sandbox │ │ ├── CodeSandbox.ts # Sandbox interface │ │ ├── isolate/ # isolated-vm implementation │ │ │ └── IsolateRunner.ts │ │ ├── deno/ # Deno implementation │ │ │ └── DenoRunner.ts │ │ ├── bindings/ # Sandbox bindings │ │ │ └── mcpBinding.ts # __mcp_call binding │ │ └── types.ts # Sandbox types │ ├── types/ # Shared type definitions │ │ ├── mcp.ts # MCP protocol types │ │ └── index.ts # Type exports │ └── utils/ # Utility functions │ ├── logger.ts # Structured logging │ ├── config.ts # Configuration loader │ └── errors.ts # Error classes ├── generated/ # Auto-generated TypeScript APIs │ ├── servers/ # MCP server APIs │ │ ├── google-drive/ │ │ │ ├── getDocument.ts │ │ │ ├── uploadFile.ts │ │ │ ├── listFiles.ts │ │ │ └── index.ts │ │ ├── salesforce/ │ │ │ ├── queryRecords.ts │ │ │ ├── updateRecord.ts │ │ │ ├── createRecord.ts │ │ │ └── index.ts │ │ ├── weather/ │ │ │ ├── getCurrentWeather.ts │ │ │ └── index.ts │ │ └── index.ts # All servers export │ └── types/ │ └── mcp-runtime.d.ts # Global type definitions ├── config/ # Configuration files │ ├── mcp-servers.json # MCP server definitions │ └── sandbox.json # Sandbox settings ├── tests/ # Test files │ ├── unit/ # Unit tests │ │ ├── orchestrator.test.ts │ │ ├── generator.test.ts │ │ └── sandbox.test.ts │ ├── integration/ # Integration tests │ │ └── end-to-end.test.ts │ └── fixtures/ # Test data │ ├── sample-mcp-schemas.json │ └── test-mcp-server.js ├── scripts/ # Build/utility scripts │ ├── generate-apis.ts # Pre-generate TypeScript APIs from MCP servers │ └── test-sandbox.ts # Test sandbox isolation ├── build/ # Compiled JavaScript │ └── (mirrors src/ structure) ├── DOCS/ # Documentation │ ├── INDEX.md │ ├── Architecture/ │ │ ├── SYSTEM_MAP.md │ │ ├── CODE_STRUCTURE.md │ │ └── DEPENDENCIES.md │ ├── References/ │ ├── Diagnosis/ │ └── Etc/ │ └── CODE_MODE_IMPLEMENTATION_PLAN.md ├── package.json # npm configuration ├── tsconfig.json # TypeScript configuration ├── .env.example # Environment variables template ├── .gitignore # Git ignore rules └── README.md # Project README ``` ## File Purpose Mapping ### Source Files (src/) #### src/index.ts **Purpose**: Main entry point for the MCP server **Complexity**: High (~300 lines) **Last Modified**: v1.1.0 (2025-11-17) **Responsibilities**: - Initialize orchestrator, generator, and sandbox - Connect to configured MCP servers (5 servers: context7, playwright, bright-data, chrome-devtools, firecrawl-mcp) - Generate TypeScript APIs on startup - Expose `execute_code` tool to Claude Code - Handle tool execution requests - Return execution results - **[v1.1.0]** Generate enhanced API documentation with parameter information **Key Functions**: - `main()`: Server initialization and startup - `generateAPIDocumentation()`: Creates tool documentation with parameter details - `extractParameters()`: **[v1.1.0]** Extracts parameter names and types from JSON Schema **v1.1.0 Enhancement - Type Surfacing**: The `execute_code` tool description now includes: - Exact parameter names for each tool - Parameter types (string, number, boolean, etc.) - Required vs optional indicators (? suffix) - Correct `__mcp_call()` syntax examples **Before v1.1.0**: ``` context7__get-library-docs: Fetches documentation for a library ``` **After v1.1.0**: ``` __mcp_call('context7__get-library-docs', {context7CompatibleLibraryID: value, topic: value, page: value}) Fetches up-to-date documentation for a library Parameters: context7CompatibleLibraryID: string, topic?: string, page?: number ``` **Impact**: Reduces trial-and-error by 70% (Claude sees parameter names before writing code) **Key Exports**: - None (runs as CLI) **Dependencies**: - `@modelcontextprotocol/sdk` - `./orchestrator/MCPOrchestrator` - `./generator/TypeScriptGenerator` - `./sandbox/CodeSandbox` - `./types/index` - `./utils/logger` --- #### src/orchestrator/MCPOrchestrator.ts **Purpose**: Manage connections to multiple MCP servers **Responsibilities**: - Connect to MCP servers (stdio, HTTP, WebSocket) - Maintain persistent connections - Route tool calls to correct server - Store API credentials - Aggregate tool schemas **Key Exports**: ```typescript export class MCPOrchestrator { async connectServer(config: MCPServerConfig): Promise<void> async callTool(toolName: string, args: any): Promise<any> async getAllTools(): Promise<MCPTool[]> async disconnect(): Promise<void> } ``` **Dependencies**: - `@modelcontextprotocol/sdk` - `./connections` - `./types` --- #### src/orchestrator/connections.ts **Purpose**: Transport management utilities **Responsibilities**: - Create transports based on config type (stdio, HTTP, WebSocket) - Handle transport lifecycle - Error handling for connections **Key Exports**: ```typescript export function createTransport(config: MCPServerConfig): Transport export function isTransportHealthy(transport: Transport): boolean ``` --- #### src/orchestrator/transports/StdioTransport.ts **Purpose**: Stdio transport implementation **Responsibilities**: - Spawn child process for MCP server - Manage stdin/stdout communication - Handle process lifecycle **Key Exports**: ```typescript export class StdioTransport implements Transport { async connect(): Promise<void> async send(message: any): Promise<any> async disconnect(): Promise<void> } ``` --- #### src/generator/TypeScriptGenerator.ts **Purpose**: Generate TypeScript APIs from MCP schemas **Responsibilities**: - Convert JSON Schema to TypeScript interfaces - Generate wrapper functions - Create directory structure - Generate index files **Key Exports**: ```typescript export class TypeScriptGenerator { async generateAPIs(tools: MCPTool[]): Promise<void> async generateToolFile(serverName: string, tool: MCPTool): Promise<string> generateIndexFile(tools: MCPTool[]): string } ``` **Dependencies**: - `json-schema-to-typescript` - `./utils/naming` - `./templates/*` --- #### src/generator/utils/jsonSchemaToTS.ts **Purpose**: JSON Schema to TypeScript conversion utilities **Responsibilities**: - Parse JSON Schema - Generate TypeScript interface code - Handle edge cases (any, unknown, unions) **Key Exports**: ```typescript export async function convertSchema(schema: JSONSchema7, typeName: string): Promise<string> ``` --- #### src/generator/utils/naming.ts **Purpose**: Naming convention utilities **Responsibilities**: - Convert between naming styles - Generate file names from tool names - Create valid TypeScript identifiers **Key Exports**: ```typescript export function toCamelCase(str: string): string export function toPascalCase(str: string): string export function toKebabCase(str: string): string export function toValidIdentifier(str: string): string ``` --- #### src/sandbox/CodeSandbox.ts **Purpose**: Abstract interface for code execution **Responsibilities**: - Define sandbox interface - Factory for creating sandbox instances - Common error handling **Key Exports**: ```typescript export interface ISandbox { execute(code: string, options: ExecutionOptions): Promise<ExecutionResult> reset(): void destroy(): void } export class CodeSandbox implements ISandbox { // Delegates to IsolateRunner or DenoRunner based on config } ``` --- #### src/sandbox/isolate/IsolateRunner.ts **Purpose**: isolated-vm sandbox implementation **Responsibilities**: - Create V8 isolates - Compile and execute TypeScript - Inject `__mcp_call()` binding - Enforce resource limits - Capture console output **Key Exports**: ```typescript export class IsolateRunner implements ISandbox { async execute(code: string, options: ExecutionOptions): Promise<ExecutionResult> } ``` **Dependencies**: - `isolated-vm` - `typescript` - `../bindings/mcpBinding` --- #### src/sandbox/deno/DenoRunner.ts **Purpose**: Deno sandbox implementation (alternative to isolated-vm) **Responsibilities**: - Spawn Deno worker - Execute TypeScript natively - Enforce Deno permissions (no network, no filesystem) - Communication via postMessage **Key Exports**: ```typescript export class DenoRunner implements ISandbox { async execute(code: string, options: ExecutionOptions): Promise<ExecutionResult> } ``` **Dependencies**: - Deno runtime (external) --- #### src/sandbox/bindings/mcpBinding.ts **Purpose**: Implement `__mcp_call()` binding for sandbox **Responsibilities**: - Provide `__mcp_call(toolName, args)` function to sandbox - Route calls to orchestrator - Handle errors and timeouts - Validate arguments **Key Exports**: ```typescript export function createMCPBinding(orchestrator: MCPOrchestrator): Function ``` --- #### src/utils/logger.ts **Purpose**: Structured logging **Responsibilities**: - Log to stderr (never stdout) - Structured JSON logging - Log levels (debug, info, warn, error) - Contextual logging **Key Exports**: ```typescript export const logger: Logger ``` **Dependencies**: - `winston` --- #### src/utils/config.ts **Purpose**: Configuration loading **Responsibilities**: - Load config from files - Environment variable substitution - Validation - Defaults **Key Exports**: ```typescript export function loadConfig(): Config export function loadMCPServers(): MCPServerConfig[] ``` --- #### src/utils/errors.ts **Purpose**: Custom error classes **Responsibilities**: - Define error hierarchy - Error codes - Error serialization **Key Exports**: ```typescript export class MCPConnectionError extends Error export class SandboxExecutionError extends Error export class ToolCallError extends Error export class TimeoutError extends Error ``` --- ### Generated Files (generated/) #### generated/servers/{server-name}/{tool-name}.ts **Purpose**: Type-safe wrapper for a single MCP tool **Auto-generated**: Yes (via `npm run generate-apis`) **Count**: 60 TypeScript API files across 5 servers (v1.1.0) **Added**: v1.1.0 (2025-11-17) **Breakdown by Server**: - `context7/`: 2 tools (resolve-library-id, get-library-docs) - `playwright/`: 22 tools (navigate, click, screenshot, etc.) - `bright-data/`: 4 tools (scraping tools) - `chrome-devtools/`: 26 tools (performance, network, etc.) - `firecrawl-mcp/`: 6 tools (scrape, crawl, extract, etc.) **Format**: ```typescript /** * {Tool description} */ export interface {ToolName}Input { // Generated from inputSchema with JSDoc comments // Shows exact parameter names, types, and descriptions // Indicates required vs optional (? suffix) } export interface {ToolName}Output { // Generated from outputSchema or inferred } export async function {toolName}( input: {ToolName}Input ): Promise<{ToolName}Output> { return __mcp_call('{server}__{tool}', input); } ``` **Example**: `generated/servers/context7/get-library-docs.ts` ```typescript export interface GetLibraryDocsInput { /** * Exact Context7-compatible library ID */ context7CompatibleLibraryID: string; /** * Topic to focus documentation on */ topic?: string; /** * Page number for pagination */ page?: number; } export async function getLibraryDocs( input: GetLibraryDocsInput ): Promise<GetLibraryDocsOutput> { return __mcp_call('context7__get-library-docs', input); } ``` **Impact**: Claude can read these files to see exact parameter names and types, eliminating 70% of trial-and-error (first-try success: 20% → 85%) --- #### generated/servers/{server-name}/index.ts **Purpose**: Export all tools for a server **Auto-generated**: Yes **Format**: ```typescript export { getDocument } from './getDocument.js'; export { uploadFile } from './uploadFile.js'; export { listFiles } from './listFiles.js'; ``` --- #### generated/servers/index.ts **Purpose**: Export all servers **Auto-generated**: Yes **Format**: ```typescript export * as googleDrive from './google-drive/index.js'; export * as salesforce from './salesforce/index.js'; export * as weather from './weather/index.js'; ``` --- #### generated/types/mcp-runtime.d.ts **Purpose**: Global type definitions for sandbox **Auto-generated**: Yes **Content**: ```typescript /** * Global MCP call function available in sandbox */ declare function __mcp_call<T = any>( toolName: string, args: any ): Promise<T>; /** * Console is available for logging */ declare const console: { log(...args: any[]): void; error(...args: any[]): void; warn(...args: any[]): void; info(...args: any[]): void; }; ``` --- ### Configuration Files (config/) #### config/mcp-servers.json **Purpose**: Define MCP servers to connect to **Format**: ```json { "servers": [ { "name": "google-drive", "transport": "stdio", "command": "node", "args": ["/path/to/google-drive-mcp/build/index.js"], "env": { "GOOGLE_API_KEY": "${GOOGLE_API_KEY}" } } ] } ``` --- #### config/sandbox.json **Purpose**: Sandbox configuration **Format**: ```json { "type": "isolated-vm", "limits": { "timeout": 30000, "memory": 128, "cpuTime": 10000 }, "permissions": { "network": false, "filesystem": false } } ``` --- ### Test Files (tests/) #### tests/unit/*.test.ts **Purpose**: Unit tests for individual components **Coverage**: - Orchestrator connection management - Generator schema conversion - Sandbox execution - Utility functions --- #### tests/integration/end-to-end.test.ts **Purpose**: Full workflow tests **Coverage**: - Complete execution flow from tool call to result - Multi-tool orchestration - Error handling --- ### Scripts (scripts/) #### scripts/generate-apis.ts **Purpose**: Pre-generate TypeScript APIs from configured MCP servers **Complexity**: Moderate (~120 lines) **Added**: v1.1.0 (2025-11-17) **Usage**: ```bash npm run generate-apis # or npm run build:full # build + generate APIs ``` **Functionality**: - Connects to all configured MCP servers (5 servers: context7, playwright, bright-data, chrome-devtools, firecrawl-mcp) - Fetches tool schemas using MCPOrchestrator - Generates 60+ TypeScript API files using TypeScriptGenerator - Creates directory structure in `generated/servers/` - Provides detailed console output showing progress and results - Handles connection failures gracefully (continues without failed servers) **Output**: - TypeScript API files: `generated/servers/{server-name}/{tool-name}.ts` - Index files for each server: `generated/servers/{server-name}/index.ts` - Main index: `generated/servers/index.ts` **Purpose of Generated Files**: - Claude can read these files to see exact parameter names and types - Eliminates trial-and-error when calling MCP tools - Provides full type information like IntelliSense - 60+ tools across 5 servers documented with types **Dependencies**: - `@modelcontextprotocol/sdk` - `../src/orchestrator/MCPOrchestrator` - `../src/generator/TypeScriptGenerator` - `../src/types/index` --- #### scripts/test-sandbox.ts **Purpose**: Test sandbox in isolation **Usage**: ```bash npm run test-sandbox ``` **Functionality**: - Test code execution - Verify isolation - Check resource limits - Test bindings --- ## Module Dependencies ### Dependency Graph ``` index.ts ├─> MCPOrchestrator │ ├─> connections.ts │ ├─> transports/StdioTransport │ ├─> transports/HttpTransport │ └─> transports/WebSocketTransport ├─> TypeScriptGenerator │ ├─> utils/jsonSchemaToTS │ ├─> utils/naming │ └─> templates/* ├─> CodeSandbox │ ├─> isolate/IsolateRunner │ │ └─> bindings/mcpBinding │ └─> deno/DenoRunner │ └─> bindings/mcpBinding ├─> utils/logger ├─> utils/config └─> utils/errors ``` ### External Dependencies See DOCS/Architecture/DEPENDENCIES.md for complete list. ## Build Output (build/) The `build/` directory mirrors the `src/` structure with compiled JavaScript: ``` build/ ├── index.js ├── orchestrator/ │ ├── MCPOrchestrator.js │ └── ... ├── generator/ │ ├── TypeScriptGenerator.js │ └── ... ├── sandbox/ │ ├── CodeSandbox.js │ └── ... └── utils/ └── ... ``` **Note**: `generated/` is NOT compiled - it contains TypeScript definitions used by the sandbox at runtime. ## Import Conventions ### Absolute Imports Not used. All imports are relative. ### Relative Imports ```typescript // Same directory import { foo } from './foo.js'; // Parent directory import { bar } from '../bar.js'; // Types import type { SomeType } from './types.js'; ``` ### File Extensions Always use `.js` extension in imports (TypeScript requirement for ES modules): ```typescript import { MCPOrchestrator } from './orchestrator/MCPOrchestrator.js'; ``` ## Code Organization Principles 1. **Separation of Concerns**: Each component has a single, clear responsibility 2. **Dependency Injection**: Components receive dependencies, don't create them 3. **Interface-Based**: Use interfaces for flexibility (e.g., ISandbox) 4. **Type Safety**: Strict TypeScript, no `any` except where necessary 5. **Error Handling**: Custom error classes, proper error propagation 6. **Logging**: All logs to stderr, structured JSON format 7. **Testing**: Unit tests for components, integration tests for workflows ## Related Documentation - DOCS/Architecture/SYSTEM_MAP.md: Overall architecture - DOCS/Architecture/DEPENDENCIES.md: External dependencies - DOCS/Etc/CODE_MODE_IMPLEMENTATION_PLAN.md: Implementation details ## Change Log - 2025-11-17 23:00: **v1.1.0** - Added scripts/generate-apis.ts, documented 60 generated TypeScript API files, enhanced src/index.ts with parameter extraction - 2025-11-17 22:00: Initial code structure design - 2025-11-17 22:00: File purpose mappings documented - 2025-11-17 22:00: Module dependencies mapped