UVG Local MCP Server

Автор: Anggelie Velásquez — Карне 221181 Университет долины Гватемалы — Курс CC3067

1. Описание

Локальный MCP-сервер (Model Context Protocol), реализованный с нуля на стандартном 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: централизованная регистрация инструментов (метаданные + схема + исполняемая функция).

4. Используемый протокол

• Транспорт: stdio (стандартный ввод / стандартный вывод).

• Форматирование: одно сообщение JSON-RPC 2.0 на строку (JSON Lines / NDJSON). Форматирование типа Content-Length не используется.

• Формат сообщений: JSON-RPC 2.0, реализованный вручную (без библиотек JSON-RPC или MCP).

• Сообщаемая версия протокола MCP: 2024-11-05 (поле protocolVersion в ответе на initialize).

• 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": {}}

Сервер ответит строкой JSON в stdout. Для завершения нажмите Ctrl+Z, затем Enter (конец stdin в Windows).

Также можно отправить весь примерный файл за один раз:

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: