MCP Tool Factory Ts

🚀 MCP工具工厂 (TypeScript)

MCP工具工厂能够根据自然语言描述、OpenAPI规范、数据库模式、GraphQL模式或本体，快速生成可用于生产环境的MCP（模型上下文协议）服务器。

🚀 快速开始

安装

# 全局安装
npm install -g @heshamfsalama/mcp-tool-factory

# 或者使用npx
npx @heshamfsalama/mcp-tool-factory generate "Create tools for managing a todo list"

设置API密钥

至少需要设置一个提供商的API密钥：

# Anthropic Claude（推荐）
export ANTHROPIC_API_KEY=your-key-here

# 或者Claude Code OAuth
export CLAUDE_CODE_OAUTH_TOKEN=your-token-here

# 或者其他支持的提供商
export OPENAI_API_KEY=your-key-here
export GOOGLE_API_KEY=your-key-here
export MISTRAL_API_KEY=your-key-here
export DEEPSEEK_API_KEY=your-key-here
export GROQ_API_KEY=your-key-here
export XAI_API_KEY=your-key-here
export AZURE_OPENAI_API_KEY=your-key-here
export COHERE_API_KEY=your-key-here

生成第一个服务器

# 从自然语言生成
mcp-factory generate "Create tools for fetching weather data by city and converting temperatures"

# 从OpenAPI规范生成
mcp-factory from-openapi ./api-spec.yaml

# 从数据库生成
mcp-factory from-database ./data.db

# 从GraphQL模式生成
mcp-factory from-graphql ./schema.graphql

# 从本体生成
mcp-factory from-ontology ./ontology.owl --format rdf

✨ 主要特性

📦 安装指南

全局安装

npm install -g @heshamfsalama/mcp-tool-factory

使用npx

npx @heshamfsalama/mcp-tool-factory generate "Create tools for managing a todo list"

💻 使用示例

自然语言生成

mcp-factory generate "Create tools for managing a todo list with priorities" \
  --name todo-server \
  --output ./servers/todo \
  --web-search \
  --logging \
  --metrics

OpenAPI规范

# 从本地文件生成
mcp-factory from-openapi ./openapi.yaml --name my-api-server

# 使用自定义基础URL生成
mcp-factory from-openapi ./spec.json --base-url https://api.example.com

数据库模式

# SQLite
mcp-factory from-database ./myapp.db --tables users,posts,comments

# PostgreSQL
mcp-factory from-database "postgresql://user:pass@localhost/mydb" --type postgresql

GraphQL模式

# 从GraphQL SDL文件生成
mcp-factory from-graphql ./schema.graphql --name my-graphql-server

# 从URL端点生成
mcp-factory from-graphql https://api.example.com/graphql --name my-api-server

GraphQL查询会映射为只读的MCP工具，突变会映射为写入工具。GraphQL类型会自动转换为Zod验证模式。

本体

# 从RDF/OWL文件（.owl, .rdf, .ttl）生成
mcp-factory from-ontology ./ontology.owl --format rdf --name knowledge-server

# 从JSON-LD文件（.jsonld）生成
mcp-factory from-ontology ./schema.jsonld --format jsonld --name linked-data-server

# 从自定义YAML本体生成
mcp-factory from-ontology ./domain.yaml --format yaml --name domain-server

OWL类会映射为MCP资源，对象属性会成为工具，数据属性会成为工具参数。

测试与服务

# 运行测试
mcp-factory test ./servers/my-server

# 启动服务器进行测试
mcp-factory serve ./servers/my-server

📚 详细文档

生成的服务器结构

servers/my-server/
├── src/
│   └── index.ts          # 包含工具、资源和提示的MCP服务器
├── tests/
│   └── tools.test.ts     # Vitest测试（InMemoryTransport）
├── package.json          # 依赖项
├── tsconfig.json         # TypeScript配置
├── Dockerfile            # 容器部署
├── README.md             # 使用文档
├── skill.md              # Claude Code技能文件
├── server.json           # MCP注册表清单
├── EXECUTION_LOG.md      # 生成跟踪（可选）
└── .github/
    └── workflows/
        └── ci.yml        # GitHub Actions CI/CD

生成的服务器导出一个createServer()工厂函数，方便进行测试。服务器使用可流式HTTP传输，有一个/mcp POST端点和一个/health GET端点。测试使用InMemoryTransport.createLinkedPair()进行快速、可靠的进程内测试。

CLI参考

生成选项

mcp-factory generate "..." \
  --output, -o <path>           # 输出目录（默认：./servers）
  --name, -n <name>             # 服务器名称
  --description, -d <desc>      # 包描述
  --github-username, -g <user>  # MCP注册表的GitHub用户名
  --version, -v <ver>           # 服务器版本（默认：1.0.0）
  --provider, -p <provider>     # LLM提供商（anthropic, openai, google, mistral, deepseek, groq, xai, azure, cohere, claude_code）
  --model, -m <model>           # 要使用的特定模型
  --web-search, -w              # 搜索网络以获取API文档
  --auth <vars...>              # 用于身份验证的环境变量
  --health-check                # 包含健康检查端点（默认：true）
  --logging                     # 启用结构化日志记录（默认：true）
  --metrics                     # 启用Prometheus指标
  --rate-limit <n>              # 速率限制（每分钟请求数）
  --retries                     # 启用重试逻辑（默认：true）
  --budget <amount>             # 以美元为单位的最大花费（超过预算则中止）
  --compare-costs               # 在生成前显示各提供商的成本比较

配置

环境变量

LLM提供商

所有提供商都通过统一的UnifiedLLMProvider类使用Vercel AI SDK，采用延迟动态导入方式 —— 运行时仅加载所选提供商的@ai-sdk/*包。

编程式使用

基本用法

import { ToolFactoryAgent, writeServerToDirectory, formatCost } from '@heshamfsalama/mcp-tool-factory';

// 创建代理（从环境变量自动检测提供商）
const agent = new ToolFactoryAgent();

// 根据描述生成
const server = await agent.generateFromDescription(
  'Create tools for managing a todo list with priorities',
  {
    serverName: 'todo-server',
    webSearch: true,
    parallel: true,           // 启用并行生成（默认）
    maxConcurrency: 5,        // 最大并发LLM调用数（默认）
    budget: 1.00,             // 可选：如果成本超过1美元则中止
    productionConfig: {
      enableLogging: true,
      enableMetrics: true,
    },
  }
);

// 成本跟踪 —— 查看生成成本
if (server.executionLog) {
  console.log(`Cost: ${formatCost(server.executionLog.totalCost)}`);
}

// 写入目录
await writeServerToDirectory(server, './servers/todo');

从OpenAPI生成

import { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';
import { readFileSync } from 'fs';
import yaml from 'js-yaml';

const spec = yaml.load(readFileSync('./openapi.yaml', 'utf-8'));
const agent = new ToolFactoryAgent({ requireLlm: false });

const server = await agent.generateFromOpenAPI(spec, {
  serverName: 'my-api-server',
  baseUrl: 'https://api.example.com',
});

await writeServerToDirectory(server, './servers/api');

从数据库生成

import { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';

const agent = new ToolFactoryAgent({ requireLlm: false });

// SQLite（从文件路径自动检测）
const server = await agent.generateFromDatabase('./data/app.db', {
  serverName: 'app-database-server',
  tables: ['users', 'posts', 'comments'],
});

// PostgreSQL（从连接字符串自动检测）
const pgServer = await agent.generateFromDatabase(
  'postgresql://user:pass@localhost/mydb',
  { serverName: 'postgres-server' }
);

await writeServerToDirectory(server, './servers/app-db');

从GraphQL生成

import { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';
import { readFileSync } from 'fs';

const schema = readFileSync('./schema.graphql', 'utf-8');
const agent = new ToolFactoryAgent({ requireLlm: false });

const server = await agent.generateFromGraphQL(schema, {
  serverName: 'my-graphql-server',
});

await writeServerToDirectory(server, './servers/graphql');

从本体生成

import { ToolFactoryAgent, writeServerToDirectory } from '@heshamfsalama/mcp-tool-factory';
import { readFileSync } from 'fs';

const ontologyData = readFileSync('./ontology.owl', 'utf-8');
const agent = new ToolFactoryAgent({ requireLlm: false });

const server = await agent.generateFromOntology(ontologyData, {
  serverName: 'knowledge-server',
  format: 'rdf',
});

await writeServerToDirectory(server, './servers/knowledge');

代码验证

import { validateTypeScriptCode, validateGeneratedServer } from '@heshamfsalama/mcp-tool-factory';

// 验证TypeScript语法
const result = await validateTypeScriptCode(code);
// { valid: false, errors: [{ line: 4, column: 1, message: "'}' expected." }] }

// 验证完整服务器
const serverResult = await validateGeneratedServer(serverCode);
// { valid: true, errors: [], summary: 'Generated server code is syntactically valid' }

与AI框架配合使用

Claude Code / Claude Desktop

添加到MCP设置（claude_desktop_config.json）：

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "./servers/my-server/src/index.ts"]
    }
  }
}

OpenAI Agents SDK

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    command="npx",
    args=["tsx", "./servers/my-server/src/index.ts"]
) as mcp:
    agent = Agent(
        name="My Agent",
        tools=mcp.list_tools()
    )

Google ADK

from google.adk.tools.mcp_tool import MCPToolset

tools = MCPToolset(
    connection_params=StdioServerParameters(
        command="npx",
        args=["tsx", "./servers/my-server/src/index.ts"]
    )
)

LangChain

from langchain_mcp_adapters.client import MCPClient

client = MCPClient(
    command="npx",
    args=["tsx", "./servers/my-server/src/index.ts"]
)
tools = client.get_tools()

🔧 技术细节

生产特性

结构化日志记录

mcp-factory generate "..." --logging

生成的服务器使用pino进行结构化JSON日志记录：

const logger = pino({ level: 'info' });
logger.info({ tool: 'get_weather', params }, 'Tool called');

Prometheus指标

mcp-factory generate "..." --metrics

生成的服务器使用prom-client进行指标监控：

• mcp_tool_calls_total - 工具调用计数器
• mcp_tool_duration_seconds - 执行时间直方图

速率限制

mcp-factory generate "..." --rate-limit 100

可配置每个客户端的速率限制，采用滑动窗口机制。

重试逻辑

mcp-factory generate "..." --retries

对于瞬态故障采用指数退避重试机制。

结构化错误代码

生成的服务器使用结构化错误代码进行一致的错误处理：

• INVALID_INPUT - 工具参数格式错误或无效
• NOT_FOUND - 请求的资源不存在
• AUTH_ERROR - 身份验证或授权失败
• INTERNAL_ERROR - 意外的服务器错误

增强的健康检查

/health端点返回详细的服务器状态：

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "memory": { "rss": 52428800, "heapUsed": 20971520 },
  "transport": "streamable-http"
}

MCP注册表发布

将生成的服务器发布到MCP注册表以提高可发现性。

生成支持注册表的服务器

mcp-factory generate "Create weather tools" \
  --name weather-server \
  --github-username your-github-username \
  --description "Weather tools for Claude" \
  --version 1.0.0

这将生成符合注册表要求的文件：

package.json:

{
  "name": "@your-github-username/weather-server",
  "mcpName": "io.github.your-github-username/weather-server"
}

server.json:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.your-github-username/weather-server",
  "packages": [{
    "registryType": "npm",
    "identifier": "@your-github-username/weather-server",
    "transport": { "type": "stdio" }
  }],
  "tools": [...]
}

发布工作流程

# 1. 构建并发布到npm
cd ./servers/weather-server
npm install && npm run build
npm publish --access public

# 2. 安装mcp-publisher
brew install modelcontextprotocol/tap/mcp-publisher

# 3. 进行身份验证
mcp-publisher login github

# 4. 发布到注册表
mcp-publisher publish

详细说明请参阅发布指南。

架构

┌───────────────────────────────────────────────────────────────────────┐
│                         MCP Tool Factory                               │
├───────────────────────────────────────────────────────────────────────┤
│  Input Sources                                                         │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────┐│
│  │ Natural   │ │  OpenAPI  │ │ Database  │ │ GraphQL   │ │Ontology ││
│  │ Language  │ │   Spec    │ │  Schema   │ │  Schema   │ │RDF/YAML ││
│  └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └────┬────┘│
│        └──────────┬───┴─────────────┴─────────────┴────────────┘     │
│                   ▼                                                    │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                     ToolFactoryAgent                            │   │
│  │  ┌─────────────────────────────────────────────────────────┐   │   │
│  │  │  UnifiedLLMProvider (Vercel AI SDK)                      │   │   │
│  │  │  Anthropic │ OpenAI │ Google │ Mistral │ DeepSeek       │   │   │
│  │  │  Groq │ xAI │ Azure │ Cohere + Claude Code OAuth       │   │   │
│  │  └─────────────────────────────────────────────────────────┘   │   │
│  │  ┌──────────────┐ ┌──────────────┐ ┌───────────────────────┐  │   │
│  │  │  LLM Cache   │ │  Cost        │ │ Parallel Generation   │  │   │
│  │  │  (TTL-based) │ │  Tracking    │ │ (max concurrency: 5)  │  │   │
│  │  └──────────────┘ └──────────────┘ └───────────────────────┘  │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                   │                                                    │
│                   ▼                                                    │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                       Generators                                │   │
│  │  ServerGenerator  │  DocsGenerator  │  TestsGenerator          │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                   │                                                    │
│                   ▼                                                    │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                     GeneratedServer                             │   │
│  │  Tools │ Resources │ Prompts │ Tests │ Docs │ Dockerfile       │   │
│  └────────────────────────────────────────────────────────────────┘   │
│                   │                                                    │
│                   ▼                                                    │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │                Streamable HTTP Transport                        │   │
│  │          POST /mcp  │  GET /health                             │   │
│  └────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────────────────┘

开发

# 克隆仓库
git clone https://github.com/HeshamFS/mcp-tool-factory-ts.git
cd mcp-tool-factory-ts

# 安装依赖
pnpm install

# 构建
pnpm run build

# 运行测试
pnpm test

# 类型检查
pnpm run typecheck

# 代码检查
pnpm run lint

项目结构

mcp-tool-factory-ts/
├── src/
│   ├── agent/              # 主要的ToolFactoryAgent
│   ├── auth/               # OAuth2提供商
│   ├── cache/              # 具有可配置TTL的LLM响应缓存
│   ├── cli/                # 命令行界面
│   ├── config/             # 配置管理
│   ├── database/           # 数据库内省（SQLite, PostgreSQL）
│   ├── execution-logger/   # 执行日志记录
│   ├── generators/         # 代码生成器（服务器、文档、测试）
│   ├── graphql/            # GraphQL SDL解析和服务器生成
│   ├── middleware/         # 验证中间件
│   ├── models/             # 数据模型
│   ├── observability/      # 遥测和跟踪
│   ├── ontology/           # 本体解析（RDF/OWL, JSON-LD, YAML）
│   ├── openapi/            # OpenAPI规范解析
│   ├── production/         # 生产代码生成
│   ├── prompts/            # LLM提示模板
│   ├── providers/          # LLM提供商（通过Vercel AI SDK支持10种提供商 + Claude Code）
│   ├── security/           # 安全扫描
│   ├── server/             # MCP服务器模式（工厂即服务器）
│   ├── templates/          # 生成文件的Handlebars模板
│   ├── validation/         # 代码验证和Zod模式
│   └── web-search/         # 网络搜索集成
├── docs/                   # 文档
├── tests/                  # 测试文件
└── dist/                   # 构建输出

文档

• 入门指南
• CLI参考
• API参考
• 示例
• OpenAPI指南
• 数据库指南
• 提供商指南
• 生产特性
• 架构
• 故障排除
• 贡献指南

故障排除

常见问题

未找到API密钥

# 检查环境变量
echo $ANTHROPIC_API_KEY

# 设置API密钥
export ANTHROPIC_API_KEY=your-key-here

生成的服务器无法启动

# 先安装依赖
cd ./servers/my-server
npm install
npx tsx src/index.ts

TypeScript错误

# 验证生成的代码
import { validateGeneratedServer } from '@heshamfsalama/mcp-tool-factory';
const result = await validateGeneratedServer(code);
console.log(result.errors);

更多解决方案请参阅故障排除指南。

变更日志

v0.3.0

• Vercel AI SDK迁移 - 所有LLM提供商现在都通过单一的UnifiedLLMProvider类使用Vercel AI SDK，采用延迟动态导入方式。移除了约473行特定提供商的实现代码。运行时仅加载所选提供商的@ai-sdk/*包。
• 10种LLM提供商 - 除了现有的Anthropic、OpenAI、Google和Claude Code提供商，还添加了Mistral、DeepSeek、Groq、xAI、Azure和Cohere。所有提供商都使用相同的统一接口。
• 成本跟踪 - 每次LLM调用现在都使用内置的50多种模型定价表计算估计成本。显示每次调用的成本、总生成成本以及每个阶段的成本细分（工具提取、实现、测试、文档）。详细的令牌细分包括缓存读写令牌和AI SDK的推理令牌。
• 预算限制 (--budget <amount>) - 设置以美元为单位的最大花费。如果累计成本超过预算，生成将优雅地中止并抛出BudgetExceededError。
• 提供商成本比较 (--compare-costs) - 在生成之前，估计所有可用提供商的成本并显示一个排序的比较表。无需额外的API调用 —— 使用静态定价表。
• 按阶段成本细分 - CLI输出和执行日志显示哪些生成步骤成本最高（工具提取、实现、资源提取、提示提取、测试生成、文档生成）。
• OpenAI推理模型支持 - 对于不支持温度参数的OpenAI o系列和gpt-5.x模型，会自动省略该参数。

v0.2.0

• 可流式HTTP传输 - 生成的服务器使用StreamableHTTPServerTransport和原生http模块，而不是Express/SSE（2025年6月已弃用）。有一个/mcp POST端点和一个/health GET端点。
• MCP SDK v1.26.0 - 从^1.0.0更新到^1.26.0
• 资源与提示 - 全面支持所有三种MCP原语。资源公开结构化数据（文档、数据库记录、文件树）。提示为引导式LLM工作流提供可重用的模板。代理通过LLM自动从描述中提取资源和提示。
• GraphQL输入源 - 新增from-graphql CLI命令和generate_from_graphql MCP工具。查询映射为读取工具，突变映射为写入工具，GraphQL类型转换为Zod模式。
• 本体输入源 - 新增from-ontology CLI命令和generate_from_ontology MCP工具。支持RDF/OWL、JSON-LD和自定义YAML格式。OWL类映射为资源，对象属性映射为工具，数据属性映射为工具参数。
• LLM响应缓存 - 通过可配置的TTL去重相同的LLM调用。可使用skipCache选项绕过缓存。
• 并行生成 - 默认情况下工具实现并发生成（parallel: true，maxConcurrency: 5）。对于多工具服务器，显著提高了生成速度。
• InMemoryTransport测试 - 生成的测试使用InMemoryTransport.createLinkedPair()而不是子进程生成。服务器导出createServer()工厂函数以方便测试。
• 生产增强 - 速率限制、结构化日志记录、指标监控和持续时间跟踪集成到工具处理程序中。增强的健康检查包含版本、正常运行时间、内存和传输信息。结构化错误代码：INVALID_INPUT、NOT_FOUND、AUTH_ERROR、INTERNAL_ERROR。

v0.1.0

• 初始TypeScript版本发布
• 支持使用Claude、Claude Code、OpenAI、Google Gemini进行自然语言生成
• 支持导入OpenAPI 3.0+规范
• 支持数据库CRUD操作生成（SQLite、PostgreSQL）
• 具备生产特性（日志记录、指标监控、速率限制）
• 支持生成MCP注册表的server.json文件
• 支持TypeScript语法验证
• 支持网络搜索API文档
• 支持生成GitHub Actions CI/CD配置
• 支持MCP服务器模式，可与Claude实时生成服务器

📄 许可证

本项目采用MIT许可证。

链接

• GitHub仓库
• npm包
• MCP规范
• MCP注册表
• Python版本