MCP Runbook Search Server

Un servidor de Model Context Protocol (MCP) que expone búsqueda semántica sobre un conjunto de runbooks de ingeniería internos como herramientas, de modo que Claude Desktop, un IDE compatible con MCP o un agente personalizado puedan preguntar "¿cómo manejamos una conmutación por error de base de datos?" y obtener el runbook correcto, en lugar de que alguien busque en una wiki.

Visión general

MCP estandariza cómo un cliente LLM descubre y llama a herramientas expuestas por un proceso de servidor separado, a través de stdio o HTTP. Este servidor implementa ese lado del protocolo para un caso de uso concreto y realista: hacer que una base de conocimiento interna (runbooks, postmortems, playbooks) sea consultable por cualquier cliente MCP sin escribir una integración personalizada por cliente.

El servidor expone tres herramientas:

• search_runbooks(query, top_k) — búsqueda semántica sobre el corpus de runbooks, clasificada por similitud de coseno.

• get_runbook(doc_id) — obtiene el texto completo de un runbook por su id.

• list_runbooks() — lista el id y el título de cada runbook indexado.

Características principales

• Protocolo MCP real, no un simulacro — construido sobre el servidor FastMCP del SDK oficial de mcp para Python, y verificado de extremo a extremo con un ClientSession real conectado a través de stdio (ver Ejemplo de ejecución más abajo) — no solo pruebas unitarias de las funciones subyacentes.

• Búsqueda semántica sin dependencias — un embedder de hash convierte cada documento en un vector de tamaño fijo sin necesidad de modelo externo, clave API o llamada de red, por lo que el servidor funciona completamente sin conexión. La similitud de coseno sobre esos vectores clasifica los resultados por significado, no solo por coincidencia de palabras clave.

• Lógica de herramientas desacoplada del transporte — src/tools.py contiene funciones simples sobre un Corpus, probadas unitariamente de forma independiente; src/server.py solo conecta esas funciones con los decoradores de herramientas de MCP. Cambiar stdio por transporte HTTP, o el corpus por un almacén de documentos real, no afecta la lógica de las herramientas.

• Manejo claro de errores — get_runbook con un id desconocido devuelve un payload estructurado {"error": ...} en lugar de lanzar una excepción, de modo que el cliente recibe una respuesta procesable en cualquier caso.

Arquitectura

MCP client (Claude Desktop, IDE, custom agent)
        │  stdio / JSON-RPC
        ▼
 FastMCP server (src/server.py)
        │  registers tools
        ▼
 tools.py  ──▶  Corpus (src/corpus.py)
                  │
                  ▼
          hashing embedder + cosine similarity
                  │
                  ▼
          5 sample engineering runbooks

Stack tecnológico

Estructura del proyecto

.
├── src/
│   ├── corpus.py    # Hashing embedder, Corpus, sample runbook documents
│   ├── tools.py      # Pure tool functions (search / get / list)
│   └── server.py     # FastMCP server wiring tools.py into MCP tool decorators
├── tests/
│   ├── test_corpus.py
│   └── test_tools.py
├── .github/workflows/ci.yml
├── Dockerfile
├── requirements.txt
└── README.md

Primeros pasos

Requisitos previos

• Python 3.10+

Instalación

git clone https://github.com/deekshu05/mcp-document-search-server.git
cd mcp-document-search-server
pip install -r requirements.txt

Ejecutar el servidor

python -m src.server

Esto inicia el servidor en stdio, esperando que un cliente MCP se conecte.

Conexión desde Claude Desktop

Añade esto a tu claude_desktop_config.json:

{
  "mcpServers": {
    "runbook-search": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-document-search-server"
    }
  }
}

Reinicia Claude Desktop, y search_runbooks, get_runbook y list_runbooks se convierten en herramientas que Claude puede llamar directamente en la conversación.

Ejecutar con Docker

docker build -t mcp-runbook-server .
docker run -i mcp-runbook-server

Ejemplo de ejecución

Salida real de un cliente MCP de Python que se conecta a este servidor a través de stdio y llama a sus herramientas — no una transcripción simulada:

Tools exposed: ['search_runbooks', 'get_runbook', 'list_runbooks']

search_runbooks('the primary database node is not responding'):
{
  "doc_id": "rb-001",
  "title": "Database failover procedure",
  "snippet": "Database failover procedure. When the primary Postgres node becomes
  unresponsive, promote the standby replica using the orchestrator's promote
  command, update the connection endpoint in the service config map, and verify",
  "score": 0.439
}
{
  "doc_id": "rb-003",
  "title": "Deploy rollback procedure",
  "snippet": "Deploy rollback procedure. If error rates exceed the alert
  threshold within ten minutes of a deploy, trigger the automated rollback to
  the previous stable image tag, confirm the health checks pass on all
  replicas, and po",
  "score": 0.3208
}

get_runbook('rb-001'):
{
  "doc_id": "rb-001",
  "title": "Database failover procedure",
  "text": "Database failover procedure. When the primary Postgres node becomes
  unresponsive, promote the standby replica using the orchestrator's promote
  command, update the connection endpoint in the service config map, and
  verify replication lag has dropped to zero on the new primary before
  resuming writes. Page the on-call DBA if promotion does not complete within
  five minutes."
}

La consulta nunca menciona 'Postgres' ni 'failover' por nombre — es una descripción simple del síntoma — y la búsqueda aún clasifica el runbook correcto en primer lugar por significado, no por coincidencia de palabras clave, con un segundo resultado real (procedimiento de rollback) que es genuinamente el siguiente runbook más relacionado.

Impacto

Un patrón como este convierte una base de conocimiento interna que antes requería que alguien supiera qué página de wiki buscar en algo que cualquier asistente de IA compatible con MCP puede consultar y citar directamente, reduciendo el tiempo entre "comienza un incidente" y "el runbook correcto está frente al respondedor".

Hoja de ruta

• Reemplazar el embedder de hash por un modelo de embedding real cuando se ejecute contra un corpus más grande

• Transporte HTTP en streaming junto con stdio, para clientes MCP remotos

• Indexación de escritura directa para que se puedan añadir nuevos runbooks sin reiniciar el servidor

• Alcance de autenticación para que diferentes clientes MCP vean diferentes subconjuntos del corpus

Licencia

MIT