Back to Details

mcp-server-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MCP Server Builder

MCP服务器构建工具

Tier: POWERFUL
Category: Engineering
Domain: AI / API Integration
层级: POWERFUL
分类: 工程
领域: AI / API集成

Overview

概述

Use this skill to design and ship production-ready MCP servers from API contracts instead of hand-written one-off tool wrappers. It focuses on fast scaffolding, schema quality, validation, and safe evolution.
The workflow supports both Python and TypeScript MCP implementations and treats OpenAPI as the source of truth.
使用此技能从API契约而非手写的一次性工具包装器来设计并交付可用于生产环境的MCP服务器。它专注于快速搭建脚手架、Schema质量、验证以及安全演进。
此工作流支持Python和TypeScript两种MCP实现方式，并将OpenAPI作为唯一可信数据源。

Core Capabilities

核心功能

  • Convert OpenAPI paths/operations into MCP tool definitions
  • Generate starter server scaffolds (Python or TypeScript)
  • Enforce naming, descriptions, and schema consistency
  • Validate MCP tool manifests for common production failures
  • Apply versioning and backward-compatibility checks
  • Separate transport/runtime decisions from tool contract design
  • 将OpenAPI路径/操作转换为MCP工具定义
  • 生成初始服务器脚手架（Python或TypeScript）
  • 强制命名、描述和Schema的一致性
  • 验证MCP工具清单，排查常见生产环境故障
  • 应用版本控制和向后兼容性检查
  • 将传输/运行时决策与工具契约设计分离

When to Use

使用场景

  • You need to expose an internal/external REST API to an LLM agent
  • You are replacing brittle browser automation with typed tools
  • You want one MCP server shared across teams and assistants
  • You need repeatable quality checks before publishing MCP tools
  • You want to bootstrap an MCP server from existing OpenAPI specs
  • 您需要向LLM agent暴露内部/外部REST API
  • 您正使用类型化工具替代脆弱的浏览器自动化方案
  • 您希望拥有一个可跨团队和助手共享的MCP服务器
  • 您需要在发布MCP工具前进行可重复的质量检查
  • 您希望从现有OpenAPI规范快速搭建MCP服务器

Key Workflows

关键工作流

1. OpenAPI to MCP Scaffold

1. OpenAPI转MCP脚手架

  1. Start from a valid OpenAPI spec.
  2. Generate tool manifest + starter server code.
  3. Review naming and auth strategy.
  4. Add endpoint-specific runtime logic.
bash
python3 scripts/openapi_to_mcp.py \
  --input openapi.json \
  --server-name billing-mcp \
  --language python \
  --output-dir ./out \
  --format text
Supports stdin as well:
bash
cat openapi.json | python3 scripts/openapi_to_mcp.py --server-name billing-mcp --language typescript
  1. 从有效的OpenAPI规范开始。
  2. 生成工具清单 + 初始服务器代码。
  3. 审核命名和认证策略。
  4. 添加端点特定的运行时逻辑。
bash
python3 scripts/openapi_to_mcp.py \
  --input openapi.json \
  --server-name billing-mcp \
  --language python \
  --output-dir ./out \
  --format text
同时支持标准输入：
bash
cat openapi.json | python3 scripts/openapi_to_mcp.py --server-name billing-mcp --language typescript

2. Validate MCP Tool Definitions

2. 验证MCP工具定义

Run validator before integration tests:
bash
python3 scripts/mcp_validator.py --input out/tool_manifest.json --strict --format text
Checks include duplicate names, invalid schema shape, missing descriptions, empty required fields, and naming hygiene.
在集成测试前运行验证器：
bash
python3 scripts/mcp_validator.py --input out/tool_manifest.json --strict --format text
检查内容包括重复名称、无效Schema结构、缺失描述、空必填字段以及命名规范。

3. Runtime Selection

3. 运行时选择

  • Choose Python for fast iteration and data-heavy backends.
  • Choose TypeScript for unified JS stacks and tighter frontend/backend contract reuse.
  • Keep tool contracts stable even if transport/runtime changes.
  • 选择Python用于快速迭代和数据密集型后端。
  • 选择TypeScript用于统一JS技术栈，实现更紧密的前后端契约复用。
  • 即使传输/运行时发生变化，也要保持工具契约稳定。

4. Auth & Safety Design

4. 认证与安全设计

  • Keep secrets in env, not in tool schemas.
  • Prefer explicit allowlists for outbound hosts.
  • Return structured errors (
    code
    , 
    message
    , 
    details
    ) for agent recovery.
  • Avoid destructive operations without explicit confirmation inputs.
  • 将密钥存储在环境变量中，而非工具Schema内。
  • 优先为外部主机使用显式允许列表。
  • 返回结构化错误（
    code
    、
    message
    、
    details
    ）以支持agent恢复。
  • 若无明确的确认输入，避免执行破坏性操作。

5. Versioning Strategy

5. 版本控制策略

  • Additive fields only for non-breaking updates.
  • Never rename tool names in-place.
  • Introduce new tool IDs for breaking behavior changes.
  • Maintain changelog of tool contracts per release.
  • 仅通过添加字段实现非破坏性更新。
  • 切勿直接重命名工具名称。
  • 针对破坏性行为变更引入新的工具ID。
  • 为每个版本维护工具契约的变更日志。

Script Interfaces

脚本接口

  • python3 scripts/openapi_to_mcp.py --help
    • Reads OpenAPI from stdin or 
      --input
    • Produces manifest + server scaffold
    • Emits JSON summary or text report
  • python3 scripts/mcp_validator.py --help
    • Validates manifests and optional runtime config
    • Returns non-zero exit in strict mode when errors exist
  • python3 scripts/openapi_to_mcp.py --help
    • 从标准输入或
      --input
      读取OpenAPI
    • 生成工具清单 + 服务器脚手架
    • 输出JSON摘要或文本报告
  • python3 scripts/mcp_validator.py --help
    • 验证工具清单和可选的运行时配置
    • 在严格模式下，若存在错误则返回非零退出码

Common Pitfalls

常见陷阱

  1. Tool names derived directly from raw paths (
    get__v1__users___id
    )
  2. Missing operation descriptions (agents choose tools poorly)
  3. Ambiguous parameter schemas with no required fields
  4. Mixing transport errors and domain errors in one opaque message
  5. Building tool contracts that expose secret values
  6. Breaking clients by changing schema keys without versioning
  1. 直接从原始路径生成工具名称（如
    get__v1__users___id
    ）
  2. 缺失操作描述（会导致agent难以选择合适工具）
  3. 参数Schema模糊且无必填字段
  4. 在一条模糊消息中混合传输错误和领域错误
  5. 构建暴露敏感值的工具契约
  6. 未进行版本控制就修改Schema键，导致客户端崩溃

Best Practices

最佳实践

  1. Use 
    operationId
    as canonical tool name when available.
  2. Keep one task intent per tool; avoid mega-tools.
  3. Add concise descriptions with action verbs.
  4. Validate contracts in CI using strict mode.
  5. Keep generated scaffold committed, then customize incrementally.
  6. Pair contract changes with changelog entries.
  1. 若存在
    operationId
    ，将其作为标准工具名称。
  2. 每个工具对应一个任务意图；避免创建全能型工具。
  3. 添加包含动作动词的简洁描述。
  4. 在CI中使用严格模式验证契约。
  5. 提交生成的脚手架代码，然后逐步自定义。
  6. 契约变更需搭配变更日志条目。

Reference Material

参考资料

  • references/openapi-extraction-guide.md
  • references/python-server-template.md
  • references/typescript-server-template.md
  • references/validation-checklist.md
  • README.md
  • references/openapi-extraction-guide.md
  • references/python-server-template.md
  • references/typescript-server-template.md
  • references/validation-checklist.md
  • README.md

Architecture Decisions

架构决策

Choose the server approach per constraint:
  • Python runtime: faster iteration, data pipelines, backend-heavy teams
  • TypeScript runtime: shared types with JS stack, frontend-heavy teams
  • Single MCP server: easiest operations, broader blast radius
  • Split domain servers: cleaner ownership and safer change boundaries
根据约束选择服务器方案：
  • Python运行时：迭代更快，适用于数据管道、后端主导的团队
  • TypeScript运行时：与JS技术栈共享类型，适用于前端主导的团队
  • 单一MCP服务器：运维最简单，但影响范围更广
  • 拆分领域服务器：职责划分更清晰，变更边界更安全

Contract Quality Gates

契约质量门槛

Before publishing a manifest:
  1. Every tool has clear verb-first name.
  2. Every tool description explains intent and expected result.
  3. Every required field is explicitly typed.
  4. Destructive actions include confirmation parameters.
  5. Error payload format is consistent across all tools.
  6. Validator returns zero errors in strict mode.
发布工具清单前需满足：
  1. 每个工具都有清晰的动词开头名称。
  2. 每个工具的描述都解释了意图和预期结果。
  3. 每个必填字段都有明确的类型定义。
  4. 破坏性操作包含确认参数。
  5. 所有工具的错误负载格式保持一致。
  6. 验证器在严格模式下返回零错误。

Testing Strategy

测试策略

  • Unit: validate transformation from OpenAPI operation to MCP tool schema.
  • Contract: snapshot 
    tool_manifest.json
    and review diffs in PR.
  • Integration: call generated tool handlers against staging API.
  • Resilience: simulate 4xx/5xx upstream errors and verify structured responses.
  • 单元测试：验证从OpenAPI操作到MCP工具Schema的转换。
  • 契约测试：对
    tool_manifest.json
    进行快照，并在PR中审查差异。
  • 集成测试：调用生成的工具处理程序对接预发布环境API。
  • 韧性测试：模拟上游4xx/5xx错误，验证结构化响应。

Deployment Practices

部署实践

  • Pin MCP runtime dependencies per environment.
  • Roll out server updates behind versioned endpoint/process.
  • Keep backward compatibility for one release window minimum.
  • Add changelog notes for new/removed/changed tool contracts.
  • 为每个环境固定MCP运行时依赖版本。
  • 在版本化端点/进程后推出服务器更新。
  • 至少在一个发布周期内保持向后兼容性。
  • 为新增/移除/变更的工具契约添加变更日志说明。

Security Controls

安全控制

  • Keep outbound host allowlist explicit.
  • Do not proxy arbitrary URLs from user-provided input.
  • Redact secrets and auth headers from logs.
  • Rate-limit high-cost tools and add request timeouts.
  • 明确外部主机允许列表。
  • 不要代理用户输入提供的任意URL。
  • 从日志中脱敏敏感信息和认证头。
  • 对高成本工具进行限流，并添加请求超时设置。