MCP Python Stdio 示例项目

这是一个可分发的 Model Context Protocol (MCP) 服务端示例，采用了 stdio 协议进行通讯。

目录结构

项目采用了标准推荐的 src 布局：

• src/stdio_python_demo/: 源代码目录
• pyproject.toml: 包含打包元数据和 entry points 配置

如何作为用户直接运行

如果你将此项目上传到 GitHub，其他用户无需手动下载代码，可以直接通过 uvx 运行：

# 替换为你的 GitHub 仓库地址
uvx --from git+https://github.com/YOUR_USERNAME/stdio-python-demo.git stdio-python-demo

本地开发与运行

1. 安装环境

uv sync

2. 运行服务端

项目配置了 stdio-python-demo 入口点，可以直接运行：

uv run stdio-python-demo

3. 测试验证

运行模拟客户端脚本：

uv run test_client.py

或者使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv run stdio-python-demo

分发到公共仓库 (PyPI) 的建议

如果你想让用户直接通过 uvx stdio-python-demo 运行：

1. 注册 PyPI 账号。
2. 在项目根目录运行 uv build。
3. 使用 uv publish 将构建好的包发布。

发布后，用户的运行体验将非常顺滑：

uvx stdio-python-demo

{
  "mcpServers": {
    "python-calc": {
      "command": "uvx",
      "args": [
        "stdio-python-demo"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

{
  "mcpServers": {
    "python-calc": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/payegis/mcp/base-demo/stdio-python-demo",
        "run",
        "stdio-python-demo"
      ],
      "env": {
        "GREETING_PREFIX": "你好"
      }
    }
  }
}

环境变量配置示例

本项目演示了两种配置环境变量的方式：

1. 使用 .env 文件（本地开发推荐）

在项目根目录下创建 .env 文件，你可以配置自定义的问候语前缀：

GREETING_PREFIX="你好"

服务端在初始化时会调用 load_dotenv()，你可以通过 say_greeting 工具来验证配置是否生效。

2. 在 Claude Desktop 中直接配置

如果你在 Claude Desktop 中使用此项目，可以在配置文件的 env 字段中注入环境变量：

{
  "mcpServers": {
    "python-calc": {
      "command": "uv",
      "args": [
        "--directory",
        "D:/payegis/mcp/base-demo/stdio-python-demo",
        "run",
        "stdio-python-demo"
      ],
      "env": {
        "GREETING_PREFIX": "尊敬的"
      }
    }
  }
}

3. 可用工具演示

• add_numbers(a, b): 基础数值加法。
• say_greeting(name): 演示从环境变量获取前缀并拼接姓名。

4. 安全建议

• 不要提交 .env：敏感信息（如 API Key）应仅存在于本地 .env 中，本项目已将其加入 .gitignore。
• 配置模板：参考 .env.example 创建你自己的本地配置。