AI导哈

计算器协议演示

一个展示最小化模型上下文协议（MCP）服务器和客户端通过stdio连接的示例，包含计算器工具和问候资源。

  • by Gerr1ck
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Gerr1ck/py_mcp

使用说明

py_mcp 可以翻译为“Python MCP（微控制器协议/模块/库等，具体含义需根据上下文确定）”。不过，由于“MCP”本身是一个较为通用的缩写，没有固定的中文翻译，所以具体翻译时需要根据“py_mcp”在上下文中的具体含义来确定“MCP”的准确翻译。如果“MCP”是一个特定项目、库或协议的名称，那么应该直接使用其官方或通用的中文名称。在缺乏具体上下文的情况下，“Python MCP”是一个较为通用的翻译

一个小型演示，展示了最小化的模型上下文协议（MCP）服务器以及通过标准输入输出（stdio）与其连接的客户端。

这个仓库包含一个玩具级的计算器服务器，提供了几个工具（加法、减法、乘法、除法），以及一个小型客户端，用于演示如何列出资源/工具、读取资源以及调用工具。

仓库布局

  • client/
    • calc_client.py — 示例异步客户端，运行服务器进程并通过标准输入输出进行通信。
  • server/
    • calc_server.py — 示例MCP服务器，用于注册计算器工具和问候资源。
  • README.md — 这个文件。

要求

  • Python 3.8+（运行客户端和服务器的环境应具有兼容的Python版本）。代码已在Python 3.13上测试过，但任何现代的3.x版本应该都可以正常工作。
  • 该 mcp 包（示例中使用的MCP框架）必须能够在Python环境中导入。这意味着：
    • 你有 mcp 安装到当前激活的虚拟环境中，或者
    • 你的PYTHONPATH包含了某个位置的路径 mcp 软件包/源代码树。

如果你没有 mcp 如果已可用，请通过常规的软件包源进行安装，或者设置 PYTHONPATH 以使软件包可被导入。

快速入门（Windows PowerShell）

打开PowerShell并切换到此存储库的目录 py_mcp 目录：

cd C:\path\to\py_mcp

选项A — 在已有的环境中运行 mcp 已安装：

# Run the server in one terminal
python .\server\calc_server.py

# In another terminal (same virtualenv/interpreter) run the client
python .\client\calc_client.py

选项B — 如果 mcp 是一个本地包的兄弟包（或者你希望不安装直接运行），请将当前目录添加到PYTHONPATH中，以便 mcp 可以导入：

$env:PYTHONPATH = $PWD
python .\server\calc_server.py
# In another terminal (same $env:PYTHONPATH value):
$env:PYTHONPATH = $PWD
python .\client\calc_client.py

检查员（可选）

如果您希望使用一个交互式的可视化检查器来探索正在运行的MCP服务器，可以使用模型上下文协议检查器。它会启动一个本地用户界面，该界面可以连接到服务器进程，并显示通过协议注册的工具、资源以及交换的消息。

从（某个位置）运行此命令 server 目录（它使用 npx 在不全局安装的情况下运行检查器：

npx @modelcontextprotocol/inspector python calc_server.py

关于检查员的注意事项：

  • 检查器将使用您提供的Python解释器来生成服务器脚本（此处 python calc_server.py）。 确保同一个翻译人员能够访问（相关内容/系统/资料等，具体根据上下文补充） mcp 包裹。
  • 该检查器是一款用于检查和调试MCP服务器的开发工具——它显示可用的工具/资源、请求/响应消息，并帮助您以交互方式使用这些工具。
  • 如果命令因以下错误而失败： npx 或者权限，确保已安装 Node.js（它提供了 npx已安装且在您的 PATH 中可用，或者全局或本地安装 inspector 包并直接运行它。

检查员故障排除

运行检查器时可能会遇到的常见问题及解决方法：

  • “'npx' 不被识别为内部或外部命令”——表示 Node.js / npm 未安装或未添加到您的系统路径中。请从 https://nodejs.org/ 安装 Node.js（其中包含 npm），然后重新打开终端。
  • 运行时出现“Permission denied”或EACCES错误 npx — 在Windows上，这种情况并不常见；请尝试以管理员身份运行PowerShell，或者在项目中本地安装inspector包（npm i @modelcontextprotocol/inspector) 并通过以下方式运行它 npx 或者 npx --no-install @modelcontextprotocol/inspector ...。
  • ModuleNotFoundError: No module named 'mcp' — 检查器使用您提供的Python解释器来启动您的服务器。请确保该解释器可以访问 mcp 包（将其安装到虚拟环境中，或者设置 PYTHONPATH （包括包位置）。你可以通过直接运行服务器脚本来复现问题：
python .\calc_server.py

并首先修复那里可能存在的导入错误。

  • 检查器无法连接/显示传输错误 — 请验证检查器是否正在启动服务器脚本，并且该脚本是否通过标准输入输出（stdio）使用模型上下文协议（MCP）。当以这种方式启动时，检查器期望服务器进程能够遵循通过标准输入输出使用的模型上下文协议。

注：

  • 示例客户端使用 sys.executable 启动服务器时，请确保服务器和客户端使用相同的Python解释器/虚拟环境，以避免导入问题。
  • 如果你看到 ModuleNotFoundError: No module named 'mcp'，请验证是否 mcp 已安装，或者PYTHONPATH指向了一个包含（所需内容）的文件夹 mcp 包裹/软件包/程序包。

演示程序的作用

  • server/calc_server.py 注册了四种工具： add， subtract， multiply，以及 divide它还通过模板暴露了一个动态资源 greeting://{name} 该函数返回为所提供名称生成的问候字符串。
  • client/calc_client.py 启动服务器作为子进程（使用stdio传输），并初始化一个MCP（管理控制协议/多通道协议，具体含义根据上下文确定） ClientSession，列出资源和工具，阅读 greeting://hello 资源，并调用 add 带有工具的 a=1, b=7。

运行客户端时应看到的（已截断）示例输出：

Using server script at: C:\...\py_mcp\server\calc_server.py
LISTING RESOURCES
Resource:  greeting://{name}
LISTING RESOURCE TEMPLATES
Template: greeting://{name}
LISTING TOOLS
Tool: add
Tool: subtract
Tool: multiply
Tool: divide
READING RESOURCE
Content: Hello, hello!, MIME Type: text/plain
CALL TOOL
1 + 7 = 8    # or similar output depending on how the client prints the tool result

合同（快速）

  • 输入：客户端请求包含资源标识符（字符串模板）或带有类似JSON的参数字典的工具名称。
  • 输出：资源读取返回（内容，MIME类型）；工具调用返回一个结果对象（演示中打印工具结果）。
  • 错误模式：服务器对无效的工具调用返回异常；在（某处）进行除零操作时 divide 回报；返回 inf 在示例服务器实现中。

边缘情况和注意事项

  • 除以零： divide(a, 0) 回报；返回 float('inf') 在服务器实现中——如需异常或自定义错误对象，请相应调整。
  • 确保服务器和客户端使用相同的Python解释器运行，以避免导入/路径不匹配的问题。
  • 如果您的环境阻止了子进程的标准输入/输出连接（这种情况较为少见），请在不同的终端中分别运行服务器和客户端，并调整客户端以通过不同的传输方式连接。

故障排除

  • ModuleNotFoundError: 没有名为 'mcp' 的模块 — 请确保 mcp 已安装或可通过PYTHONPATH访问。
  • 启动Python时遇到权限/路径问题——请使用您想要使用的Python可执行文件的完整路径（或者从所需的虚拟环境提示符中运行）。

下一步

  • 添加一个 requirements.txt 或者，如果该项目需要声明依赖项，则使用pyproject配置。
  • 添加单元测试来验证客户端与服务器之间的交互（使用模拟的stdio传输或捕获I/O的子进程）。
  • 扩展服务器，增加更多工具和资源类型以探索MCP功能。

许可证

未指定许可证。如需明确项目的许可证，请添加LICENSE文件。

相关 MCP