UVG Local MCP Server

Autor: Anggelie Velásquez — Matrikelnummer 221181 Universidad del Valle de Guatemala — Kurs CC3067

1. Beschreibung

Lokaler MCP-Server (Model Context Protocol), von Grund auf in Standard-Python 3 implementiert, ohne FastMCP oder ein offizielles MCP-SDK. Der Server kommuniziert über stdio mit einem Client und verwendet manuell implementiertes JSON-RPC 2.0.

Related MCP server: @belal-elsabbagh-apex/copilot-mcp

2. Ziel

Die Kenntnis des Lebenszyklus eines MCP-Servers (initialize → notifications/initialized → tools/list → tools/call) demonstrieren, indem das Protokoll manuell aufgebaut wird, ohne auf Bibliotheken zurückzugreifen, die diese Logik verbergen.

3. Architektur

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

• server.py: Einstiegspunkt, Leseschleife für stdin und Methodenrouting.

• jsonrpc.py: Erstellung von JSON-RPC-2.0-Antworten/-Fehlern und grundlegende Validierung.

• tools.py: zentrale Registrierung von Werkzeugen (Metadaten + Schema + Ausführungsfunktion).

4. Verwendetes Protokoll

• Transport: stdio (Standard-Eingabe / Standard-Ausgabe).

• Framing: eine JSON-RPC-2.0-Nachricht pro Zeile (JSON Lines / NDJSON). Es wird kein Content-Length-Framing verwendet.

• Nachrichtenformat: JSON-RPC 2.0, manuell implementiert (ohne JSON-RPC- oder MCP-Bibliotheken).

• Gemeldete MCP-Protokollversion: 2024-11-05 (Feld protocolVersion in der Antwort auf initialize).

• stdout ist ausschließlich für JSON-RPC-Antworten reserviert. Alle Logs werden an stderr gesendet.

5. Implementierte MCP-Methoden

Jede andere Methode gibt den JSON-RPC-Fehler -32601 Method not found zurück.

6. Verfügbare Werkzeuge

analizar_texto

Eingabe: { "texto": "Hola mundo" } Gibt zurück: Anzahl der Zeichen, Anzahl der Wörter, Anzahl der Zeilen, Text in Groß- und Kleinschreibung.

calcular_estadisticas

Eingabe: { "numeros": [10, 20, 30, 40] } Gibt zurück: Anzahl, Summe, Durchschnitt, Minimum und Maximum. Validiert, dass numeros eine nicht leere Liste mit ausschließlich numerischen Werten ist.

informacion_sistema

Ohne Argumente. Gibt zurück: Betriebssystem, Python-Version, Plattform und aktuelles Arbeitsverzeichnis. Gibt keine Passwörter, Tokens, Umgebungsvariablen oder Dateiinhalte preis.

7. Anforderungen

• Python 3.8 oder höher.

• Es sind keine externen Abhängigkeiten erforderlich (siehe requirements.txt).

8. Installation

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

9. So führen Sie den Server manuell aus

In PowerShell wartet der Server auf Nachrichten über stdin:

python src/server.py

Sie können eine JSON-Zeile schreiben und die Eingabetaste drücken, zum Beispiel:

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

Der Server antwortet mit einer JSON-Zeile auf stdout. Zum Beenden drücken Sie Ctrl+Z und dann Enter (Ende von stdin unter Windows).

Sie können auch die gesamte Beispieldatei auf einmal senden:

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

10. So testen Sie es

Automatische Tests (unittest)

python -m unittest discover tests -v

Demo-Client (Unterprozess)

python examples/test_client.py

Dieses Skript startet src/server.py als Unterprozess und führt automatisch den Zyklus initialize -> initialized -> tools/list -> tools/call für die 3 Werkzeuge aus, zusätzlich zu einem Fall einer nicht existierenden Methode.

11. So konfigurieren Sie es in einem MCP-Client

Eine Beispielkonfiguration ist in client-config/claude_desktop_config.example.json enthalten:

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

Wichtig: Ersetzen Sie C:\RUTA\AL\PROYECTO durch den tatsächlichen Pfad, in dem Sie dieses Repository auf Ihrem Rechner geklont haben.

12. Beispiele

Siehe examples/requests.jsonl, das eine JSON-RPC-Nachricht pro Zeile enthält und initialize, notifications/initialized, tools/list und tools/call für die drei Werkzeuge sowie Fehlerfälle abdeckt.

13. Projektstruktur

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. Fehlerbehandlung

Die Standard-JSON-RPC-2.0-Codes werden implementiert: