mcp-demo

Un servidor MCP mínimo en Python, construido por fases para que cada commit enseñe un concepto. Estado final: Claude Code puede llamar a modelos locales de Ollama (gemma3:4b / 3:12b) como una herramienta, desviando el trabajo de baja prioridad de la API hacia el servidor doméstico.

¿Qué es MCP, realmente?

Model Context Protocol es un protocolo estandarizado JSON-RPC 2.0 que permite a un cliente LLM (Claude Code, Claude Desktop, Cursor) descubrir e invocar herramientas, obtener recursos y cargar plantillas de prompts desde procesos separados llamados servidores MCP. MCP es al tooling de LLM lo que LSP es al soporte de lenguaje en IDEs: un protocolo, muchas implementaciones interoperables.

Las piezas móviles

    ┌───────────────────┐  stdio / HTTP   ┌──────────────────┐
    │  MCP Client       │ ◄──JSON-RPC──► │  MCP Server      │
    │  (Claude Code)    │                │  (this repo)     │
    └───────────────────┘                └──────────────────┘
            │                                     │
            │ spawns as child                     │ hits
            │ process (stdio)                     │ localhost:11434
            ▼                                     ▼
     your shell env                        Ollama / gemma3

• Cliente — integrado en la aplicación LLM

• Servidor — cualquier proceso que hable MCP

• Transporte — stdio (el cliente inicia el servidor como hijo, canaliza JSON-RPC) o streamable-http (el servidor es un servicio web). Este repositorio utiliza stdio.

Tres primitivas que expone un servidor MCP

Progresión de fases

Cada fase es un commit — git log muestra la evolución.

1. ✅ scaffold — pyproject, README, .gitignore.

2. ✅ servidor hello-world — una herramienta echo + cliente de prueba de humo. Demuestra el ciclo de vida completo: inicio del cliente → handshake → descubrimiento de herramientas → llamada a herramienta.

3. ✅ herramienta ollama_ask — herramienta asíncrona que hace POST a localhost:11434/api/generate y devuelve la respuesta de Gemma.

4. ✅ pulido — añade el parámetro system a ollama_ask y expone un recurso en ollama://models (lista de modelos descargados).

Instalación y ejecución

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# Phase 2+ only: run the server by hand to smoke-test
python -m mcp_demo.server

El servidor lee JSON-RPC desde stdin y escribe en stdout — si lo ejecutas directamente en una terminal, simplemente se quedará esperando entrada. Eso es esperado. El cliente (Claude Code) es quien realmente lo alimenta.

Registro en Claude Code

Añadir a ~/.claude/settings.json:

{
  "mcpServers": {
    "mcp-demo": {
      "command": "/home/booty/mcp-demo/.venv/bin/python",
      "args": ["-m", "mcp_demo.server"]
    }
  }
}

Reinicia Claude Code. Las herramientas aparecerán como mcp__mcp-demo__<tool_name>.

Lecturas adicionales

• Especificación: https://modelcontextprotocol.io/specification

• SDK de Python: https://github.com/modelcontextprotocol/python-sdk

• Inspector (una interfaz de depuración para probar cualquier servidor MCP): npx @modelcontextprotocol/inspector