mcp-server-template

用于构建编码代理能够真正良好使用的只读 MCP 服务器的约定式模板：带超时的 I/O 接缝、离线测试、紧凑的文本输出、最小权限文档。

从这里开始 → BUILDING.md — 从想法到发布服务器的完整工作流（约半天）。

包含内容：一个可运行的示例服务器（pypi_project 固定源 HTTP 工具，位于可打桩的接缝之后 + word_stats 纯工具）、离线测试套件、CI 工作流、CLAUDE.md 约定，以及下方的 README 骨架。

网络示例特意不接受任意 URL。"只读"并不会让 URL 抓取器变得安全：不受限制的目标地址和跟随重定向可能暴露回环、私有网络或云元数据服务。pypi_project 仅构造 https://pypi.org/... 请求，拒绝形如 URL/路径的输入，绝不跟随重定向，将解码后的响应限制在 2 MiB 以内，并应用 15 秒的整个操作时限。

你的服务器的 README 骨架（替换整个文件）

1. # mcp-<name> + 一行加粗的价值主张

2. 4 行使用记录（你：… / 代理：→ 工具调用 / 代理：回答）

3. 工具表（工具 → 返回内容）

4. 安装：claude mcp add <name> -e TOKEN=... -- python -m mcp_<name> + .mcp.json 代码块

5. 令牌范围/安全性（最小权限、只读声明）

6. 设计说明（为什么只读、为什么紧凑文本、为什么超时）

7. 许可证 + 联系方式

直接使用上述结构；在发布衍生服务器之前，替换所有模板名称和示例。

Related MCP server: MCP Server Template

安全与隐私

• 该示例仅将提供的包名发送到 PyPI。不要在工具参数中放入机密或私有标识符。

• PyPI 项目摘要是由上传者控制的文字内容，因此该示例特意将其从代理可见的输出中省略。将所有外部文本视为不可信数据。

• 切勿记录凭据、授权头、原始私有响应或用户提示。

• 记录每个参数会发送到哪个外部服务。即使工具只读取私有 CI 日志和内部 URL，它们也是敏感的。

• 除非你实现了目标地址允许列表以及无法通过重定向或 DNS 重绑定绕过的传输机制，否则请勿在衍生服务器中加入任意 URL 抓取功能。

开发

python -m pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest
python -m build

MIT — 参见 LICENSE。