🏛️ ArchMCP: Zentraler Remote-MCP-Server für Microservices

Gib deinem KI-Codierungsassistenten ein organisatorisches Gehirn.
ArchMCP ist ein leichtgewichtiger, Remote-Model-Context-Protocol-Server (MCP), der deine KI-Assistenten (Google Antigravity, Claude Desktop, Cursor, VS Code) in Echtzeit mit deiner gesamten Microservice-Architektur verbindet.

📚 Lies das Schritt-für-Schritt-Benutzerhandbuch & die Setup-Anleitung

📖 Die Geschichte hinter ArchMCP

Das alltägliche Problem

Stell dir vor, du schreibst eine Funktion in order-service mit deinem KI-Codierungsassistenten. Du fragst die KI:

„Implementiere den Checkout und belaste den Kunden."

Sofort stößt die KI an eine Wand:

• Sie hat keine Ahnung, welche Header payment-service für Idempotenz benötigt.

• Sie weiß nicht, welche Datenbankspalten in inventory-service existieren, um Lagerbestand zu reservieren.

• Sie hat keine Ahnung, welche vorgelagerten Dienste brechen, wenn du einen Endpunkt änderst.

Um das heute zu lösen, versuchen Entwickler normalerweise eine von zwei schlechten Optionen:

1. Komplette Repositories in den Prompt kippen: Das verschwendet leicht 100.000+ Tokens pro Frage, kostet viel Geld, macht die KI langsam und verursacht Halluzinationen durch überladene Prompts.

2. 20+ Repos lokal klonen: Jeder Entwickler im Team muss 20 Repos auf seinem Laptop aktuell halten, nur damit seine lokale KI Kontext hat.

Die Lösung: Ein gemeinsames Remote-Gehirn

ArchMCP löst das, indem es als zentralisiertes Architektur-Gehirn mit Sub-Millisekunden-Antwortzeit fungiert.

Statt als privater lokaler Befehl auf einem Laptop zu laufen, läuft ArchMCP als gemeinsamer Remote-Dienst. Jeder Ingenieur in deinem Team verbindet seinen KI-Assistenten mit der ArchMCP-Server-URL und einem Authentifizierungstoken.

Wenn dein KI-Assistent wissen muss:

• „Welcher Dienst übernimmt Rückerstattungen?" $\rightarrow$ Er ruft search_microservices auf.

• „Welche Tabellen gehören zu payment-service?" $\rightarrow$ Er ruft get_database_schema auf.

• „Wenn ich /api/v1/orders ändere, was bricht dann?" $\rightarrow$ Er ruft analyze_blast_radius auf.

┌────────────────────────────────────────────────────────┐
│                   AI Assistant Client                  │
│       (Google Antigravity, Claude Desktop, Cursor)     │
└──────────────────────────┬─────────────────────────────┘
                           │
                           │  HTTP / Server-Sent Events (SSE)
                           │  Authorization: Bearer <token>
                           │
┌──────────────────────────▼────────────────────────────────────────────────────────┐
│                                   ArchMCP Server                                   │
│                                                                                    │
│   ┌─────────────────────┐  ┌─────────────────────┐  ┌──────────────────────────┐   │
│   │      MCP Tools      │  │    MCP Resources    │  │       MCP Prompts        │   │
│   │ • search_services   │  │ • arch/overview     │  │ • cross_service_planner  │   │
│   │ • blast_radius      │  │ • services/catalog  │  │ • incident_triage        │   │
│   │ • sequence_diagram  │  │ • guidelines/docs   │  │ • contract_refactor      │   │
│   │ • get_db_schema     │  │ • service docs      │  │                          │   │
│   └──────────┬──────────┘  └──────────┬──────────┘  └────────────┬─────────────┘   │
│              │                        │                          │                 │
│   ┌──────────▼────────────────────────▼──────────────────────────▼─────────────┐   │
│   │                       Microservice Intelligence Engine                     │   │
│   │ • Transitive Graph Traversal & Blast Radius Analyzer (BFS)                 │   │
│   │ • In-Memory Index & Token Search (< 2ms response time)                     │   │
│   │ • Dynamic OpenAPI / Swagger 3.0 Importer                                   │   │
│   └───────────────────────────────────┬────────────────────────────────────────┘   │
│                                       │                                            │
│   ┌───────────────────────────────────▼────────────────────────────────────────┐   │
│   │              Embedded Web Visualizer & Live Sandbox (/dashboard)           │   │
│   │ • Interactive Service Topology Explorer & Token Economics Calculator       │   │
│   └────────────────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────────────────┘

💡 Wie ich es entworfen habe & warum

Beim Entwurf von ArchMCP war das Ziel, es schnell, sauber und praktisch zu halten, ohne unnötige Komplexität:

1. Warum Remote-HTTP/SSE statt eines lokalen CLI-Prozesses?

Standard-MCP-Server laufen als lokaler stdio-Subprozess. Das funktioniert zwar für Desktop-Skripte einzelner Benutzer, aber ein Unternehmen mit 50 Ingenieuren, die an 30 Microservices arbeiten, braucht eine zentrale Quelle der Wahrheit. Indem ArchMCP über HTTP/SSE gehostet wird, sind Architektur-Updates und neue API-Schemas sofort für alle verfügbar, ohne dass Repos lokal geklont werden müssen.

2. Warum In-Memory-Graph-Indexierung statt einer schweren Vektordatenbank?

Viele KI-Tools springen sofort auf schwere Vektordatenbanken (wie Pinecone oder Milvus). Für strukturierte Architektur-Metadaten (API-Routen, Datenbanktabellen und Dienstabhängigkeiten) sind Graphtraversierung und schnelles lexikalisches Token-Matching:

• Deterministisch: Exakte Übereinstimmungen für Routen wie /api/v1/auth/login oder Tabelle users.

• Null Overhead: Läuft mit ~38 MB RAM und null externen API-Schlüsseln oder GPU-Anforderungen.

• Blitzschnell: Antwortzeit unter 2 ms.

3. Berücksichtigte Kompromisse

📊 Leistungs-Benchmarks & Token-Ökonomie

Wir haben den Unterschied gemessen zwischen dem Analysieren einer Microservice-Aufgabe durch einen KI-Assistenten per Repository-Dump im Prompt und der Abfrage von ArchMCP:

💡 Echtzeit-Verifizierung: Du kannst diese Leistungsmetriken jederzeit live testen und beobachten, indem du die integrierte Interaktive Dashboard-Sandbox verwendest, die bei jeder Anfrage die Abfragelatenz und Token-Ersparnis berechnet.

🔍 Überraschungen & Entdeckungen auf dem Weg

Der Bau eines Remote-MCP-Servers in Python offenbarte einige faszinierende technische Details:

1. Typ-Hinweise werden zu KI-Schemas: Das offizielle Python-MCP-SDK liest automatisch Python-Typannotationen und Docstrings, um JSON-Schema-Definitionen zu generieren, die das LLM zur Auswahl von Tools verwendet. Gute Docstrings machen die KI buchstäblich schlauer.

2. DNS-Rebinding-Schutz: Das MCP-2.0-Protokoll validiert automatisch eingehende Host-Header, um interne Entwicklernetzwerke vor browserbasierten DNS-Angriffen zu schützen.

3. Der 2-Phasen-SSE-Handshake: Wenn ein KI-Client eine Verbindung zu GET /sse herstellt, öffnet der Server den Event-Stream und gibt eine eindeutige Session-Postback-URL zurück (/messages/?session_id=...). Alle nachfolgenden JSON-RPC-Tool-Aufrufe werden an diese Session gesendet.

🖥️ Live-Browser-Visualizer & Sandbox

ArchMCP enthält ein eingebettetes, responsives Web-Dashboard unter http://localhost:8000/dashboard (oder /):

• Interaktive Topologie: Klicke auf eine beliebige Dienstkarte (auth-service, order-service, payment-service), um deren APIs, zugehörige Datenbanktabellen und Abhängigkeitszuordnung zu inspizieren.

• Live-Tool-Sandbox: Teste jedes MCP-Tool in Echtzeit und sieh dir die JSON-RPC-Anfrage/-Antwort mit Live-Token-Ersparnis und Latenzmetriken an.

⌨️ Entwickler-CLI

ArchMCP wird mit einem praktischen Befehlszeilentool geliefert:

# 1. Start the Remote Server
archmcp run

# 2. Explore the Catalog in your Terminal
archmcp explore

# 3. Calculate Change Blast Radius
archmcp blast-radius auth-service

# 4. Import a live OpenAPI / Swagger Specification
archmcp import-openapi https://petstore.swagger.io/v2/swagger.json --owner "Commerce Team"

🔌 Verbinden deines KI-Assistenten

Sobald ArchMCP läuft (z. B. unter http://127.0.0.1:8000/sse), konfiguriere dein KI-Tool in Sekunden:

Google Antigravity IDE

Füge zu .agents/mcp_config.json hinzu:

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer dev-token-secret-123"
      }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "archmcp": {
      "url": "http://127.0.0.1:8000/sse?token=dev-token-secret-123"
    }
  }
}

🚀 3-Schritte-Schnellstart

# 1. Clone & Install
git clone https://github.com/ShubhamScript/archmcp.git
cd archmcp
pip install -e .[dev]

# 2. Run Tests
pytest -v

# 3. Start Server
archmcp run

Öffne http://localhost:8000/dashboard in deinem Browser, um deine Architektur interaktiv zu erkunden.

🔮 Was als Nächstes auf der Roadmap steht

Wenn ArchMCP für 500+ Microservices in einem großen Unternehmen erweitert wird:

1. Semantische Konzeptsuche: Hinzufügen von pgvector oder sqlite-vec mit lokalen Embeddings, damit Entwickler konzeptionelle Fragen stellen können („Wo lebt die wiederkehrende Abrechnung?").

2. Backstage-Integration: Automatische Synchronisierung von Spotifys Backstage catalog-info.yaml.

3. Redis-Event-Bus: Synchronisierung aktiver SSE-Sessions über horizontal skalierte Container-Replikate.

4. Git-Webhooks: Automatische Aktualisierung von Schemas, wenn ein PR gemerged wird.

📂 Projektstruktur

archmcp/
├── README.md                      # Project guide & architecture story
├── pyproject.toml                 # Dependencies, CLI scripts, and build config
├── Dockerfile                     # Container build instructions
├── docker-compose.yml             # Container orchestration
├── data/
│   └── repositories.yaml          # Sample microservices catalog
├── src/
│   └── archmcp/
│       ├── main.py                # Server bootstrap
│       ├── cli.py                 # Developer CLI (run, explore, blast-radius, import-openapi)
│       ├── config/settings.py     # Environment settings
│       ├── auth/                  # Bearer token verification & ASGI middleware
│       ├── mcp/                   # Tools, Resources, Prompts, and SSE route handlers
│       ├── services/              # Blast radius, graph traversal, and search logic
│       ├── ingestion/             # OpenAPI importer, markdown parser, dependency scanner
│       ├── storage/               # In-memory database & token search index
│       ├── web/                   # Embedded visualizer and live testing playground
│       └── models/                # Pydantic schemas (Architecture, BlastRadius, Services)
└── tests/                         # 18 unit & integration tests

📄 Lizenz

MIT-Lizenz. Kostenlos für Open-Source- und kommerzielle Nutzung.