HCM-LLM MCP Server

Ein auf FastAPI basierender Model Context Protocol (MCP)-Server für Highway Capacity Manual (HCM)-Analysen und verkehrstechnische Berechnungen. Bisher bietet dieser Server eine umfassende Analyse zweistreifiger Landstraßen gemäß der Methodik von HCM Kapitel 15.

Features

• Semantische Suche in der HCM-Dokumentation

• Vollständige Analyse nach HCM Kapitel 15 (zweistreifige Landstraße) und Kapitel 12 (einfache Autobahnabschnitte)

• Vollständige Abdeckung der HCM-Kapitel 10 bis 28 hinter drei Fähigkeits-Tools (hcm_analyze, hcm_describe, hcm_validate) mit über 33 Methoden, die jeweils das eigene Beispiel-JSON der Bibliothek verwenden und jeweils anhand des veröffentlichten Beispielproblems validiert werden

• Eingabevalidierungs-Gateway gegen HCM/AASHTO-Beschränkungen (über transportations-validator)

• Validierung des gesamten Korpus (300+ Regeln aus HCM/AASHTO/MUTCD/HSM/ADA/...) mit Quellenangaben, gelände-/kontextabhängigen Regeln und Rückfragen zur Klärung – läuft prozessintern, ohne Datenbank

• Wissensgraph-basiertes Schließen: abduktive Designreparatur (Two-Lane & Basic Freeway), widerlegbare Code-Abstimmung, inverses Design und Vorwärts-/Rückwärtsverkettung – jeder Reparaturkandidat wird erneut durch die verifizierte Bibliothek ausgeführt

• YAML-basierte Funktionsregistrierung für einfache Erweiterbarkeit

• Funktionsaufruf-Schnittstelle mit über 15 Verkehrsanalysefunktionen

• MCP-Server-Kompatibilität für die Integration mit KI-Assistenten (unterstützt Claude)

• RESTful-API-Endpunkte für den direkten Zugriff

• Dynamische Endpunktgenerierung auf Basis der Registrierung

• Umfassende Testsuite und Validierungswerkzeuge

Related MCP server: MCP WebAnalyzer

Verbindung zum Remote-MCP-Server herstellen

Dieser Server kann als Backend für KI-Code-Agenten wie Claude Desktop verwendet werden, sodass diese komplexe Verkehrsanalysen durchführen und dynamisch auf die HCM-Dokumentation zugreifen können.

Um diese Funktionalität zu aktivieren, fügen Sie den Server als MCP-Server zur Konfiguration Ihres KI-Assistenten hinzu.

Für Claude-Desktop-Benutzer

Unter den Benutzereinstellungen finden Sie den Tab Connectors und klicken auf Add custom connector.

Fügen Sie dann https://api.hcm-calculator.com/mcp zu Ihrer Claude-Konfiguration hinzu.

Für GitHub-Copilot-Benutzer in VSCode

Sie können diesen Server auch mit GitHub Copilot verwenden, indem Sie ihn als benutzerdefinierten MCP-Server konfigurieren.

Drücken Sie dazu Ctrl+p und wählen Sie MCP: Open User Configuration und passen Sie Folgendes in Ihrer mcp.json an:

{
	"servers": {
		"hcm-mcp": {
			"url": "https://api.hcm-calculator.com/mcp"
		}
	}
}

Verbindung zum lokalen MCP-Server herstellen

Sie können diesen Server auch lokal zu Entwicklungs- oder Testzwecken ausführen.

uv venv

# Windows
.venv\Scripts\activate
# Linux
source .venv/bin/activate

uv pip install .

Starten Sie dann den Server.

# Setup the database.
python hcm_mcp_server/scripts/import_hcm_docs.py

# Start the server.
python mcp_server_fastapi.py

Für Claude-Desktop-Benutzer

Öffnen Sie Claude Desktop und fügen Sie den Server als benutzerdefinierten MCP-Server mit der URL http://localhost:8000/mcp hinzu.

Fügen Sie Folgendes zu Ihrer Claude-Desktop-Konfiguration (claude_desktop_config.json) hinzu:

Hinweis: Diese JSON-Einstellungen scheinen derzeit nicht zu funktionieren (https://github.com/anthropics/claude-code/issues/4188), und in meiner Desktop-Umgebung haben sie ebenfalls nicht funktioniert.

{
  "mcpServers": {
    "hcm-mcp-local": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Für GitHub-Copilot-Benutzer in VSCode

Wie oben können Sie diesen Server mit GitHub Copilot verwenden, indem Sie ihn als benutzerdefinierten MCP-Server konfigurieren.

Drücken Sie dazu Ctrl+p und wählen Sie MCP: Open User Configuration und passen Sie Folgendes in Ihrer mcp.json an:

{
	"servers": {
		"hcm-mcp-local": {
			"url": "http://127.0.0.1:8000/mcp"
		}
	}
}

Anschließend können Sie die Funktionsaufruf-Schnittstelle direkt in Ihrem Code-Editor verwenden.

Projektstruktur

hcm-mcp-server/
├── mcp_server_fastapi.py        # Main FastAPI application
├── functions_registry.yaml      # Function registry configuration
├── hcm_mcp_server/
│   ├── example_prompts/                  
│   │   ├── *.txt                # Example prompts for function calling
│   │   └── *.json               # Example json files for web validation
│   ├── core/                    # Core application modules
│   │   ├── dependencies.py      # Dependency injection and utilities
│   │   ├── registry.py          # Function registry implementation
│   │   ├── models.py            # Pydantic data models
│   │   └── endpoints.py         # Dynamic endpoint creation
│   ├── functions/                  
│   │   ├── chapter15.py         # Chapter 15: Two-Lane Highways
│   │   └── research.py          # Research and documentation
│   └── scripts/                    
│       ├── import_hcm_docs.py   # Import HCM documentation and setup ChromaDB
│       └── validate_registry.py # Registry validation
├── data/                           
│   └──  hcm_files/               # HCM documentation files
└── chroma_db/                    # ChromaDB storage

Konfiguration

Umgebungsvariablen

Erstellen Sie eine .env-Datei auf Basis von .env.example. Kopieren Sie den folgenden Inhalt und fügen Sie ihn ein, oder führen Sie cp .env.example .env aus:

CHROMA_DB_PATH=./chroma_db
HOST=127.0.0.1
PORT=8000
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
LOG_LEVEL=INFO
DB_MODE=local
PUBLIC_SUPABASE_URL=https://
PUBLIC_SUPABASE_API=your-anon-key / service-role-key

Funktionsregistrierung

Funktionen sind in functions_registry.yaml definiert:

functions:
  chapter15:
    identify_vertical_class:
      module: "functions.chapter15"
      function: "identify_vertical_class_function"
      description: "Identify vertical alignment class range"
      category: "transportation"
      chapter: 15
      step: 1
      parameters:
        type: "object"
        properties:
          segment_index:
            type: "integer"
          highway_data:
            type: "object"
        required: ["segment_index", "highway_data"]

Ablationsarme (eingeschränkte MCP-Oberflächen)

Für die 2x2-Ablation aus Tabelle 5 / Abbildung 7 kann dieselbe App so gestartet werden, dass nur eine Teilmenge der Tools verfügbar ist, sodass ein Modell unter jeder Bedingung isoliert evaluiert werden kann:

python mcp_server_fastapi.py     # ct  : full system (all tools), port 8000
python mcp_server_kg_only.py     # kg  : 7 reasoning/validation tools only, port 8001 (no Chroma needed)
python mcp_server_rag_only.py    # rag : query_hcm only, port 8002

Beide Launcher sind schlanke Wrapper, die vor dem Import der App zwei Umgebungsvariablen setzen:

• HCM_MCP_INCLUDE_OPS — durch Kommas getrennte Operations-IDs, die die MCP-Oberfläche bereitstellt (nicht gesetzt = alle). Die Filterung verwendet FastApiMCP(include_operations=...).

• HCM_ENABLE_RAG — auf false setzen, um das Laden des Embedding-Modells und des Vektor-Speichers zu überspringen (der Nur-KG-Arm benötigt keines von beiden).

Richten Sie jeden VS-Code-/Claude-Desktop-MCP-Client auf den Port des zu testenden Arms aus (z. B. http://localhost:8001 für Nur-KG), damit das Modell nur die Tools dieses Arms sieht. Der base-Arm ist einfach ohne angeschlossenen MCP-Server.

API-Nutzung

Vollständige Straßenanalyse

curl -X POST "http://localhost:8000/analysis/chapter15/complete" \
  -H "Content-Type: application/json" \
  -d '{
    "segments": [{
      "passing_type": 0,
      "length": 2.0,
      "grade": 2.0,
      "spl": 50.0,
      "volume": 760.0,
      "volume_op": 1500.0,
      "phf": 0.95,
      "phv": 5.0
    }],
    "lane_width": 12.0,
    "shoulder_width": 6.0,
    "apd": 5.0
  }'

Funktionsaufruf-Schnittstelle

curl -X POST "http://localhost:8000/tools/call" \
  -H "Content-Type: application/json" \
  -d '{
    "function": {
      "name": "chapter15_determine_free_flow_speed",
      "arguments": {
        "segment_index": 0,
        "highway_data": {
          "segments": [{"passing_type": 0, "length": 2.0, "grade": 2.0, "spl": 50.0}],
          "lane_width": 12.0,
          "shoulder_width": 6.0
        }
      }
    }
  }'

Verfügbare Funktionen auflisten

# List all functions
curl -X POST "http://localhost:8000/tools/list"

# Filter by category
curl -X POST "http://localhost:8000/tools/list" \
  -H "Content-Type: application/json" \
  -d '{"category": "transportation"}'

# Filter by chapter
curl -X POST "http://localhost:8000/tools/list" \
  -H "Content-Type: application/json" \
  -d '{"chapter": 15}'

HCM-Dokumentation abfragen

curl -X POST "http://localhost:8000/tools/query-hcm" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What factors affect free flow speed in two-lane highways?",
    "top_k": 5
  }'

Verfügbare Funktionen

Funktionen zu Kapitel 15

• chapter15_identify_vertical_class - Schritt 1: Klassenbereich der vertikalen Linienführung bestimmen

• chapter15_determine_demand_flow - Schritt 2: Nachfrageflussraten und Kapazität berechnen

• chapter15_determine_vertical_alignment - Schritt 3: Klassifizierung der vertikalen Linienführung bestimmen

• chapter15_determine_free_flow_speed - Schritt 4: Freie Fließgeschwindigkeit berechnen

• chapter15_estimate_average_speed - Schritt 5: Mittlere Reisegeschwindigkeit schätzen

• chapter15_estimate_percent_followers - Schritt 6: Prozentsatz der Kolonnenfahrer schätzen

• chapter15_determine_follower_density_pl - Schritt 8a: Kolonnendichte für Überholfahrstreifen

• chapter15_determine_follower_density_pc_pz - Schritt 8b: Kolonnendichte für PC/PZ-Abschnitte

• chapter15_determine_segment_los - Schritt 9: Servicegrad des Abschnitts berechnen

• chapter15_determine_facility_los - Schritt 10: Servicegrad der Anlage berechnen

• chapter15_complete_analysis - Vollständige HCM-Kapitel-15-Prozedur

Funktionen zu Kapitel 12 (einfache Autobahnabschnitte)

Eine andere Gleichungsfamilie als Kapitel 15 – die Kette Fahrstreifenbreite -> FFS -> Kapazität/Geschwindigkeit -> Dichte -> LOS. Erfordert transportations-library>=0.1.12.

• chapter12_determine_free_flow_speed - Schritt 2: Freie Fließgeschwindigkeit schätzen und anpassen

• chapter12_estimate_capacity - Schritt 3: Basis- und angepasste Kapazität (Pkw-E/h/FS)

• chapter12_estimate_demand_volume - Schritt 4: Verkehrsstärke je Fahrstreifen v_p

• chapter12_calculate_speed - Schritt 5a: Mittlere Fahrgeschwindigkeit über die Geschwindigkeits-Fluss-Kurve

• chapter12_estimate_density - Schritt 5b: Dichte D = v_p / S

• chapter12_determine_segment_los - Schritt 6: Servicegrad des Abschnitts

• chapter12_complete_analysis - Vollständige HCM-Kapitel-12-Prozedur für einfache Autobahnabschnitte

HCM-Analysefähigkeiten (vollständige Kapitelabdeckung)

Jede HCM-Methode, die die Rechenbibliothek implementiert, Kapitel 10 bis 28, hinter drei Fähigkeits-Tools. Die Methode ist ein Argument, kein Tool: dreiunddreißig nahezu identische Schemata würden jedem Aufrufer Kontext kosten und die Tool-Auswahl abstumpfen, und die zehn oben veröffentlichten Tools sind bereits als Fähigkeiten konzipiert.

• hcm_analyze — {method, config}. Führt eine Methode aus. Die Tool-Beschreibung enthält den Methodenkatalog, jeweils eine kompakte Zeile, und method ist ein Enum der dreiunddreißig IDs.

• hcm_describe — {method?}. Mit einer Methode: eine Skizze ihres Eingabeschemas, die Bedeutung ihrer Ergebnisfelder und die Beispielproblem-Fixture, die sie validiert. Ohne eine: den Katalog, jede Methoden-ID mit ihrem Kapitel und einer einzeiligen Zusammenfassung. Rufen Sie dies zuerst auf; so erfährt ein Aufrufer die Form einer Methode, ohne die Rust-Bindungen lesen zu müssen.

• hcm_validate — {method, config}. Parst und prüft eine Konfiguration ohne die Analyse auszuführen und gibt die eigenen Validierungsfehler der Bibliothek oder ok zurück. Die Iteration über eine Konfiguration kostet einen Parsevorgang statt einer vollständigen Analyse. Vierundzwanzig der dreiunddreißig Methoden haben einen echten Validierungsschritt hinter dem Konstruktor (serde-Deserialisierung, Konstruktor-Bereichsprüfungen und für Kapitel 15 die Parameterbereiche aus Exhibit 15-8 über tl.validate_input); die anderen neun sind einzelne JSON-Einstiegspunkte in der Bibliothek, bei denen Parsen und Berechnung ein einziger Aufruf sind, und diese geben dies in der Antwort an, anstatt die Analyse auszuführen und sie als Validierung zu bezeichnen.

Die Eingabe ist immer das eigene Beispiel-Fall-JSON (Fixture) der Rechenbibliothek, das als config übergeben wird – nicht ein zweites, abgeflachtes Schema, das für die MCP-Ebene erfunden wurde. Ein Beispiel aus transportations-library/tests/ExampleCases/hcm/ kann unverändert übergeben werden. Erfordert transportations-library>=0.3.7.

Jede Methode liefert ihr durchgerechnetes Beispiel unter hcm_mcp_server/data/examples/<method>.json mit, und tests/test_methods.py lässt jede einzelne davon durch hcm_analyze laufen, gegen die veröffentlichten Werte des jeweiligen Beispielproblems, mit den Toleranzen, die die eigene Testsuite der Berechnungsbibliothek ansetzt.

Jede Methode hält außerdem eine methodenförmige REST-Route unter /analysis/hcm/<method-with-hyphens> für direkte API-Aufrufer bereit. Routen sind keine MCP-Tools, kosten also keinen Kontext des Aufrufers.

Domänenverweigerungen verwenden die eigene Meldung der Bibliothek. Eine nicht digitalisierte Mischverkehrs-Steigung, ein domänenfremder PCE für eine spezifische Steigungsstrecke und eine fehlerhaft formatierte Konfiguration werden alle als {"success": false, "error": "..."} in den Worten der Bibliothek zurückgegeben, weil diese Meldungen angeben, was die veröffentlichten HCM-Daten abdecken.

Diese Tools sind nicht Teil der Standard-MCP-Oberfläche. mcp_server_fastapi.py ist der ct-Ablationsarm, und die zehn Tools, die es standardmäßig anbietet, sind die Oberfläche, gegen die das veröffentlichte Experiment lief (siehe tests/test_frozen_surface.py). Setzen Sie HCM_MCP_FULL_COVERAGE=true, um die drei Fähigkeits-Tools an den MCP-Mount anzuhängen. Ohne diese sind sie weiterhin über REST und über /tools/call erreichbar.

Validierungsfunktionen

• validation_validate_design_full – Validiert ein Design gegen den vollständigen Regelkorpus (300+ Regeln: HCM, AASHTO, MUTCD, HSM, ADA, OpenDRIVE, ...) mit Zitaten, gelände-/zuständigkeitsabhängigen Regeln und Klarstellungsanfragen, wenn eine Eingabe fehlt oder ihr Kontext mehrdeutig ist. Läuft prozessintern über den gebündelten Seed-Korpus — keine Datenbank. (Die Kapitel-15/12-Tools verwenden ein leichteres Semantic-Firewall-Gateway; dies ist die vollständige Engine.) Erfordert transportations-validator>=0.2.0 + sqlalchemy.

Forschungsfunktionen

• query_hcm – HCM-Dokumentationsdatenbank abfragen

Reasoning-Funktionen

Die X-KG-Reasoning-Schicht führt Schlussfolgerungen über den Wissensgraphen und das verifizierte ausführbare Substrat durch. Reparatur und inverses Design führen jeden Kandidaten vor der Rückgabe erneut durch transportations-library aus, sodass Ergebnisse als konform bewiesen und nicht nur behauptet werden. Es ist keine Datenbank erforderlich.

• reasoning_propagate_change – Vorwärtsverkettung: nachgelagerte Parameter, die von einer geänderten Eingabe betroffen sind

• reasoning_diagnose_failure – Rückwärtsverkettung: vorgelagerte Ursachen eines fehlschlagenden Parameters

• reasoning_repair_design – Abduktive Reparatur: minimale konforme Korrektur für eine zweistreifige Landstraße (HCM Ch.15)

• reasoning_repair_freeway – Abduktive Reparatur: minimale konforme Korrektur für einen Basis-Freeway (HCM Ch.12)

• reasoning_reconcile_codes – Widerlegbare Entscheidung über widersprüchliche Regelwerksbestimmungen mit einer Argumentationsspur

• reasoning_inverse_design – Zielgerichtete Synthese: realisierbare Geometrien, die einen Ziel-LOS erreichen

Abhängigkeiten: Die Reasoning-Funktionen erfordern transportations-validator>=0.2.0 und transportations-library>=0.1.12 (letzteres für das BasicFreeways-Binding, das von reasoning_repair_freeway verwendet wird). Beide sind auf PyPI, sodass eine normale pip install (oder uv sync) sie auflöst.

API-Endpunkte

Rufen Sie das Verzeichnis der API-Endpunkte auf, um Analysen durchzuführen oder die HCM-Dokumentation abzufragen.

Hinweis: /docs für eine detaillierte Beschreibung der API-Endpunkte befindet sich im Aufbau und wird bald verfügbar sein.

Kern-Endpunkte

• POST /tools/call – Führt eine beliebige registrierte Funktion aus

• POST /tools/list – Listet verfügbare Funktionen mit Filterung auf

• GET /mcp/discovery – MCP-Fähigkeitserkennung

HCM-Analyse pro Methode

POST /analysis/hcm/analyze                # {method, config}
POST /analysis/hcm/describe               # {method?} - catalog, or one method's schema + worked example
POST /analysis/hcm/validate               # {method, config} - parse and check, without running

POST /analysis/hcm/<method-with-hyphens>  # method-shaped convenience route, e.g. /analysis/hcm/analyze-roundabout

Die Pro-Methode-Routen akzeptieren {"config": { ... }} im Beispielschema der jeweiligen Methode. Siehe HCM-Analysefähigkeiten oben für die vollständige Liste.

Kapitel-15-Analyse

• POST /analysis/chapter15/complete – Vollständige HCM-Analyse

• POST /analysis/chapter15/segment – Analyse eines einzelnen Segments

Forschung

• POST /tools/query-hcm – HCM-Datenbank abfragen

• POST /research/search_hcm_by_chapter – HCM-Inhalte nach bestimmtem Kapitel durchsuchen

• GET /research/get_hcm_section – Inhalt eines bestimmten HCM-Abschnitts abrufen

• POST /research/summarize_hcm_content – HCM-Inhalte zu einem Thema zusammenfassen

Reasoning & Validierung

Dedizierte Endpunkte (und damit erstklassige MCP-Tools) für die X-KG-Reasoning-Schicht und die Vollkorpus-Validierung. Jeder bezieht seine Implementierung aus der Registrierung, sodass die Oberfläche mit function_registry.yaml synchron bleibt.

• POST /reason/propagate-change – Vorwärtsverkettung nachgelagerter Auswirkungen

• POST /reason/diagnose-failure – Rückwärtsverkettung vorgelagerter Ursachen

• POST /reason/repair-design – Minimale konforme Korrektur (zweistreifige Landstraße, HCM Ch.15)

• POST /reason/repair-freeway – Minimale konforme Korrektur (Basis-Freeway, HCM Ch.12)

• POST /reason/reconcile-codes – Widerlegbare Entscheidung über mehrere Zuständigkeitsbereiche hinweg

• POST /reason/inverse-design – Zielgerichtete Geometriesynthese

• POST /validate/design-full – Gegen den vollständigen Regelkorpus mit Zitaten + Klarstellungen validieren

Dienstprogramme

• GET /health – Gesundheitsprüfung

• GET /registry/info – Registrierungsinformationen

• POST /registry/reload – Funktionsregistrierung neu laden

Datenmodelle

Highway-Segment

{
  "passing_type": 0,      # 0=PC, 1=PZ, 2=PL
  "length": 2.0,          # miles
  "grade": 2.0,           # percent
  "spl": 50.0,            # speed limit (mph)
  "volume": 760.0,        # vehicles/hour
  "volume_op": 1500.0,    # opposing volume
  "phf": 0.95,            # peak hour factor
  "phv": 5.0              # percent heavy vehicles
}

Highway-Facility

{
  "segments": [...],      # list of segments
  "lane_width": 12.0,     # feet
  "shoulder_width": 6.0,  # feet
  "apd": 5.0,             # access points/mile
  "pmhvfl": 0.02,         # percent HV in fast lane
  "l_de": 0.0             # effective passing distance
}

Hinzufügen neuer HCM-Kapitel

1. Funktionsmodul erstellen

Erstellen Sie functions/chapter16.py:

def new_analysis_function(data: Dict[str, Any]) -> Dict[str, Any]:
    """Implementation for new analysis."""
    try:
        # Your implementation here
        return {"success": True, "result": "analysis_result"}
    except Exception as e:
        return {"success": False, "error": str(e)}

2. Registrierung aktualisieren

Fügen Sie zu functions_registry.yaml hinzu:

functions:
  chapter16:
    new_analysis:
      module: "functions.chapter16"
      function: "new_analysis_function"
      description: "New analysis function"
      category: "transportation"
      chapter: 16
      parameters:
        type: "object"
        properties:
          input_param:
            type: "string"
        required: ["input_param"]

3. Server neu starten

Die Registrierung lädt die neuen Funktionen automatisch.

Entwicklung

Tests ausführen

Hinweis: Tests werden bald hinzugefügt.

pytest tests/

Registrierung validieren

Hinweis: Noch nicht verwendet.

python scripts/validate_registry.py

Einrichten der Entwicklungsdatenbank

python scripts/import_hcm_docs.py

Anpassung

Benutzerdefinierte Analysemodelle

Erweitern Sie Modelle in core/models.py:

class CustomAnalysisInput(BaseModel):
    parameter1: float = Field(description="Custom parameter")
    parameter2: str = Field(description="Another parameter")

Benutzerdefinierte Funktionen

1. Funktion im entsprechenden Modul implementieren

2. Zu functions_registry.yaml hinzufügen

3. Server neu starten oder /registry/reload aufrufen

Support

Dieses Projekt befindet sich in der Betaphase und dient derzeit hauptsächlich Forschungszwecken. Beiträge oder Feedback sind sehr willkommen!

Bei Problemen und Fragen:

• Ein Issue auf GitHub eröffnen

• Die API-Dokumentation unter /docs prüfen

• Die Funktionsregistrierung unter /registry/info einsehen

• Das Setup mit Dienstprogramm-Skripten validieren