MCP Runbook Search Server

Ein Model Context Protocol (MCP)-Server, der semantische Suche über eine Reihe interner Engineering-Runbooks als Tools bereitstellt – sodass Claude Desktop, eine MCP-kompatible IDE oder ein benutzerdefinierter Agent fragen kann: „Wie gehen wir mit einem Datenbank-Failover um?“ und das richtige Runbook zurückbekommt, anstatt dass jemand ein Wiki durchsucht.

Überblick

MCP standardisiert, wie ein LLM-Client Tools entdeckt und aufruft, die von einem separaten Serverprozess über stdio oder HTTP bereitgestellt werden. Dieser Server implementiert diese Seite des Protokolls für einen konkreten, realistischen Anwendungsfall: eine interne Wissensbasis (Runbooks, Postmortems, Playbooks) für jeden MCP-Client abfragbar zu machen, ohne eine kundenspezifische Integration pro Client zu schreiben.

Der Server stellt drei Tools bereit:

• search_runbooks(query, top_k) – semantische Suche über das Runbook-Korpus, sortiert nach Kosinus-Ähnlichkeit.

• get_runbook(doc_id) – holt den vollständigen Text eines Runbooks anhand der ID.

• list_runbooks() – listet ID und Titel jedes indizierten Runbooks auf.

Kernfunktionen

• Echtes MCP-Protokoll, kein Mock – basierend auf dem offiziellen mcp-Python-SDK-Server FastMCP und Ende-zu-Ende mit einer echten ClientSession über stdio verifiziert (siehe Beispiel unten) – nicht nur Unit-Tests der zugrunde liegenden Funktionen.

• Semantische Suche ohne Abhängigkeiten – ein Hashing-Embedder wandelt jedes Dokument in einen Vektor fester Größe um, ohne externes Modell, API-Schlüssel oder Netzwerkaufruf, sodass der Server vollständig offline läuft. Die Kosinus-Ähnlichkeit über diese Vektoren ordnet Ergebnisse nach Bedeutung, nicht nur nach Schlüsselwortüberschneidung.

• Tool-Logik vom Transport entkoppelt – src/tools.py enthält einfache Funktionen über ein Corpus, unabhängig unit-getestet; src/server.py verbindet diese Funktionen nur mit MCP-Tool-Dekoratoren. Der Austausch von stdio gegen HTTP-Transport oder des Corpus gegen einen echten Dokumentenspeicher berührt die Tool-Logik nicht.

• Klare Fehlerbehandlung – get_runbook gibt bei unbekannter ID eine strukturierte {"error": ...}-Antwort zurück, anstatt eine Ausnahme auszulösen, sodass ein Client in jedem Fall eine verwertbare Antwort erhält.

Architektur

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

Tech-Stack

Projektstruktur

.
├── 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

Erste Schritte

Voraussetzungen

• Python 3.10+

Installation

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

Server ausführen

python -m src.server

Dies startet den Server auf stdio und wartet auf einen MCP-Client, der sich verbindet.

Verbinden von Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

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

Starten Sie Claude Desktop neu, und search_runbooks, get_runbook und list_runbooks werden zu Tools, die Claude direkt im Gespräch aufrufen kann.

Ausführen mit Docker

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

Beispielausführung

Echte Ausgabe eines Python-MCP-Clients, der sich über stdio mit diesem Server verbindet und seine Tools aufruft – kein simuliertes Transkript:

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."
}

Die Abfrage erwähnt „Postgres“ oder „Failover“ nicht namentlich – sie ist eine einfache Beschreibung des Symptoms – und die Suche ordnet dennoch das richtige Runbook zuerst nach Bedeutung ein, nicht nach Schlüsselwortübereinstimmung, mit einem echten zweitplatzierten Ergebnis (Rollback-Verfahren), das tatsächlich das nächstverwandte Runbook ist.

Auswirkungen

Ein solches Muster verwandelt eine interne Wissensbasis, die früher jemanden erforderte, der wusste, welche Wiki-Seite zu durchsuchen ist, in etwas, das jeder MCP-kompatible KI-Assistent direkt abfragen und zitieren kann, und verkürzt die Zeit zwischen „ein Vorfall beginnt“ und „das richtige Runbook liegt dem Responder vor“.

Roadmap

• Hashing-Embedder gegen ein echtes Embedding-Modell austauschen, wenn gegen ein größeres Korpus gearbeitet wird

• Streamable HTTP-Transport neben stdio für entfernte MCP-Clients

• Write-through-Indizierung, sodass neue Runbooks hinzugefügt werden können, ohne den Server neu zu starten

• Auth-Scoping, sodass verschiedene MCP-Clients unterschiedliche Teilmengen des Korpus sehen

Lizenz

MIT