anirbanbasu-pymcp

PyMCP 主要用作模板仓库，供开发者使用 Python 和 FastMCP 开发 MCP 服务；它在一定程度上受到了 官方 everything MCP 服务（使用 Typescript 编写）的启发。

组件

此 MCP 服务提供以下组件。

工具

1. greet

• 用经典的 Hello World 消息问候调用者。
• 输入
  • name：string（可选）：要问候的名称。默认值为 none。
• 输出
  • 包含带 UTC 时间戳问候语的 TextContent。

2. generate_password

• 生成指定长度的随机密码，可选择包含特殊字符，并满足至少包含一个小写字母、一个大写字母和两个数字的复杂度要求。如果包含特殊字符，密码也会至少包含一个此类字符。
• 输入
  • length：integer：生成的密码长度。该值必须是介于 8 和 64 之间（含两端）的整数。
  • use_special_chars：boolean（可选）：指示密码是否应包含特殊字符的标志。默认值为 False。
• 输出
  • 包含生成密码的 TextContent。

3. text_web_search

• 使用 Dux Distributed Global Search (DDGS) 根据文本查询搜索网络。
• 输入
  • query：string：用于获取结果的搜索查询。必须是非空字符串。
  • region：string（可选）：两位国家代码，后接连字符，再接两位语言代码，例如 uk-en 或 us-en。默认值为 uk-en。
  • max_results：integer（可选）：要获取的最大结果数（可选）。默认值为 10。
  • pages：integer（可选）：结果分布的页数（可选）。默认值为 1。
• 环境变量
  • DDGS_PROXY：string（可选）：用于外发网络搜索请求的代理服务（可选）。
• 输出
  • 包含搜索结果字典列表的 TextContent。

4. permutations

• 计算从 $n$ 个项目中不重复、有顺序地选择 $k$ 个项目的方法数。如果未提供 $k$，则默认为 $n$。
• 输入
  • n：integer：可供选择的项目数。必须是非零正整数。
  • k：integer（可选）：要选择的项目数。默认值为 n 的值。
• 输出
  • 包含从 $n$ 个项目中选择 $k$ 个项目的方法数的 TextContent，即 ${}^{n}P_{k}$。

5. run_python_code

• 使用 Pydantic Monty 在安全且快速的解释器中运行任意 Python 代码。请注意，Pydantic Monty 仍处于实验阶段；截至 2026 年 2 月 8 日，其对 Python 语言的支持尚不完整。
• 输入
  • code：string：要运行的 Python 代码。
  • inputs：dict[str, Any]（可选）：供 Python 代码使用的输入值字典。默认值为 None。
  • script_name：str（可选）：用于回溯和错误消息的脚本名称。默认值为 main.py。
  • check_types：bool（可选）：指示是否检查类型的标志。默认值为 True。
  • type_definitions：str（可选）：用于类型检查的类型定义。默认值为 None。
• 输出
  • 包含 Python 代码输出（如有）的 TextContent。

说明

pirate_summary（LLM 客户端采样）和 vonmises_random（客户端引导）这两个示例工具已移除。它们都依赖服务端发起的请求（ctx.sample() 和 ctx.elicit()），而 SEP-2577 已在现代 MCP 协议（2026-07-28）中移除此类请求，改为采用无状态的逐请求封装，不再提供服务端回调客户端的反向通道。FastMCP 现在将这两个 API 标记为已弃用——它们仍可运行，但仅适用于较旧的握手时代（基于会话）的协议。我们选择移除这些工具，而不是让它们继续依赖已弃用的协议时代。

这不会影响其余的工具、资源和提示词：底层 MCP SDK 会按连接协商协议版本，并自动支持 2026-07-28+ 和握手时代的客户端，无需在此更改代码。只有服务端发起的反向通道模式（即使用 ctx.sample() 或 ctx.elicit() 的任何功能）仅适用于旧版协议。如果你 Fork 此模板，并希望添加依赖客户端采样或引导的工具，请注意，它只能在协商使用较旧、已弃用协议的客户端上运行。

资源

1. resource_logo

• 获取 PyMCP 的 Base64 编码 PNG 徽标及其 SHA3-512 哈希值。
• URL：data://logo
• 输出
  • TextContent，其中包含一个 Base64EncodedBinaryDataResponse Pydantic 对象，字段如下。
    • data：string：PyMCP 的 Base64 编码 PNG 徽标。
    • hash：string：原始二进制数据的十六进制编码加密哈希值，该原始数据由 data 中的 Base64 编码字符串表示。（预期的十六进制编码哈希值为 6414b58d9e44336c2629846172ec5c4008477a9c94fa572d3419c723a8b30eb4c0e2909b151fa13420aaa6a2596555b29834ac9b2baab38919c87dada7a6ef14。）
    • hash_algorithm：string：所用的加密哈希算法，例如 sha3_512。

2. resource_logo_svg

• 获取 PyMCP 的 SVG 徽标。
• URL：data://logo_svg
• 输出
  • TextContent，包含 PyMCP 徽标的 SVG 数据。

3. resource_unicode_modulo10

• 计算给定数字除以 10 的余数，并返回表示该结果的 Unicode 字符。根据余数是奇数还是偶数来选择字符。余数为奇数时，使用 Unicode 字符 ❶（U+2776）、❸（U+2778）、❺（U+277A）、❼（U+277C）和 ❾（U+277E）。余数为偶数时，使用 Unicode 字符 ⓪（U+24EA）、②（U+2461）、④（U+2463）、⑥（U+2465）和 ⑧（U+2467）。
• URL：data://modulo10/{number}
• 输入
  • number：integer：1 到 1000（含）之间的正整数。
• 输出
  • TextContent，其中包含表示相应 Unicode 字符的字符串。

提示词

1. code_prompt

• 获取一个提示词，根据指定任务用 Python 编写代码片段。
• 输入
  • task：string：将用于生成代码实现提示词的任务描述。
• 输出
  • 表示该提示词的 str。

安装

在此将克隆此仓库的目录称为_工作目录_或_WD_。

安装 uv。安装 just。若要在虚拟环境中安装项目及其最少依赖项，请在_WD_中运行以下命令。若要安装所有非必需依赖项（开发和测试所需），请在以下命令中将 install 目标替换为 install-all 目标。

just install

环境变量

可以配置以下环境变量。

• PYMCP_LOG_LEVEL：设置 PyMCP 服务的 Python 日志级别。默认值为 INFO。
• MCP_SERVER_TRANSPORT：设置此 MCP 服务的 FastMCP 服务传输类型。默认值为 stdio。
• RESPONSE_CACHE_TTL：设置用于缓存服务提示词、资源和工具响应的 TTL 缓存有效时长，单位为秒。默认值为 30。0 到 86400（即一天）之间的任意整数（含两端）均有效。设为 0 即可禁用响应缓存。
• FASTMCP_HOST：使用网络传输（例如 streamable-http、sse）时，设置 FastMCP 服务的主机地址。默认值为 localhost。
• FASTMCP_PORT：使用网络传输时，设置 FastMCP 服务的端口号。默认值为 8000。
• ASGI_CORS_ALLOWED_ORIGINS：通过 HTTP 传输启动 MCP 服务时，设置 CORS 允许的来源。默认值为 ["*"]。

独立使用

运行以下命令，即可通过 stdio 传输独立启动 PyMCP 作为 MCP 服务。也可以通过 MCP_SERVER_TRANSPORT 环境变量指定传输类型，使用 streamable-http 或 sse 传输启动。

uv run pymcp

使用 MCP Inspector 测试

MCP Inspector 是一款 官方 的模型上下文协议工具，开发者可用它测试和调试 MCP 服务。这是探索 MCP 服务最全面的方式。

要使用它，必须安装 Node.js。安装和管理 node 以及 MCP Inspector 等软件包的最佳方式是使用 Node 版本管理器（即 nvm）。安装好 nvm 后，运行以下命令即可安装并使用最新的长期支持版本 node。

nvm install --lts
nvm use --lts

然后，在 WD 中运行以下命令，启动 MCP Inspector 和 PyMCP。

npx @modelcontextprotocol/inspector uv run pymcp

这会在端口 6274 创建一个带有身份验证令牌的本地 URL，你可以复制该 URL 并在浏览器中打开。进入 MCP Inspector 界面后，点击 Connect 连接到 MCP 服务。之后，你可以探索服务提供的工具。

你也可以运行 just launch-inspector 启动 MCP Inspector。

与 Claude Desktop、Visual Studio 等配合使用

以下是通过 stdio 传输运行服务时的入口配置，可用于 Claude Desktop、Visual Studio Code 等系统。

{
    "command": "uv",
    "args": [
        "run",
        "pymcp"
    ]
}

你可能需要将 args 列表的最后一项 pymcp 替换为脚本的完整路径，例如 WD/.venv/bin/pymcp。

远程托管选项

目前可用的远程托管选项如下。

• FastMCP Cloud：https://pymcp-template.fastmcp.app/mcp
• Glama.AI：https://glama.ai/mcp/servers/@anirbanbasu/pymcp

测试与覆盖率

要使用 pytest 运行提供的测试集，请在 WD 中执行以下命令。要在运行测试时生成覆盖率报告，请在 WD 中运行以下命令。

just test-coverage

这会生成类似以下的输出。

Name    Stmts   Miss    Cover   Missing
---------------------------------------
TOTAL     214      0  100.00%

贡献

请参阅贡献指南。

许可证

MIT。