HCM-LLM MCP Server

FastAPIベースのModel Context Protocol (MCP)サーバーで、Highway Capacity Manual (HCM)の解析と交通工学計算を提供します。現時点では、このサーバーはHCM第15章の方法論に従った包括的な2車線道路解析を提供します。

特徴

• HCMドキュメントのセマンティック検索

• HCM第15章（2車線道路）と第12章（基本フリーウェイ区間）の完全な解析

• HCM全章（第10章から第28章）を、3つのケイパビリティツール（hcm_analyze、hcm_describe、hcm_validate）を通じて、33のメソッドにわたってカバーしています。各メソッドはライブラリ独自のサンプルケースJSONを受け取り、公開された例題に対して検証済みです。

• HCM/AASHTOの制約に対する入力検証ゲートウェイ（transportations-validator経由）

• 全文書コーパス検証（HCM/AASHTO/MUTCD/HSM/ADA/...にわたる300以上のルール）。引用付き、地形・文脈でゲートされたルール、明確化リクエストに対応 — プロセス内で実行され、データベース不要です。

• ナレッジグラフ推論：アブダクションによる設計修正（2車線道路および基本フリーウェイ区間）、反証可能なコード整合、逆設計、前方/後方連鎖 — すべての修正候補は検証済みライブラリを通じて再実行されます。

• YAMLベースの関数レジストリによる容易な拡張性

• 15以上の交通解析関数を備えた関数呼び出しインターフェース

• AIアシスタント（Claude対応）との統合のためのMCPサーバー互換性

• 直接アクセスのためのRESTful APIエンドポイント

• レジストリに基づく動的エンドポイント生成

• 包括的なテストスイートと検証ツール

Related MCP server: MCP WebAnalyzer

リモートMCPサーバーへの接続

このサーバーは、Claude DesktopなどのAIコードエージェントのバックエンドとして使用でき、複雑な交通解析を実行し、HCMドキュメントに動的にアクセスできるようにします。

この機能を有効にするには、サーバーをAIアシスタントの設定にMCPサーバーとして追加してください。

Claude Desktopユーザー向け

ユーザー設定でConnectorsタブを見つけ、Add custom connectorをクリックします。

次に、https://api.hcm-calculator.com/mcp をClaude設定に追加します。

VSCode上のGitHub Copilotユーザー向け

このサーバーは、カスタムMCPサーバーとして設定することで、GitHub Copilotでも使用できます。

これを行うには、Ctrl+pを押してMCP: Open User Configurationを選択し、mcp.jsonに次のように変更します：

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

ローカルMCPサーバーへの接続

開発やテスト目的で、このサーバーをローカルで実行することもできます。

uv venv

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

uv pip install .

その後、サーバーを実行します。

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

# Start the server.
python mcp_server_fastapi.py

Claude Desktopユーザー向け

Claude Desktopを開き、URL http://localhost:8000/mcp でサーバーをカスタムMCPサーバーとして追加します。

Claude Desktopの設定（claude_desktop_config.json）に追加します：

注記: 最近このjson設定は機能していないようです（https://github.com/anthropics/claude-code/issues/4188）。私のデスクトップ環境でも機能しませんでした。

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

VSCode上のGitHub Copilotユーザー向け

上記と同様に、このサーバーをカスタムMCPサーバーとして設定することで、GitHub Copilotで使用できます。

これを行うには、Ctrl+pを押してMCP: Open User Configurationを選択し、mcp.jsonに次のように変更します：

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

その後、コードエディタで関数呼び出しインターフェースを直接使用できます。

プロジェクト構造

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

設定

環境変数

.env.exampleに基づいて.envファイルを作成します。次の内容をコピーして貼り付けるか、cp .env.example .envを実行します：

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

関数レジストリ

関数はfunctions_registry.yamlで定義されています：

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"]

アブレーションアーム（制限付きMCPサーフェス）

Table 5 / Figure 7の2x2アブレーションでは、同じアプリをツールのサブセットのみを公開して起動できるため、各条件を単独でモデル評価できます：

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

両方のランチャーは、アプリをインポートする前に2つの環境変数を設定する薄いラッパーです：

• HCM_MCP_INCLUDE_OPS — MCPサーフェスが公開する操作IDのカンマ区切りリスト（未設定 = すべて）。フィルタリングにはFastApiMCP(include_operations=...)を使用します。

• HCM_ENABLE_RAG — falseに設定すると、埋め込みモデルとベクトルストアの読み込みをスキップします（kgのみのアームにはどちらも不要です）。

各VS Code / Claude Desktop MCPクライアントを、テスト対象アームのポート（例：kgのみの場合はhttp://localhost:8001）に向けます。これにより、モデルはそのアームのツールのみを認識します。baseアームは、単にMCPサーバーを接続しない状態です。

APIの使用法

完全な高速道路解析

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
  }'

関数呼び出しインターフェース

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
        }
      }
    }
  }'

利用可能な関数の一覧

# 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ドキュメントのクエリ

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
  }'

利用可能な関数

第15章の関数

• chapter15_identify_vertical_class - ステップ1：縦断線形クラスの範囲を特定

• chapter15_determine_demand_flow - ステップ2：需要交通流率と容量を計算

• chapter15_determine_vertical_alignment - ステップ3：縦断線形の分類を決定

• chapter15_determine_free_flow_speed - ステップ4：自由走行速度を計算

• chapter15_estimate_average_speed - ステップ5：平均旅行速度を推定

• chapter15_estimate_percent_followers - ステップ6：追従車両の割合を推定

• chapter15_determine_follower_density_pl - ステップ8a：追越車線の追従密度

• chapter15_determine_follower_density_pc_pz - ステップ8b：PC/PZ区間の追従密度

• chapter15_determine_segment_los - ステップ9：区間のサービス水準を計算

• chapter15_determine_facility_los - ステップ10：施設全体のサービス水準を計算

• chapter15_complete_analysis - HCM第15章の手順全体を実行

第12章の関数（基本フリーウェイ区間）

第15章とは異なる方程式群です — lane width -> FFS -> capacity/speed -> density -> LOSの連鎖。transportations-library>=0.1.12が必要です。

• chapter12_determine_free_flow_speed - ステップ2：自由走行速度を推定・調整

• chapter12_estimate_capacity - ステップ3：基本容量と調整容量（pc/h/ln）

• chapter12_estimate_demand_volume - ステップ4：車線あたりの交通流率 v_p

• chapter12_calculate_speed - ステップ5a：速度-交通流曲線による空間平均速度

• chapter12_estimate_density - ステップ5b：密度 D = v_p / S

• chapter12_determine_segment_los - ステップ6：区間のサービス水準

• chapter12_complete_analysis - HCM第12章の基本フリーウェイ手順全体を実行

HCM解析ケイパビリティ（全章カバー）

計算ライブラリが実装するすべてのHCMメソッド（第10章から第28章）を、3つのケイパビリティツールの背後にまとめています。メソッドはツールではなく引数です。33個のほぼ同一のスキーマは、すべての呼び出し元のコンテキストを消費し、ツール選択を鈍らせるため、上記の10個の公開ツールはすでにケイパビリティ型になっています。

• hcm_analyze — {method, config}。1つのメソッドを実行します。ツールの説明にはメソッドカタログが各1行の簡潔な形式で含まれ、methodは33個のIDのenumです。

• hcm_describe — {method?}。メソッドを指定した場合：その入力スキーマの概要、結果フィールドの意味、およびそれを検証する例題フィクスチャを返します。指定しない場合：カタログ、各メソッドIDとその章、および1行の要約を返します。これを最初に呼び出してください。呼び出し元がRustバインディングを読まずにメソッドの形状を把握する方法です。

• hcm_validate — {method, config}。解析を実行せずに設定を解析・チェックし、ライブラリ独自の検証エラーまたはokを返します。設定の反復には、完全な解析ではなくパースのみのコストがかかります。33のメソッドのうち24は、コンストラクタの背後に実際の検証ステップがあります（serdeデシリアライゼーション、コンストラクタの範囲チェック、第15章ではtl.validate_inputによるExhibit 15-8のパラメータ範囲）。残りの9つは、ライブラリ内の単一のJSONエントリポイントであり、パースと計算が1回の呼び出しで行われます。これらのメソッドは、解析を実行して検証と呼ぶのではなく、その旨をレスポンスに明記します。

入力は常に計算ライブラリ独自のサンプルケース（フィクスチャ）JSONであり、configとして渡されます — MCPレイヤー用に考案された2番目のフラット化スキーマではありません。transportations-library/tests/ExampleCases/hcm/のサンプルケースは、そのまま渡すことができます。transportations-library>=0.3.7が必要です。

各メソッドは、計算例を hcm_mcp_server/data/examples/<method>.json に同梱しており、tests/test_methods.py は、その例題の公開値に対して、計算ライブラリ自身のテストスイートが定める許容誤差で、hcm_analyze を通じて全メソッドを駆動します。

各メソッドはまた、直接のAPI呼び出し元向けに、/analysis/hcm/<method-with-hyphens> にメソッド単位のRESTルートを保持しています。ルートはMCPツールではないため、呼び出し元のコンテキストを一切消費しません。

ドメイン外の拒否応答は、ライブラリ自身のメッセージを返します。デジタル化されていない混在交通流のグレード、ドメイン外の特定アップグレードPCE、不正な設定はすべて、ライブラリの言葉で {"success": false, "error": "..."} として返されます。これらのメッセージは、公開されているHCMデータがカバーする範囲を示しているためです。

これらのツールはデフォルトのMCPサーフェスには含まれていません。 mcp_server_fastapi.py は ct アブレーション群であり、デフォルトで公開する10個のツールが、公開された実験が実行されたサーフェスです（tests/test_frozen_surface.py を参照）。HCM_MCP_FULL_COVERAGE=true を設定すると、3つのケイパビリティツールをMCPマウントに追加できます。設定しない場合でも、RESTおよび /tools/call 経由で到達可能です。

検証関数

• validation_validate_design_full - 引用付きで、設計を完全なルールコーパス（300以上のルール：HCM、AASHTO、MUTCD、HSM、ADA、OpenDRIVE、...）に対して検証します。地形・管轄区域で制御されるルール、入力が欠落している場合やそのコンテキストが曖昧な場合の明確化要求も含みます。バンドルされたシードコーパスに対してプロセス内で実行されるため、データベースは不要です。（第15章/第12章のツールはより軽量なセマンティックファイアウォールゲートウェイを使用しますが、これは完全なエンジンです。）transportations-validator>=0.2.0 + sqlalchemy が必要です。

リサーチ関数

• query_hcm - HCMドキュメントデータベースを照会します

推論関数

X-KG推論レイヤーは、ナレッジグラフと検証済みの実行可能基盤の上で推論します。修復と逆設計は、結果を返す前にすべての候補を transportations-library で再実行するため、結果は主張されるのではなく適合が証明されます。データベースは不要です。

• reasoning_propagate_change - フォワードチェーン：変更された入力によって影響を受ける下流パラメータ

• reasoning_diagnose_failure - バックワードチェーン：失敗しているパラメータの上流原因

• reasoning_repair_design - アブダクティブ修復：二車線道路（HCM第15章）に対する最小限の適合修正

• reasoning_repair_freeway - アブダクティブ修復：基本フリーウェイ（HCM第12章）に対する最小限の適合修正

• reasoning_reconcile_codes - 矛盾するコード規定の取消可能な裁定（論証トレース付き）

• reasoning_inverse_design - 目標指向合成：目標LOSに到達する実現可能な幾何形状

依存関係： 推論機能には transportations-validator>=0.2.0 と transportations-library>=0.1.12 が必要です（後者は reasoning_repair_freeway が使用する BasicFreeways バインディング用）。どちらもPyPIにあるため、通常の pip install（または uv sync）で解決できます。

APIエンドポイント

APIエンドポイントディレクトリにアクセスして、分析を実行したりHCMドキュメントを照会したりできます。

注記: 詳細なAPIエンドポイントの説明のための /docs は現在構築中で、まもなく利用可能になる予定です。

コアエンドポイント

• POST /tools/call - 登録済みの任意の関数を実行します

• POST /tools/list - フィルタリング付きで利用可能な関数を一覧表示します

• GET /mcp/discovery - MCPケイパビリティのディスカバリ

メソッド単位のHCM分析

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

メソッド単位のルートは、そのメソッドの例題スキーマに従った {"config": { ... }} を受け取ります。完全なリストについては、上記のHCM分析ケイパビリティを参照してください。

第15章の分析

• POST /analysis/chapter15/complete - 完全なHCM分析

• POST /analysis/chapter15/segment - 単一セグメント分析

リサーチ

• POST /tools/query-hcm - HCMデータベースを照会します

• POST /research/search_hcm_by_chapter - 特定の章ごとにHCMコンテンツを検索します

• GET /research/get_hcm_section - 特定のHCMセクションのコンテンツを取得します

• POST /research/summarize_hcm_content - トピックに関するHCMコンテンツを要約します

推論と検証

X-KG推論レイヤーと完全コーパス検証のための専用エンドポイント（したがってファーストクラスのMCPツール）です。各エンドポイントはレジストリから実装を解決するため、サーフェスは function_registry.yaml と同期が保たれます。

• POST /reason/propagate-change - フォワードチェーンによる下流への影響

• POST /reason/diagnose-failure - バックワードチェーンによる上流原因

• POST /reason/repair-design - 最小限の適合修正（二車線道路、HCM第15章）

• POST /reason/repair-freeway - 最小限の適合修正（基本フリーウェイ、HCM第12章）

• POST /reason/reconcile-codes - 取消可能な複数管轄区域の裁定

• POST /reason/inverse-design - 目標指向の幾何形状合成

• POST /validate/design-full - 引用と明確化付きで完全なルールコーパスに対して検証します

ユーティリティ

• GET /health - ヘルスチェック

• GET /registry/info - レジストリ情報

• POST /registry/reload - 関数レジストリを再読み込みします

データモデル

道路セグメント

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

道路施設

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

新しいHCM章の追加

1. 関数モジュールを作成する

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. レジストリを更新する

functions_registry.yaml に追加します：

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. サーバーを再起動する

レジストリは新しい関数を自動的に読み込みます。

開発

テストの実行

注記: テストはまもなく追加される予定です。

pytest tests/

レジストリの検証

注記: まだ使用されていません。

python scripts/validate_registry.py

開発データベースのセットアップ

python scripts/import_hcm_docs.py

カスタマイズ

カスタム分析モデル

core/models.py のモデルを拡張します：

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

カスタム関数

1. 適切なモジュールに関数を実装します

2. functions_registry.yaml に追加します

3. サーバーを再起動するか、/registry/reload を呼び出します

サポート

このプロジェクトはベータ版であり、現時点では主に研究目的です。貢献やフィードバックは大歓迎です！

問題や質問については：

• GitHubでissueを開く

• /docs でAPIドキュメントを確認する

• /registry/info で関数レジストリを確認する

• ユーティリティスクリプトでセットアップを検証する