mcpforge

mcpforge

输入一句英文描述，输出经过测试、无需编写规范的 FastMCP 3.x 服务。

mcpforge 可将简单的英文描述转换为完整的 FastMCP 3.x MCP 服务，包含工具、Pydantic 输入验证、错误处理、pytest 测试套件、运行配置和客户端设置文档，并将它们全部整合到一起，随时可供检查、验证和安装。无需手动编写 MCP 架构或协议样板代码：这句话就是规范。由你描述需求，Claude 编写实现，mcpforge 则会在你运行之前执行生成的测试套件和验证器。

⚡ 60 秒快速开始

你需要 Python 3.12+、uv 和 Anthropic API 密钥。

uv tool install fastmcp-builder      # or: pip install fastmcp-builder
export ANTHROPIC_API_KEY="your_anthropic_api_key"

mcpforge generate "A weather server that returns today's forecast for a city" -o weather-server

还没有密钥？试试演示。 mcpforge demo 会针对内置录制内容运行真实的 plan → generate → validate 流程，并写入一个完整且经过验证的天气服务，无需 API 密钥，也不会产生费用。这是了解 mcpforge 具体产出最快的方式：

uvx --from fastmcp-builder mcpforge demo

使用你自己的密钥（BYOK）。 生成过程使用你自己的 Anthropic API 密钥——mcpforge 会直接调用 Claude API，不会通过托管服务转发。单次 generate 会调用模型数次（plan → server → tests），因此在默认模型（claude-sonnet-4-6）下，典型运行的 API 使用费用约为 $0.05–$0.30。此数值是估算值，会随服务复杂度和你选择的模型而变化，并非实时测量结果。所有不调用模型的操作——validate、inspect、list、doctor 和 init——均免费。

整个流程就是这样。mcpforge 会规划工具、生成代码，然后针对生成结果运行语法、安全、lint、导入和 pytest 检查，因此写入 ./weather-server/ 的内容已经过验证：

# weather-server/server.py  (excerpt)
"""Weather forecast MCP server."""

from fastmcp import FastMCP

mcp = FastMCP("Weather")

# Illustrative lookup — describe a real source and mcpforge wires the call for you.
_FORECASTS: dict[str, dict] = {
    "san francisco": {"high_c": 18, "low_c": 12, "summary": "Foggy"},
    "denver": {"high_c": 24, "low_c": 9, "summary": "Clear"},
}


@mcp.tool
async def get_forecast(city: str) -> dict:
    """Return today's forecast for a city."""
    key = city.strip().lower()
    if key not in _FORECASTS:
        raise ValueError(f"No forecast available for {city!r}")
    return {"city": city, **_FORECASTS[key]}


if __name__ == "__main__":
    mcp.run(transport="streamable-http")

每次生成还会创建 test_server.py（真实的 pytest 测试套件）、pyproject.toml、README.md 和 MCP 客户端 config.json——这是一个完整项目，而非代码片段。运行方式如下：

cd weather-server
uv run server.py            # start the server (streamable-http)
uv run pytest -v            # run the generated tests
mcpforge validate .         # re-run the full validation suite anytime

上面的代码片段是文档中的示例玩具项目（“weather”）。实际生成的内容会符合你的描述——可查看 examples/ 中实时生成的服务（todo、文件读取器、数据库查询、Slack 通知器、TypeScript）。

构建，然后审计 — MCP 工具包

mcpforge 有一个姊妹项目：mcp-audit（在 PyPI 上名为 mcp-audits）。它们是同一工作流的两个环节 — 先构建服务，再审计 Agent 实际能够访问的内容，然后再决定是否信任它。

阶段	工具	功能
构建	mcpforge	根据一句话生成完整且经过测试的 MCP 服务。
审计	mcp-audit	扫描机器上接入的每个 MCP 服务，并评估各自可访问内容的风险。

# build
mcpforge generate "A weather server that returns today's forecast for a city" -o weather-server

# audit everything your agents can reach (read-only, no install needed)
uvx --from mcp-audits mcp-audit scan --ssrf-check

mcp-audit 默认只读 — 它绝不会编辑配置，并且只报告环境变量的键名，不会报告其值。放心构建，然后确认影响范围。

可供注册表使用的元数据位于 server.json 中，其中 MCP Registry 名称为 io.github.saagpatel/mcpforge，PyPI 软件包为 fastmcp-builder。请将此元数据视为 用于发现和溯源的背景信息，而非生成的服务无需审核即可安全运行的证明。

用作 MCP 服务

mcpforge 本身就是一个 MCP 服务：将 MCP 客户端（Claude Code、Claude Desktop、Cursor）连接到它，Agent 就能在对话中构建、验证和检查 MCP 服务。它通过 stdio 在本地运行（会将文件写入你的工作区，并使用你自己的密钥调用模型提供商），因此不提供托管式远程服务。

uvx fastmcp-builder

将其添加到客户端配置中（此处以 Claude Code 为例）。generate、update 和 plan 会调用模型提供商，因此请在服务环境中设置密钥：

{
  "mcpServers": {
    "mcpforge": {
      "command": "uvx",
      "args": ["fastmcp-builder"],
      "env": { "ANTHROPIC_API_KEY": "<your-key>", "MCPFORGE_WORKSPACE": "/path/to/workspace" }
    }
  }
}

工作区路径会根据 MCPFORGE_WORKSPACE 解析，并限制在该路径范围内。请注意，generate 和 update 会写入文件，并产生模型提供商费用（使用你的密钥时，每次调用约为 $0.05 至 $0.30）。

工具	功能	写入	费用	关键参数
generate	根据描述生成完整且经过测试的 FastMCP 3.x 服务	是（工作区）	API 调用	description、language、transport、output_path、dry_run
update	对现有生成的服务应用自然语言更改	是（工作区）	API 调用	server_path、request
plan	提取结构化的服务计划，但不生成代码	否	API 调用	description、transport
validate	对生成的服务执行语法、lint、导入和 pytest 检查	否（会执行测试）	无	server_path
inspect	在不执行服务的情况下对其进行概述	否	无	server_path
doctor	检查本地先决条件和提供商就绪状态	否	无	workspace_path
list_generated_servers	列出工作区中由 mcpforge 生成的服务	否	无	workspace_path、recursive

功能

• 纯英文生成——用自然语言描述你的服务；Claude 会编写实现
• 完整的项目脚手架——同时生成工具、Pydantic 输入模型、错误处理、pyproject.toml 和 pytest 测试套件
• 原生支持 FastMCP 3.x——输出采用现代 FastMCP 装饰器和传输配置，而不是原始 MCP 协议样板代码
• 运行前先验证——mcpforge validate 会针对生成的服务执行语法、安全、lint、导入和 pytest 检查
• 安全迭代——mcpforge update 会修改现有生成服务，并在写入前备份已更改的文件
• 发现生成的服务——mcpforge list 会在工作区中查找由 mcpforge 生成的项目
• 检查和诊断——mcpforge inspect 会概述生成的服务结构，mcpforge doctor 会检查本地环境是否就绪
• 机器可读输出——类似状态的命令提供 --json，供 Agent 工作流使用
• OpenAPI 筛选控制——包含/排除标签、操作允许列表和操作数量限制，让生成的集成保持聚焦
• 无需大模型即可搭建脚手架——mcpforge init 会创建最精简的 FastMCP 服务骨架，便于本地迭代
• MCP 服务模式——mcpforge-server 提供生成、规划、验证、检查、诊断和发现工具，让 AI 助手能够安全地构建

更多命令

PyPI 发行包名为 fastmcp-builder；安装后的命令为 mcpforge 和 mcpforge-server。除 generate 之外：

# See it work with no API key — generate a weather server from a built-in recording
mcpforge demo

# Generate a new MCP server
mcpforge generate "A todo list manager with create, read, update, and delete operations"

# Validate an existing generated server
mcpforge validate ./my-server

# Modify an existing generated server
mcpforge update ./my-server "Add a tool to export todos as CSV"

# Find generated servers in the current workspace
mcpforge list . --recursive

# Inspect a generated server without executing it
mcpforge inspect ./my-server

# Check local prerequisites and provider readiness
mcpforge doctor

实用的生成标志：

• --dry-run 显示结构化计划，但不写入文件。
• --no-execute 写入文件，但跳过依赖安装和生成代码执行。Python 仍会报告静态语法、安全性和 lint 结果；不会运行导入和生成的测试。TypeScript 也会跳过类型检查和生成的测试，其 MCP 响应会报告 validation_mode: "write_only" 和 tests_status: "not_run"。基于提供方的规划和代码生成仍可能调用 API。仅凭旧版 tests_ok 标志无法证明测试已运行。
• --strict 将 Python lint 错误视为硬性验证失败；TypeScript 没有 lint 阶段。
• --from-openapi FILE 根据 OpenAPI 3.x 规范生成。
• --openapi-include-tag TAG、--openapi-exclude-tag TAG、--openapi-operation ID 和 --openapi-limit N 用于筛选 OpenAPI 转换内容。
• --language python|typescript 选择目标服务端语言。
• --auth-profile none|api-key|jwt 添加可选的 Python 身份验证配置元数据和环境变量文档。
• --middleware-profile logging|timing|rate-limit 添加可选的 Python 中间件配置；可重复使用此标志来组合多个配置。
• --provider anthropic|openai|openrouter 选择生成提供方。openrouter 是“使用任意模型”的途径：设置 OPENROUTER_API_KEY，并通过 --model 选择任意 OpenRouter 模型（例如 --model anthropic/claude-opus-4.8），包括免费和低成本模型。不同模型的生成质量和结构化输出支持各不相同——推荐模型为 Claude Opus 4.8（xHigh）和／或 GPT 5.5（High/Extra High）。openai 包是默认依赖项（包含在所有安装中），因为 --provider openai 和 --provider openrouter 都依赖它；设置 MCPFORGE_ENABLE_OPENAI_PROVIDER=1 即可启用直接 OpenAI 提供方，以便使用 OPENAI_API_KEY。

实用的状态标志：

• mcpforge list --json
• mcpforge inspect PATH --json
• mcpforge validate PATH --json
• mcpforge doctor --json
• mcpforge version --json

mcpforge doctor --json 始终会输出完整的 JSON 报告；当报告的 ok 为 true 时退出码为 0，为 false 时退出码为 1，与普通的 doctor 行为一致。

对于 Cloud 开发，请使用可移植的 MCP Forge Cloud 工作流技能。 它涵盖预先准备的启动流程和无需凭据的检查、继续处理已授权的现有 PR，以及在已配置的 Git 传输受阻时使用经过测试的 GitHub 连接器回退方案，并在交付前验证远程历史记录和经过测试的内容。

技术栈

层级	技术
语言	Python 3.12+
生成	通过 anthropic SDK 使用 Anthropic Claude；通过 openai SDK 使用 OpenAI 和 OpenRouter（默认包含）
MCP 框架	FastMCP 3.x
命令行界面	Click 8
模板	Jinja2
验证	Pydantic v2
输出	Rich

开发环境设置

仓库在 .python-version 中固定使用 Python 3.12.15，并要求 uv 0.13.0 或更高版本。设置锁定环境并运行完整的本地检查：

make setup
make check

make check 包含对 examples/todo-server 的验证；在 macOS 上会使用可用的 sandbox-exec 隔离边界。CI 会在示例验证命令中禁用该封装器，因为 GitHub 托管的运行器不提供它。

架构

generate 命令会将用户的描述发送给 Claude，并附上结构化提示词，其中包含 FastMCP 3.x 惯用模式和工具架构契约。Claude 会返回一个 JSON 计划（工具名称、签名和描述），mcpforge 会先用 Pydantic 模型进行验证，再通过 Jinja2 模板将其渲染为完整的项目目录。随后，生成的项目会通过语法检查、安全扫描、ruff lint、导入检查和 pytest 执行进行验证。update 命令会读取现有的生成式服务，请 Claude 进行针对性修改，为变更的文件创建备份，并验证结果。

状态

技术栈

当前软件包版本为 0.3.4，已以 fastmcp-builder 名称发布到 PyPI。该版本新增了 fastmcp-builder 控制台脚本别名，并修正了注册表元数据。版本 0.3.3 新增了 mcpforge demo、OpenRouter 提供方和 MCP Registry 元数据。项目面向 Python 3.12+ 和 FastMCP 3.x。代码库工具链固定使用 Python 3.12.15，并要求 uv 0.13.0 或更高版本。

已知风险

• 常规验证期间会运行生成的代码。macOS 在 sandbox-exec 可用时会使用它；非 macOS 上的验证不会使用沙盒。使用前请检查生成的代码。
• Python 的 --no-execute 只会执行静态语法、安全和 lint 检查；不会运行导入检查和生成的测试。静态检查结果不能证明代码在运行时的行为。
• 更新命令目前支持 Python 服务。TypeScript 验证的范围比 Python 验证流程更窄，且不会使用 Python lint 或安全检查阶段。
• 提供方兼容性和部署就绪情况取决于所选提供方和环境。请参阅提供方矩阵。

后续步骤

规划发布工作前，请参阅 CHANGELOG.md 了解发布历史，并参阅提供方矩阵了解托管提供方的就绪情况。

完整版本历史请参阅 CHANGELOG.md。

许可证

MIT