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版本