使用说明

MCP-CODEGEN

AI代理的通用工具发现

代理工具清单（ATM）规范的参考实现。 将ANY API转换为类型安全的TypeScript包装器，减少98%的令牌。

这是什么？

MCP-CODEGEN 生成人工智能代理用于与API交互的TypeScript包装代码，与发送原始API规范相比，令牌减少了98%。

代理导入并使用生成的包装器代码的~2K个令牌，而不是在每个提示中发送150K个令牌API规范。

令牌问题

源类型	原始规格大小	带MCP-CODEGEN	缩减
MCP服务器	~150K令牌	~2K令牌	98.7%
REST/OpenAPI	约20万个令牌	约3千个令牌	98.5%
GraphQL	约10万个令牌	约1.5万个令牌	98.5%

解决方案

Any API Source              Agent Tool Manifest           Any AI Agent
───────────────             ───────────────────           ────────────

MCP Server      ─┐                                    ┌─► Claude
                 │       .agent-ready.json            │
REST/OpenAPI   ──┼────►   + TypeScript wrappers  ────┼─► GPT
                 │                                    │
GraphQL        ──┘                                    └─► Any Agent

一种格式。任何来源。普遍发现。

支持的来源

源类型	状态	适配器
MCP服务器	✅ 生产	`MCPAdapter`
REST/OpenAPI	✅ 生产	`OpenAPIAdapter`
图查询语言	✅ 可用	`GraphQLAdapter`
数据库	📋 计划中	`DatabaseAdapter`

快速开始

# Install
npm install -g mcp-codegen

# Initialize a new project
mcp-codegen quickstart

# Or create a config manually
cat > codegen.config.json << 'EOF'
{
  "sources": {
    "mcp": {
      "filesystem": {
        "type": "mcp",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      }
    },
    "openapi": {
      "github": {
        "type": "openapi",
        "spec": "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "baseUrl": "https://api.github.com"
      }
    }
  }
}
EOF

# Generate wrappers
mcp-codegen sync

使用生成的包装器：

import { call } from "./codegen/runtime";

// MCP: Read local file
const data = await call("filesystem__read_file", {
  path: "/tmp/repos.json"
});

// REST: Fetch from GitHub
const repos = await call("github__list_repos", {
  path: { username: "anthropics" }
});

// Chain them together
await call("filesystem__write_file", {
  path: "/tmp/anthropic-repos.json",
  content: JSON.stringify(repos, null, 2)
});

结果： 代币减少98%。一个运行时。通用。

ATM规范

MCP-CODEGEN实施 代理工具清单（ATM）规范 --AI代理工具发现的通用格式。

📄 阅读完整规格→ 规格.md

为什么要制定规范？

通用 --适用于MCP、REST、GraphQL、数据库
最小化 --针对LLM令牌效率进行了优化
打开 --任何人都可以实现生成器或消费者
可验证的 --JSON模式的正确性

这 `.agent-ready.json` 清单

每个项目都会生成一个清单，供代理用于发现：

{
  "specVersion": "1.0.0",
  "codeMode": true,
  "name": "my-tools",
  "description": "MCP and REST API tools",
  "sources": {
    "mcp": ["filesystem"],
    "openapi": ["github"],
    "total": 2
  },
  "tools": {
    "total": 1122,
    "bySource": { "filesystem": 14, "github": 1108 }
  },
  "capabilities": ["type-safety", "mcp-servers", "rest-apis"],
  "tokenReduction": {
    "traditional": 207500,
    "codeMode": 2500,
    "savings": "98.8%"
  }
}

特性

通用源代码支持

MCP服务器（模型上下文协议）
REST API（OpenAPI/Swagger 3.x）
GraphQL API（通过内省）

生产基础结构

具有指数回退的自动重试
5种具有env-var解析的身份验证类型
连接池
全面的错误处理

开发者体验

类型安全的TypeScript包装器
所有API的IDE自动补全
基于哈希的再生（仅再生已更改的工具）
全套仪器和遥测

LLM优化

98%的代币减少（已验证）
渐进式披露
干净、最少的包装

配置

多源配置

{
  "sources": {
    "mcp": {
      "filesystem": {
        "type": "mcp",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      }
    },
    "openapi": {
      "github": {
        "type": "openapi",
        "spec": "https://api.github.com/openapi.json",
        "baseUrl": "https://api.github.com",
        "auth": {
          "type": "bearer",
          "token": "${GITHUB_TOKEN}"
        }
      }
    },
    "graphql": {
      "shopify": {
        "type": "graphql",
        "endpoint": "https://mystore.myshopify.com/admin/api/graphql.json",
        "auth": {
          "type": "bearer",
          "token": "${SHOPIFY_TOKEN}"
        }
      }
    }
  },
  "outputDir": "./codegen",
  "runtimePackage": "codegen/runtime"
}

身份验证类型

类型	描述
`bearer`	授权标头中的承载令牌
`apiKey`	标头或查询中的API键
`basic`	HTTP基本身份验证
`oauth2`	OAuth 2.0（多流）
`custom`	可插拔自定义解析器

环境变量会自动解析： ${GITHUB_TOKEN} → 实际代币价值。

CLI命令

# Generate all wrappers from config
mcp-codegen sync

# Generate specific source only
mcp-codegen generate <source-name>

# List discovered sources and tools
mcp-codegen list

# Initialize new project interactively
mcp-codegen quickstart

# Validate manifest against ATM spec
mcp-codegen validate .agent-ready.json

建筑

┌─────────────────────────────┐
│   ANY API SOURCE            │
│  MCP | REST | GraphQL | DB  │
└──────────────┬──────────────┘
               │
        ┌──────▼────────┐
        │   Adapters    │  ← Source-specific discovery & execution
        └──────┬────────┘
               │
        ┌──────▼────────┐
        │   Codegen     │  ← JSON Schema → TypeScript
        └──────┬────────┘
               │
        ┌──────▼────────┐
        │  TypeScript   │  ← Type-safe wrappers
        │   Wrappers    │
        └──────┬────────┘
               │
        ┌──────▼────────┐
        │  Universal    │  ← One runtime for all sources
        │   Runtime     │
        └───────────────┘

看建筑.md 详细设计。

示例

MCP服务器

import { call } from "./codegen/runtime";

const content = await call("filesystem__read_file", {
  path: "/tmp/example.txt"
});

REST API

const user = await call("github__get_user", {
  path: { username: "anthropics" }
});

图查询语言

const products = await call("shopify__query_products", {
  first: 10,
  query: "tag:featured"
});

类型安全呼叫

import { callTyped } from "./codegen/runtime";

interface GitHubUser {
  login: string;
  name: string;
  public_repos: number;
}

const user = await callTyped<{ path: { username: string } }, GitHubUser>(
  "github__get_user",
  { path: { username: "anthropics" } }
);

console.log(`${user.name} has ${user.public_repos} repos`);

基准测试

验证令牌减少：

来源	之前	之后	缩减	工具
MCP文件系统	1841	120	93.5%	14
GitHub REST	205658	120	99.94%	1,108
合并	2442	139	94.3%	19

演出

GitHub API（11.6MB规格）：在30秒内生成1108个包装器
发现：对于大多数来源，<5s
生成：每个工具<1s
运行时间开销：每次调用<50ms

项目结构

MCP-CODEGEN/
├── SPEC.md                 # ATM Specification
├── atm.schema.json         # JSON Schema for validation
├── ARCHITECTURE.md         # Technical architecture
├── src/
│   ├── adapters/           # Source adapters
│   │   ├── mcp-adapter.ts
│   │   ├── openapi-adapter.ts
│   │   └── graphql-adapter.ts
│   ├── runtime/            # Universal runtime
│   │   ├── auth-resolver.ts
│   │   ├── retry-policy.ts
│   │   └── errors.ts
│   ├── codegen/            # Code generation
│   └── cli.ts              # CLI commands
├── codegen/                # Generated output (example)
│   ├── mcp/
│   ├── openapi/
│   └── runtime/
└── .agent-ready.json       # Generated manifest

致谢

该项目扩展了以下概念：

Anthropic的MCP --支持AI工具通信的模型上下文协议
Cloudflare的代码模式 --演示了工具效率的代码生成

MCP-CODEGEN将这些概念扩展到工作中 普遍地 通过ATM规范跨越MCP、REST、GraphQL和其他API类型。

贡献

看贡献.md 用于：

开发设置
架构指南
如何添加适配器
测试策略

许可证

Apache 2.0许可证-请参阅许可证了解详情。

该项目包括Apache 2.0下的专利保护。看通知和版权归因要求。

链接

规范： 规格.md
架构： 建筑.md
示例： 示例/
问题： GitHub问题
讨论： GitHub讨论

AI代理的通用工具发现。一种格式。任何API。代币减少98%。