UVG 本地 MCP 服务器

作者： Anggelie Velásquez — 学号 221181 危地马拉山谷大学 — 课程 CC3067

1. 描述

一个本地 MCP（模型上下文协议）服务器，使用标准 Python 3 从零实现，不使用 FastMCP 或任何官方 MCP SDK。服务器通过 stdio 与客户端通信，使用手动实现的 JSON-RPC 2.0。

Related MCP server: My Tools MCP Server

2. 目标

通过手动构建协议，不依赖隐藏该逻辑的库，来展示对 MCP 服务器生命周期（initialize → notifications/initialized → tools/list → tools/call）的理解。

3. 架构

Cliente MCP  <-- stdio (stdin/stdout) -->  server.py
                                              │
                                    ┌─────────┴─────────┐
                                    │                    │
                                jsonrpc.py           tools.py
                          (formato JSON-RPC 2.0)  (herramientas)

• server.py：入口点，stdin 读取循环和方法路由。

• jsonrpc.py：构建 JSON-RPC 2.0 响应/错误并进行基本验证。

• tools.py：工具的集中注册（元数据 + schema + 执行函数）。

4. 使用的协议

• 传输： stdio（标准输入 / 标准输出）。

• 帧格式： 每行一个 JSON-RPC 2.0 消息（JSON Lines / NDJSON）。不使用 Content-Length 类型的帧格式。

• 消息格式： JSON-RPC 2.0，手动实现（不使用 JSON-RPC 或 MCP 库）。

• 报告的 MCP 协议版本： 2024-11-05（initialize 响应中的 protocolVersion 字段）。

• stdout 仅保留用于 JSON-RPC 响应。所有日志发送到 stderr。

5. 已实现的 MCP 方法

任何其他方法返回 JSON-RPC 错误 -32601 Method not found。

6. 可用工具

analizar_texto

输入：{ "texto": "Hola mundo" } 返回：字符数、单词数、行数、大写文本和小写文本。

calcular_estadisticas

输入：{ "numeros": [10, 20, 30, 40] } 返回：数量、总和、平均值、最小值和最大值。 验证 numeros 是一个列表，非空，且仅包含数值。

informacion_sistema

无参数。返回：操作系统、Python 版本、平台和当前工作目录。 不暴露密码、令牌、环境变量或文件内容。

7. 要求

• Python 3.8 或更高版本。

• 不需要外部依赖（参见 requirements.txt）。

8. 安装

git clone https://github.com/Anggelie/mcp-local-server-uvg.git
cd mcp-local-server-uvg

9. 如何手动运行服务器

在 PowerShell 中，服务器将等待 stdin 消息：

python src/server.py

你可以写一行 JSON 并按 Enter，例如：

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}

服务器将在 stdout 上以一行 JSON 响应。要结束，按 Ctrl+Z 然后按 Enter（Windows 上 stdin 结束）。

你也可以一次性发送整个示例文件：

Get-Content examples/requests.jsonl | python src/server.py

10. 如何测试

自动测试（unittest）

python -m unittest discover tests -v

演示客户端（子进程）

python examples/test_client.py

此脚本将 src/server.py 作为子进程启动，并自动执行 initialize -> initialized -> tools/list -> tools/call 循环，覆盖 3 个工具，以及一个不存在方法的用例。

11. 如何在 MCP 客户端中配置

在 client-config/claude_desktop_config.example.json 中包含了一个示例配置：

{
  "mcpServers": {
    "uvg-local-server": {
      "command": "python",
      "args": [
        "C:\\RUTA\\AL\\PROYECTO\\src\\server.py"
      ]
    }
  }
}

重要： 将 C:\RUTA\AL\PROYECTO 替换为你机器上克隆此仓库的实际路径。

12. 示例

参见 examples/requests.jsonl，其中每行包含一个 JSON-RPC 消息，涵盖 initialize、notifications/initialized、tools/list 和三个工具的 tools/call，以及错误用例。

13. 项目结构

mcp-local-server-uvg/
│
├── src/
│   ├── server.py      # Punto de entrada del servidor
│   ├── jsonrpc.py      # Utilidades JSON-RPC 2.0
│   └── tools.py        # Registro de herramientas
│
├── tests/
│   ├── test_jsonrpc.py
│   └── test_tools.py
│
├── examples/
│   ├── requests.jsonl
│   └── test_client.py
│
├── client-config/
│   └── claude_desktop_config.example.json
│
├── .gitignore
├── requirements.txt
├── README.md
└── README_ES.md

14. 错误处理

实现了 JSON-RPC 2.0 标准错误码：