Servidor y cliente MCP

PersonalKB: un servidor real del Model Context Protocol (MCP), búsqueda de notas más una consulta del tiempo en vivo, y un cliente/agente que se comunica con él. La capa de protocolo MCP nunca se simula: cada prueba lanza un subproceso de servidor real y realiza JSON-RPC real a través de él, ya sea mediante stdio o mediante HTTP real. Lo único que se falsea sin conexión es la decisión del propio LLM sobre qué herramienta usar; no se necesita ninguna clave de API para ejecutar nada aquí excepto el flag final --real.

Problema: Conectar un modelo a herramientas con un blob JSON hecho a mano funciona hasta que necesitas un segundo cliente, un servidor remoto o las herramientas de otra persona. MCP es el estándar abierto de Anthropic que define cómo un modelo descubre y llama herramientas, lee recursos y usa plantillas de prompt a través de un protocolo de comunicación real. Este proyecto construye un servidor real contra ese protocolo, desde los decoradores hasta un puente de cliente funcional y un bucle de agente.

Habilidades demostradas: construir un servidor MCP (herramientas, recursos, prompts) con FastMCP, tanto los transportes stdio como streamable-HTTP, un puente de cliente que descubre herramientas en vivo a través del protocolo, un enrutador determinista de herramientas sin conexión y un bucle de agente real contra la API de Claude, búsqueda de texto completo en SQLite (FTS5), y pytest contra tráfico de protocolo real (sin simulación).

Stack tecnológico: Python 3.10+, el SDK mcp (FastMCP), SQLite (biblioteca estándar), el SDK de Anthropic para la ruta del agente real, requests para el tiempo en vivo (Open-Meteo), pytest.

Lo que expone

Al ejecutar mcp_kb.server se inicia un servidor MCP, PersonalKB, sobre notas almacenadas en SQLite con búsqueda de texto completo:

• Herramientas: search_notes(query, limit), add_note(title, body, tags), list_tags(), get_weather(city).

• Recursos: note://{note_id} (obtener una nota), notebook://summary (un resumen de todo el cuaderno).

• Prompt: research_prompt(topic), una plantilla de prompt reutilizable.

Related MCP server: MCP Apple Notes

Ejecútalo

python -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python generate_data.py           # seeds data/notes.db with 15 hand-written notes

python -m mcp_kb tools                                  # list tools/resources/prompts
python -m mcp_kb ask "find notes about python"
python -m mcp_kb ask "what's the weather in Paris"
python -m mcp_kb serve                                  # run the server directly (stdio)
python -m mcp_kb serve --http                            # or over streamable-HTTP

pytest -q                          # the full suite, all real protocol traffic, no key needed

ask lanza el servidor real, descubre sus herramientas en vivo a través de MCP y responde a tu pregunta con un enrutador determinista sin conexión por defecto, o con la API real de Claude mediante --real (necesita ANTHROPIC_API_KEY en .env).

Cómo encaja

mcp_kb/
├── db.py         SQLite + FTS5 notes store: search, add, tags
├── weather.py     an offline table, or real keyless Open-Meteo data with --live-weather
├── server.py      the actual MCP server (FastMCP-based): tools, resources, a prompt
├── bridge.py       the MCP client wrapper: discovers tools/resources/prompts live
├── llm.py         the offline deterministic tool-choice router
├── agent.py        the agentic loop: offline router, or a real Claude tool-use loop
└── cli.py           python -m mcp_kb tools|ask|serve
tests/                41 tests, all real protocol traffic (stdio and HTTP), no mocking

La decisión de diseño que importa: server.py es una capa fina alrededor de db.py y weather.py; la única tarea de la capa MCP es traducir entre el protocolo y funciones Python sencillas. Esa división es lo que hace que la lógica subyacente se pueda probar sin sobrecarga de protocolo, mientras que la capa de protocolo en sí misma se ejercita de verdad en cada prueba.

Cómo conectar un cliente MCP real

El mismo servidor también se ejecuta tal cual dentro de la aplicación real de Claude Desktop: apunta su configuración de MCP a python -m mcp_kb serve, y puede buscar en tus notas o consultar el tiempo en un chat normal, llamando a las herramientas exactas definidas en server.py. Consulta hosting/HOSTING_GUIDE.md para los pasos de conexión y para desplegar el transporte HTTP en algún lugar donde un cliente remoto pueda acceder a él.

Lo que aprendí

• MCP separa lo que hace una herramienta de cómo un cliente la encuentra y la llama: el servidor declara herramientas, recursos y prompts una vez, y cualquier cliente compatible (un puente hecho a mano o Claude Desktop) puede descubrirlos y usarlos sin pegamento personalizado.

• Mantener la capa de protocolo fina y llevar la lógica a funciones Python sencillas y comprobables es lo que permitió que la suite de pruebas ejecutara tráfico real de cliente/servidor sin que fuera lenta o frágil.

• stdio y streamable-HTTP son solo dos transportes bajo el mismo protocolo; las herramientas, los recursos y los prompts que expone un servidor no cambian según cómo un cliente acceda a él.