UVG Local MCP Server

Author: Anggelie Velásquez — Student ID 221181 Universidad del Valle de Guatemala — Course CC3067

1. Description

Local MCP (Model Context Protocol) server, implemented from scratch in standard Python 3, without using FastMCP or any official MCP SDK. The server communicates with a client through stdio, using JSON-RPC 2.0 implemented manually.

Related MCP server: mini-mcp-demo

2. Objective

Demonstrate understanding of the MCP server lifecycle (initialize → notifications/initialized → tools/list → tools/call) by building the protocol manually, without relying on libraries that hide that logic.

3. Architecture

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

• server.py: entry point, stdin read loop, and method routing.

• jsonrpc.py: construction of JSON-RPC 2.0 responses/errors and basic validation.

• tools.py: centralized tool registry (metadata + schema + executor function).

4. Protocol used

• Transport: stdio (standard input / standard output).

• Framing: one JSON-RPC 2.0 message per line (JSON Lines / NDJSON). No Content-Length-style framing is used.

• Message format: JSON-RPC 2.0, implemented manually (no JSON-RPC or MCP libraries).

• Reported MCP protocol version: 2024-11-05 (protocolVersion field in the initialize response).

• stdout is reserved exclusively for JSON-RPC responses. All logs are sent to stderr.

5. MCP methods implemented

Any other method returns the JSON-RPC error -32601 Method not found.

6. Available tools

analizar_texto

Input: { "texto": "Hola mundo" } Returns: character count, word count, line count, text in uppercase and lowercase.

calcular_estadisticas

Input: { "numeros": [10, 20, 30, 40] } Returns: count, sum, average, minimum, and maximum. Validates that numeros is a list, not empty, and contains only numeric values.

informacion_sistema

No arguments. Returns: operating system, Python version, platform, and current working directory. Does not expose passwords, tokens, environment variables, or file contents.

7. Requirements

• Python 3.8 or higher.

• No external dependencies required (see requirements.txt).

8. Installation

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

9. How to run the server manually

From PowerShell, the server waits for messages on stdin:

python src/server.py

You can write a JSON line and press Enter, for example:

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

The server will respond with a JSON line on stdout. To exit, press Ctrl+Z and then Enter (end of stdin on Windows).

You can also send the entire example file at once:

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

10. How to test it

Automated tests (unittest)

python -m unittest discover tests -v

Demo client (subprocess)

python examples/test_client.py

This script launches src/server.py as a subprocess and automatically runs the initialize -> initialized -> tools/list -> tools/call cycle for all 3 tools, plus a nonexistent-method case.

11. How to configure it in an MCP client

An example configuration is included in client-config/claude_desktop_config.example.json:

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

Important: replace C:\RUTA\AL\PROYECTO with the actual path where you cloned this repository on your machine.

12. Examples

See examples/requests.jsonl, which contains one JSON-RPC message per line covering initialize, notifications/initialized, tools/list, and tools/call for all three tools, plus error cases.

13. Project structure

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. Error handling

The standard JSON-RPC 2.0 codes are implemented: