DevTools MCP

一个面向开发者的小型实用 MCP 服务器，旨在端到端地学习 Model Context Protocol：服务器实现、本地测试、使用现有 MCP、公开发布以及 Smithery 发布。

1. 概述

DevTools MCP 通过 Model Context Protocol 提供四个小型开发者工具：解释错误信息、校验/格式化 JSON、根据描述生成正则表达式，以及使用 LLM（Grog）总结文本。一个极简的 TypeScript/Vite 仪表盘让你可以在浏览器中实际操作这些工具，并以真实 MCP 客户端的身份建立连接。

Related MCP server: ai-assistant

2. 为什么选择 MCP

MCP 标准化了 LLM 主机（Claude Desktop、IDE 或智能体）探测和调用工具的方式，而不是让每个项目都自行发明一套专用的工具调用 API。项目的首要学习目标是构建一个真正的 MCP 服务器——而不是一个贴了“MCP”标签的 REST API。

3. 架构

MCP Client
    |
MCP Protocol
    |
DevTools MCP Server
    |-- explain_error    (local/deterministic)
    |-- format_json      (local/deterministic)
    |-- generate_regex   (local/deterministic)
    `-- summarize_text
            |
        Groq API
            |
        GPT-OSS 120B

服务器（server/server.py）是一个 mcp.server.MCPServer（MCP Python SDK v2）。它通过 stdio 进行本地测试（MCP Inspector、Client(mcp)），并通过 Streamable HTTP（/mcp）实现远程/浏览器访问。TypeScript 前端（frontend/）是一个真正的 MCP 客户端：它使用 @modelcontextprotocol/sdk 的 Client 与 StreamableHTTPClientTransport 直接通过 Streamable HTTP（服务器已启用 CORS）与服务器通信，而不是自研的 REST 桥接层。

4. 工具

5. 项目结构

devtools-mcp/
├── server/
│   ├── server.py               # MCPServer + tool registration + ASGI app
│   ├── tools.py                # explain_error / format_json / generate_regex logic
│   ├── ai.py                   # Groq-backed summarize_text logic
│   └── tests/
│       └── test_server.py      # pytest suite using the SDK's in-memory Client
├── frontend/
│   ├── index.html
│   ├── src/
│   │   ├── main.ts             # real MCP client (StreamableHTTPClientTransport)
│   │   └── style.css
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── .env.example
├── .gitignore
├── requirements.txt
├── render.yaml                 # optional Render Blueprint
├── README.md
└── EXISTING_MCP_EXPERIENCE.md

6. 前提条件

• Python 3.10+

• Node.js 18+ 和 npm（用于前端，也用于通过 npx 运行 MCP Inspector）

• 一个 Groq API 密钥（仅 summarizeliz 需要）

• （可选，用于部署）一个 Render 账号和一个 Smithery 账号

7. 安装

git clone <this-repo>
cd devtools-mcp
python3 -m venv .venv
. .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

8. 环境变量

将 .env.example 复制为 .env，填入所需内容：

GROQ_API_KEY=            # required for summarize_text
GROQ_MODEL=openai/gpt-oss-120b
MCP_ALLOWED_HOSTS=        # only needed when deployed behind a real hostname
MCP_ALLOWED_ORIGINS=      # comma-separated browser origins allowed via CORS

.env 已被 git 忽略。绝不要把真实密钥提交到版本库。

9. 本地配置

Stdio（默认，适用于本地 MCP 客户端）：

python -m server.server

Streamable HTTP（适用于前端，或任何基于 HTTP 的 MCP 客户端），仅限本地：

uvicorn server.server:app --host 127.0.0.1 --port 8000

在本地 MCP_ALLOWED_HOSTS 可以不设置——SDK 内置的仅限 localhost 的 DNS 重绑定防御会自动覆盖 127.0.0.1/localhost。健康检查：curl http://127.0.0.1:8000/health。

10. 使用 MCP Inspector 测试

# Against stdio:
uv run mcp dev server/server.py     # requires uv; or: npx @modelcontextprotocol/inspector
# Against a running Streamable HTTP server:
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list

开发阶段已针对本地 Streamable HTTP 服务器运行该测试，并验证了所有四个工具均可被发现，且输入/输出 schema 正确（具体结果见下文“测试”部分）。

11. 前端配置

cd frontend
npm install
npm run dev          # http://localhost:5173

在运行中的仪表盘中，将服务器 URL 字段设置为本 MCP 服务器的 /mcp 端点（默认 http://localhost:8000/mcp），点击 Connect，选择工具，填写表单，然后点击 Run。本地使用请以 MCP_ALLOWED_ORIGINS=http://localhost:5173 启动后端，以便 CORS 放行该来源。

生产构建：npm run build（输出到 frontend/dist/）。

12. Groq 配置

1. 在 console.groq.com 创建 API 密钥。

2. 在 .env 中或部署平台的环境变量中设置 GROQ_API_KEY（以及可选的 GROQ_MODEL，默认是 openai/gpt-oss-120b）。

3. 本项目中的任何其他部分都不使用其他 LLM 提供商。

13. 使用现有 MCP 的体验

有关“必须演示如何使用已有 MCP 服务器（Context7）”的内容——它是什么、如何连接、实际执行的查询以及收获——请参阅 EXISTING_MCP_EXPERIENCE.md。

14. 探索 Render 部署

使用 Render 原生 Python 运行时（不需要 Docker）。

仪表盘设置：

1. 把本仓库推送到 GitHub。

2. 在 Render 中：New → Web Service → 关联仓库。

3. 运行时：Python 3。构建命令：pip install -r requirements.txt。启动命令：uvicorn server.server:app --host 0.0.0.0 --port $PORT。

4. 设置环境变量：GROQ_API_KEY，GROQ_MODEL，MCP_ALLOWED_HOSTS=<your-service>.onrender.com,<your-service>.onrender.com:*，以及 MCP_ALLOWED_ORIGINS=<your-frontend-origin>（如果你同时部署前端）。

5. 部署。MCP 端点将是 https://<your-service>.onrender.com/mcp。

还提供 render.yaml BluePrint 作为同样的设置的便捷方式。

**必须手动验证的步骤：**实际部署需要 Render 账号，本次回复并未实际执行该步骤——具体仍属于手动的部分，见完成报告。

15. Smithery 发布

当前的 Smithery CLI 可以直接发布已经托管的远程 MCP 服务器 URL（此路径不需要 Docker/容器打包）：

npm install -g smithery
smithery auth login
smithery mcp publish "https://<your-service>.onrender.com/mcp" -n "<your-org>/devtools-mcp"

发布后，请验证四个工具是否已暴露：

smithery mcp add "https://<your-service>.onrender.com/mcp" --id devtools-mcp
smithery tool list devtools-mcp

需要手动执行的步骤： 此步骤首先需要一个 Smithery 账号和一个已上线且可公开访问的 Render 部署；本次回复中未实际执行。

16. 公开的 MCP 用法

部署完成后，任何支持 StreamableHTTP MCP 的客户端都可以连接到：

https://<your-service>.onrender.com/mcp

SDK 的 Client 示例：

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with streamable_http_client("https://<your-service>.onrender.com/mcp") as (r, w, _):
    async with Client(r, w) as client:
        await client.initialize()
        print(await client.list_tools())

17. 测试

在本环境中实际运行：

pytest server/tests/ -v

结果：11 项通过——工具发现；format_json 的合法、畸形和空输入；expline_error 的匹配与不匹配模式（包括空输入）；generate_regex 对已知模式（并发起了一次真实的正则匹配检查）和未匹配的描述；summarize_text 在缺少 GROQ_API_KEY 时和空输入时的行为。

另外，还手动（在 pytest 之外）做了实际运行：

• uvicorn server.server:app 成功启动；/health 返回 {"status":"ok", ...}。

• 一个原始的 initialize JSON-RPC POST 至 /mcp 返回 200。

• 真正的 MCP Inspector CLI（npx @modelcontextprotocol/inspector --cli）通过 Streamable HTTP 连接成功，列出的四个工具 schema 均正确，并且成功调用了 generate_regex、expline_error 和 format_json（同时支持合法和非法 JSON）、以及 summarize_text（由于预期用真实 Groq 密钥，故正确地报出没有 API 错误）。

• 传输安全性已验证：伪造 Host 头的请求正确收到了 421 Misdirected Request。

• CORS 预检已验证：带 Origin: http://localhost:5173 的 OPTIONS /mcp 请求在设置 MCP_ALLOWED_ORIGINS 后返回 200 且带正确的 access-control-* 头。

• 前端：npx tsc --noEmit 无错误；通过 npm run build 成功生成 frontend/dist/。

未验证（需要当前环境不具备的外部账户/凭据）：使用真实 Groq API 密钥完成 summarize_text 真实调用、Render 部署本身、Smithery 发布/上架。

18. 局限

• summarize_text 只在错误路径上做了端到端测试；还从未用真实 Groq 凭据调用过。

• Render 部署和 Smithery 发布需要你自己账号下的手动操作（见第 14-15 节），此处未执行。

• expline_error 和 generate_regex 使用很小的手写模式库，而非 LLM；项目设定本就不打算做成“全知”，因此它们不会识别所有可能的错误或描述的模式。

• 按项目范围要求“无需账户/无需认证，前端没有认证机制，仅用于本地/演示用途”。

19. 学习成果

• MCP 是什么： 一种标准化协议，将“为 LLM 提供上下文/动作”与“LLM 交互本身”分离，因此一次构建而成的服务器（例如本项目）可以与任何符合规范的客户端一起工作。

• Host/Client/Server： host是 LLM 应用程序（Claude Desktop，或者浏览器仪表盘背后的应用）；client 是其内部用 MCP 交谈的组件（SDK 的 Client，或我们前端基于 StreamableHTTPClientTransport 的客户端）；server 是这个地方构建的模块——它绝不会直接与模型对话。

• 工具 vs. 资源 vs. 提示词： 工具由模型控制（LLM 决定调用 format_json）；资源由 application 按自己控制数据加载；prompts是用户触发的模板。本项目只需要工具即可。

• 工具的发现与调用： 调用 tools/list，你能看到可用的工具内容（名称、描述、JSON-schema 的输入/输出，这些都自动从 Python 类型标注和 docstrings 生成），之后以入参调用 tools/call 工具，指定 method名字完成调用。

• 为什么 MCP 胜过 plain REST API： REST API 需要为每个客户端做自定义集成；而 MCP 服务器能描述自己的能力和 schema，因此任何认识 MCP 的主机无需定制拼接层即可使用——把同一个服务器同时接入 MCP Inspector 和我们自己构建的前端客户端，并且服务端零改动，即直接证据。

• LLM 应放在哪里： 只存在于 summarize_text 内部，它调用端点 Groq。服务器其余部分是确定性普通代码——这说明“MCP 服务器”和“AI 应用”是不同的两回事，也值得注意。

• 部署的现实： Streamable HTTP 服务器默认只放行 localhost 的 Host/Origin 白名单（安全考虑）；一旦放在真实域名之后运营，必须显式放开（TransportSecuritySettings）——这通过实际操作触发一次 421 并随后修复，得到了手工确认。