{"id":33576236,"url":"https://github.com/universal-tool-calling-protocol/code-mode","last_synced_at":"2026-01-24T16:22:43.201Z","repository":{"id":323647255,"uuid":"1094122545","full_name":"universal-tool-calling-protocol/code-mode","owner":"universal-tool-calling-protocol","description":"🔌 Plug-and-play library to enable agents to call MCP and UTCP tools via code execution. ","archived":false,"fork":false,"pushed_at":"2026-01-16T16:28:04.000Z","size":160,"stargazers_count":1265,"open_issues_count":9,"forks_count":86,"subscribers_count":13,"default_branch":"main","last_synced_at":"2026-01-17T05:16:38.788Z","etag":null,"topics":["ai-agents","codemode","mcp","model-context-protocol","toolchain","utcp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/universal-tool-calling-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T09:35:44.000Z","updated_at":"2026-01-17T04:40:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/universal-tool-calling-protocol/code-mode","commit_stats":null,"previous_names":["universal-tool-calling-protocol/code-mode"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/universal-tool-calling-protocol/code-mode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Fcode-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Fcode-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Fcode-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Fcode-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/universal-tool-calling-protocol","download_url":"https://codeload.github.com/universal-tool-calling-protocol/code-mode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/universal-tool-calling-protocol%2Fcode-mode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28731225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","codemode","mcp","model-context-protocol","toolchain","utcp"],"created_at":"2025-11-28T16:00:41.779Z","updated_at":"2026-01-24T16:22:43.190Z","avatar_url":"https://github.com/universal-tool-calling-protocol.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\u003c!-- \u003cimg alt=\"utcp code mode banner\" src=\"https://github.com/user-attachments/assets/77723130-ecbc-4d1d-9e9b-20f978882699\" width=\"80%\" style=\"margin: 20px auto;\"\u003e --\u003e\n\n\u003ch1 align=\"center\"\u003e🤖 Code-Mode Library: First library for tool calls via code execution\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/universal-tool-calling-protocol\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/followers/universal-tool-calling-protocol?label=Follow%20Org\u0026logo=github\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://img.shields.io/npm/dt/@utcp/code-mode\" title=\"PyPI Version\"\u003e\n        \u003cimg src=\"https://img.shields.io/npm/dt/@utcp/code-mode\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/universal-tool-calling-protocol/code-mode/blob/main/LICENSE\" alt=\"License\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/universal-tool-calling-protocol/code-mode\" /\u003e\u003c/a\u003e\n \n  [![npm](https://img.shields.io/npm/v/@utcp/code-mode)](https://www.npmjs.com/package/@utcp/code-mode)\n\u003c/p\u003e\n\u003c/div\u003e\n\n\u003e Transform your AI agents from clunky tool callers into efficient code executors — in just 3 lines.\n\n## Why This Changes Everything\n\nLLMs excel at writing code but struggle with tool calls. Instead of exposing hundreds of tools directly, give them ONE tool that executes TypeScript code with access to your entire toolkit.\n\n[Apple](https://machinelearning.apple.com/research/codeact), [Cloudflare](https://blog.cloudflare.com/code-mode/), and [Anthropic](https://www.anthropic.com/engineering/code-execution-with-mcp) say that Code-Mode is a more efficient way to approach tool calling compared to the traditional dump function information and then extract a JSON for function calling.\n\n## Benchmarks\n\nIndependent [Python benchmark study](https://github.com/imran31415/codemode_python_benchmark) validates the performance claims with **$9,536/year cost savings** at 1,000 scenarios/day:\n\n| Scenario Complexity | Traditional | Code Mode | **Improvement** |\n|---------------------|-------------|-----------|----------------|\n| **Simple (2-3 tools)** | 3 iterations | 1 execution | **67% faster** |\n| **Medium (4-7 tools)** | 8 iterations | 1 execution | **75% faster** |\n| **Complex (8+ tools)** | 16 iterations | 1 execution | **88% faster** |\n\n### **Why Code Mode Dominates:**\n\n   **Batching Advantage** - Single code block replaces multiple API calls  \n   **Cognitive Efficiency** - LLMs excel at code generation vs. tool orchestration  \n   **Computational Efficiency** - No context re-processing between operations\n\n# Getting Started\n\n[\u003cimg width=\"2606\" height=\"1445\" alt=\"Frame 4 (4)\" src=\"https://github.com/user-attachments/assets/58ba26ab-6e77-459b-a59a-eeb60d711746\" /\u003e\n](https://www.youtube.com/watch?v=zsMjkPzmqhA)\n\n## Get Started in 3 Lines\n\n```typescript\nimport { CodeModeUtcpClient } from '@utcp/code-mode';\n\nconst client = await CodeModeUtcpClient.create();                    // 1. Initialize\nawait client.registerManual({ name: 'github', /* MCP config */ });  // 2. Add tools  \nconst { result } = await client.callToolChain(`/* TypeScript */`);   // 3. Execute code\n```\n\nThat's it. Your AI agent can now execute complex workflows in a single request instead of dozens.\n\n## What You Get\n\n### **Progressive Tool Discovery**\n```typescript\n// Agent discovers tools dynamically, loads only what it needs\nconst tools = await client.searchTools('github pull request');\n// Instead of 500 tool definitions → 3 relevant tools\n```\n\n### **Natural Code Execution**  \n```typescript\nconst { result, logs } = await client.callToolChain(`\n  // Chain multiple operations in one request\n  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  \n  // Process data efficiently in-sandbox\n  return {\n    title: pr.title,\n    commentCount: comments.length,\n    approvals: reviews.filter(r =\u003e r.state === 'APPROVED').length\n  };\n`);\n// Single API call replaces 15+ traditional tool calls\n```\n\n### **Auto-Generated TypeScript Interfaces**\n```typescript\nnamespace github {\n  interface get_pull_requestInput {\n    /** Repository owner */\n    owner: string;\n    /** Repository name */ \n    repo: string;\n    /** Pull request number */\n    pull_number: number;\n  }\n}\n```\n\n## Enterprise-Ready\n\n- **Secure VM Sandboxing** – Node.js isolates prevent unauthorized access\n- **Timeout Protection** – Configurable execution limits prevent runaway code  \n- **Complete Observability** – Full console output capture and error handling\n- **Zero External Dependencies** – Tools only accessible through registered UTCP/MCP servers\n- **Runtime Introspection** – Dynamic interface discovery for adaptive workflows\n\nIf you're working at an enterprise, and need support, book a consultation [here](https://bevel.neetocal.com/meeting-with-ali).\n## Universal Protocol Support\n\nWorks with **any tool ecosystem:**\n\n| Protocol | Description | Usage |\n|----------|-------------|-------|\n| **MCP** | Model Context Protocol servers | `call_template_type: 'mcp'` |\n| **HTTP** | REST APIs with auto-discovery | `call_template_type: 'http'` |  \n| **File** | Local JSON/YAML configurations | `call_template_type: 'file'` |\n| **CLI** | Command-line tool execution | `call_template_type: 'cli'` |\n\n## Installation\n\n```bash\nnpm install @utcp/code-mode\n```\n\n## Even Easier: Ready-to-Use MCP Server\n\n**Want Code Mode without any setup?** Use our plug-and-play MCP server with Claude Desktop or any MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"code-mode\": {\n      \"command\": \"npx\",\n      \"args\": [\"@utcp/code-mode-mcp\"],\n      \"env\": {\n        \"UTCP_CONFIG_FILE\": \"/path/to/your/.utcp_config.json\"\n      }\n    }\n  }\n}\n```\n\n**That's it!** No installation, no Node.js knowledge required. The [Code Mode MCP Server](https://github.com/universal-tool-calling-protocol/code-mode/tree/main/code-mode-mcp) automatically:\n- Downloads and runs the latest version via `npx`\n- Loads your tool configurations from JSON\n- Provides code execution capabilities to Claude Desktop\n- Gives you `call_tool_chain` as an MCP tool for TypeScript execution\n\n**Perfect for non-developers** who want Code Mode power in Claude Desktop!\n\n## Direct TypeScript Usage\n\n### 1. **MCP Server Integration**\nConnect to any Model Context Protocol server:\n\n```typescript\nimport { CodeModeUtcpClient } from '@utcp/code-mode';\n\nconst client = await CodeModeUtcpClient.create();\n\n// Connect to GitHub MCP server\nawait client.registerManual({\n  name: 'github',\n  call_template_type: 'mcp',\n  config: {\n    mcpServers: {\n      github: {\n        command: 'docker',\n        args: ['run', '-i', '--rm', '-e', 'GITHUB_PERSONAL_ACCESS_TOKEN', 'mcp/github'],\n        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN }\n      }\n    }\n  }\n});\n```\n\n### 2. **Execute Multi-Step Workflows**\nReplace 15+ tool calls with a single code execution:\n\n```typescript\nconst { result, logs } = await client.callToolChain(`\n  // Traditional: 4 separate API round trips → Code Mode: 1 execution\n  const pr = await github.get_pull_request({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  const comments = await github.get_pull_request_comments({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  const reviews = await github.get_pull_request_reviews({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  const files = await github.get_pull_request_files({ owner: 'microsoft', repo: 'vscode', pull_number: 1234 });\n  \n  // Process data in-sandbox (no token overhead)\n  const summary = {\n    title: pr.title,\n    state: pr.state,\n    author: pr.user.login,\n    stats: {\n      comments: comments.length,\n      reviews: reviews.length, \n      filesChanged: files.length,\n      approvals: reviews.filter(r =\u003e r.state === 'APPROVED').length\n    },\n    topDiscussion: comments.slice(0, 3).map(c =\u003e ({\n      author: c.user.login,\n      preview: c.body.substring(0, 100) + '...'\n    }))\n  };\n  \n  console.log(\\`PR \"\\${pr.title}\" analysis complete\\`);\n  return summary;\n`);\n\nconsole.log('Analysis Result:', result);\n// console output: 'PR \"Fix memory leak in hooks\" analysis complete'\n```\n\n---\n\n## Advanced Features\n\n### **Multi-Protocol Tool Chains**\nMix and match different tool ecosystems in a single execution:\n\n```typescript\n// Register multiple tool sources\nawait client.registerManual({ name: 'github', call_template_type: 'mcp', /* config */ });\nawait client.registerManual({ name: 'slack', call_template_type: 'http', /* config */ });\nawait client.registerManual({ name: 'db', call_template_type: 'file', file_path: './db-tools.json' }); // This loads a UTCP manual from a json file\n\nconst result = await client.callToolChain(`\n  // Fetch PR data from GitHub (MCP)\n  const pr = await github.get_pull_request({ owner: 'company', repo: 'api', pull_number: 42 });\n  \n  // Query deployment status from database (File)\n  const deployment = await db.get_deployment_status({ pr_id: pr.id });\n  \n  // Send notification to Slack (HTTP)\n  await slack.post_message({\n    channel: '#releases',\n    text: \\`PR #42 \"\\${pr.title}\" deployed to \\${deployment.environment}\\`\n  });\n  \n  return { pr: pr.title, environment: deployment.environment };\n`);\n```\n\n### **Runtime Interface Introspection**\nTools can dynamically discover and adapt to available interfaces:\n\n```typescript\nconst result = await client.callToolChain(`\n  // Discover available tools at runtime\n  console.log('Available interfaces:', __interfaces);\n  \n  // Get specific tool interface for validation\n  const prInterface = __getToolInterface('github.get_pull_request');\n  console.log('PR tool expects:', prInterface);\n  \n  // Use interface info for dynamic workflows\n  const hasSlackTools = __interfaces.includes('namespace slack');\n  if (hasSlackTools) {\n    await slack.post_message({ channel: '#dev', text: 'Analysis complete' });\n  }\n  \n  return { toolsAvailable: hasSlackTools };\n`);\n```\n\n### **Context-Efficient Data Processing**\nProcess large datasets without bloating the model's context:\n\n```typescript\nconst result = await client.callToolChain(`\n  // Fetch large dataset\n  const allIssues = await github.list_repository_issues({ owner: 'facebook', repo: 'react' });\n  console.log('Fetched', allIssues.length, 'total issues');\n  \n  // Process efficiently in-sandbox\n  const criticalBugs = allIssues\n    .filter(issue =\u003e issue.labels.some(l =\u003e l.name === 'bug'))\n    .filter(issue =\u003e issue.labels.some(l =\u003e l.name === 'high priority'))\n    .map(issue =\u003e ({\n      number: issue.number,\n      title: issue.title,\n      author: issue.user.login,\n      daysOld: Math.floor((Date.now() - new Date(issue.created_at)) / (1000 * 60 * 60 * 24))\n    }))\n    .sort((a, b) =\u003e b.daysOld - a.daysOld);\n  \n  // Only return processed summary (not 10,000 raw issues)\n  return {\n    totalIssues: allIssues.length,\n    criticalBugs: criticalBugs.slice(0, 10), // Top 10 oldest critical bugs\n    summary: \\`Found \\${criticalBugs.length} critical bugs, oldest is \\${criticalBugs[0]?.daysOld} days old\\`\n  };\n`);\n```\n\n### **Error Handling \u0026 Observability**\nBuilt-in error handling with complete execution transparency:\n\n```typescript\nconst { result, logs } = await client.callToolChain(`\n  try {\n    console.log('Starting multi-step workflow...');\n    \n    const data = await external_api.fetch_data({ id: 'user-123' });\n    console.log('Data fetched successfully');\n    \n    const processed = await data_processor.transform(data);\n    console.warn('Processing completed with', processed.warnings.length, 'warnings');\n    \n    return processed;\n  } catch (error) {\n    console.error('Workflow failed:', error.message);\n    throw error; // Propagates to outer error handling\n  }\n`, 30000); // 30-second timeout\n\n// Complete observability\nconsole.log('Result:', result);\nconsole.log('Execution logs:', logs);\n// ['Starting multi-step workflow...', 'Data fetched successfully', '[WARN] Processing completed with 2 warnings']\n```\n\n### **Custom Timeouts**\nConfigure execution limits for different workload types:\n\n```typescript\n// Quick operations (5 seconds)\nconst quickResult = await client.callToolChain(`return await ping.check();`, 5000);\n\n// Heavy data processing (2 minutes) \nconst heavyResult = await client.callToolChain(`\n  const bigData = await database.export_full_dataset();\n  return await analytics.process_dataset(bigData);\n`, 120000);\n```\n\n---\n\n## AI Agent Integration\n\nPlug-and-play with any AI framework. The built-in prompt template handles all the complexity:\n\n```typescript\nimport { CodeModeUtcpClient } from '@utcp/code-mode';\n\nconst systemPrompt = `\nYou are an AI assistant with access to tools via UTCP CodeMode.\n${CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE}\nAdditional instructions...\n`;\n\n// Works with any AI library\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [\n    { role: 'system', content: systemPrompt },\n    { role: 'user', content: 'Analyze the latest PR in microsoft/vscode' }\n  ]\n});\n```\n\n**The template provides comprehensive guidance on:**\n- Tool discovery workflow (`searchTools` → `__interfaces` → `callToolChain`)\n- Hierarchical access patterns (`manual.tool()` syntax)  \n- Interface introspection (`__getToolInterface()`)\n- Error handling and best practices\n\n---\n\n## API Reference\n\n### **Core Methods**\n\n#### `callToolChain(code: string, timeout?: number)`\nExecute TypeScript code with full tool access and observability.\n- **Returns**: `{result: any, logs: string[]}` with execution result and captured console output\n- **Default timeout**: 30 seconds\n\n#### `getAllToolsTypeScriptInterfaces()`\nGenerate complete TypeScript interfaces for IDE integration.\n- **Returns**: String containing all interface definitions with namespaces\n\n#### `searchTools(query: string)` *(from UtcpClient)*\nDiscover tools using natural language queries.\n- **Returns**: Array of relevant tools with descriptions and interfaces\n\n### **Static Methods**\n\n#### `CodeModeUtcpClient.create(root_dir?, config?)`\nCreate a new client instance with optional configuration.\n\n#### `CodeModeUtcpClient.AGENT_PROMPT_TEMPLATE`\nProduction-ready prompt template for AI agents.\n\n---\n\n## Security \u0026 Performance\n\n### **Secure by Design**\n- **Node.js VM sandboxing** – Isolated execution context\n- **No filesystem access** – Tools only through registered servers  \n- **Timeout protection** – Configurable execution limits\n- **Zero network access** – No external dependencies or API keys exposed\n\n### **Performance Optimized**\n- **Minimal memory footprint** – VM contexts are lightweight\n- **Efficient tool caching** – TypeScript interfaces cached automatically\n- **Streaming console output** – Real-time log capture without buffering\n- **Identifier sanitization** – Handles invalid TypeScript identifiers gracefully\n\n---\n\n## Development Experience\n\n### **IDE Integration**\nGenerate TypeScript definitions for full IntelliSense support:\n\n```bash\n# Generate tool interfaces  \nconst interfaces = await client.getAllToolsTypeScriptInterfaces();\nawait fs.writeFile('generated-tools.d.ts', interfaces);\n\n# Add to tsconfig.json\n{\n  \"compilerOptions\": {\n    \"typeRoots\": [\"./generated-tools.d.ts\"]\n  }\n}\n```\n\n### **Debug \u0026 Monitor**\nBuilt-in observability for production deployments:\n\n```typescript\nconst { result, logs } = await client.callToolChain(userCode);\n\n// Ship logs to your monitoring system\nlogs.forEach(log =\u003e {\n  if (log.startsWith('[ERROR]')) monitoring.error(log);\n  if (log.startsWith('[WARN]')) monitoring.warn(log);\n});\n```\n\n---\n\n\n### **Benchmark Methodology**\nThe [comprehensive Python study](https://github.com/imran31415/codemode_python_benchmark) tested **16 realistic scenarios** across:\n- **Financial workflows** (invoicing, expense tracking)  \n- **DevOps operations** (deployments, monitoring)\n- **Data processing** (analysis, reporting)\n- **Business automation** (CRM, notifications)\n\n**Models tested:** Claude Haiku, Gemini Flash  \n**Pricing basis:** $0.25/1M input, $1.25/1M output tokens  \n**Scale:** 1,000 scenarios/day = $9,536/year savings with Code Mode\n\n## Learn More\n\n- **[Cloudflare Research](https://blog.cloudflare.com/code-mode/)** – Original code mode whitepaper\n- **[Anthropic Study](https://www.anthropic.com/engineering/code-execution-with-mcp)** – MCP code execution benefits\n- **[Python Benchmark Study](https://github.com/imran31415/codemode_python_benchmark)** – Comprehensive performance analysis\n- **[UTCP Specification](https://utcp.io)** – Official TypeScript implementation  \n- **[Report Issues](https://github.com/universal-tool-calling-protocol/code-mode/issues)** – Bug reports and feature requests\n\n## License\n\n**MPL-2.0** – Open source with commercial-friendly terms.\n","funding_links":[],"categories":["📚 Projects (1974 total)","Containerised MCP Servers","MCP Servers \u0026 Integrations","Python"],"sub_categories":["MCP Servers","AI \u0026 Machine Learning","Other IDEs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Fcode-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funiversal-tool-calling-protocol%2Fcode-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funiversal-tool-calling-protocol%2Fcode-mode/lists"}