HCM-LLM MCP Server

고속도로 용량편람(HCM) 분석 및 교통공학 계산을 위한 FastAPI 기반 Model Context Protocol(MCP) 서버입니다. 현재 이 서버는 HCM 15장 방법론에 따른 종합적인 2차로 도로 분석을 제공합니다.

기능

• HCM 문서에 대한 시맨틱 검색

• HCM 15장(2차로 도로) 및 12장(기본 고속도로) 분석 전체

• 10장부터 28장까지의 전체 HCM 장을 세 가지 기능 도구(hcm_analyze, hcm_describe, hcm_validate)로 제공하며, 33개 메서드 각각은 라이브러리 자체 예제 케이스 JSON을 입력으로 받고 각각 게시된 예제 문제에 대해 검증됩니다.

• HCM/AASHTO 제약 조건에 대한 입력 검증 게이트웨이(transportations-validator 사용)

• 인용, 지형/상황 게이트 규칙, 명확화 요청을 포함한 전체 말뭉치 검증(HCM/AASHTO/MUTCD/HSM/ADA/... 300개 이상 규칙) — 프로세스 내에서 실행되며 데이터베이스 불필요

• 지식 그래프 추론: 귀추적 설계 수리(2차로 및 기본 고속도로), 취소 가능한 코드 조정, 역설계, 전방/후방 연결 — 모든 수리 후보는 검증된 라이브러리를 통해 재실행됩니다.

• 쉬운 확장을 위한 YAML 기반 함수 레지스트리

• 15개 이상의 교통 분석 함수를 제공하는 함수 호출 인터페이스

• AI 어시스턴트와의 통합을 위한 MCP 서버 호환성(Claude 지원)

• 직접 액세스를 위한 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

두 실행기는 모두 앱을 가져오기 전에 두 개의 환경 변수를 설정하는 얇은 래퍼입니다:

• 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장과 다른 방정식 계열입니다 — 차로 폭 -> FFS -> 용량/속도 -> 밀도 -> 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장)는 세 가지 기능 도구 뒤에 있습니다. 메서드는 도구가 아니라 인자입니다. 33개의 거의 동일한 스키마는 모든 호출자의 컨텍스트를 소모하고 도구 선택을 무디게 만들기 때문입니다. 위의 열 가지 공개 도구는 이미 기능 형태를 갖추고 있습니다.

• hcm_analyze — {method, config}. 하나의 메서드를 실행합니다. 도구 설명에는 각각 한 줄로 된 메서드 카탈로그가 포함되며, method는 33개 ID의 열거형입니다.

• hcm_describe — {method?}. 메서드가 있으면: 입력 스키마 개요, 결과 필드 의미, 그리고 이를 검증하는 예제 문제 픽스처를 반환합니다. 메서드가 없으면: 카탈로그, 각 메서드 ID와 해당 장 및 한 줄 요약을 반환합니다. 이 도구를 먼저 호출하세요. 호출자가 Rust 바인딩을 읽지 않고 메서드의 형태를 파악하는 방법입니다.

• hcm_validate — {method, config}. 분석을 실행하지 않고 구성을 구문 분석하고 검사하여 라이브러리 자체의 검증 오류 또는 ok를 반환합니다. 구성을 반복하는 데는 전체 분석이 아닌 구문 분석만 필요합니다. 33개 메서드 중 24개는 생성자 뒤에 실제 검증 단계가 있습니다(serde 역직렬화, 생성자 범위 검사, 15장의 경우 tl.validate_input을 통한 Exhibit 15-8 매개변수 범위). 나머지 9개는 라이브러리에서 구문 분석과 계산이 하나의 호출로 이루어지는 단일 JSON 진입점이며, 분석을 실행하고 이를 검증이라고 부르는 대신 응답에 그렇게 명시합니다.

입력은 항상 컴퓨트 라이브러리 자체의 예제 케이스(픽스처) JSON이며 config로 전달됩니다. MCP 계층을 위해 새로 만든 두 번째 평면화 스키마가 아닙니다. 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 절제(ablation) 분기이며, 기본적으로 노출하는 열 개 도구는 게시된 실험이 실행된 표면입니다(tests/test_frozen_surface.py 참조). HCM_MCP_FULL_COVERAGE=true를 설정하면 세 가지 기능 도구를 MCP 마운트에 추가할 수 있습니다. 설정하지 않아도 REST 및 /tools/call을 통해 계속 접근할 수 있습니다.

검증 함수

• validation_validate_design_full - 인용, 지형/관할권 게이트 규칙, 입력이 누락되거나 컨텍스트가 모호할 때의 명확화 요청을 포함하여 전체 규칙 말뭉치(300개 이상의 규칙: HCM, AASHTO, MUTCD, HSM, ADA, OpenDRIVE, ...)에 대해 설계를 검증합니다. 번들된 시드 말뭉치에 대해 프로세스 내에서 실행되며 데이터베이스가 필요 없습니다. (Chapter 15/12 도구는 더 가벼운 의미론적 방화벽 게이트웨이를 사용합니다. 이것은 완전한 엔진입니다.) transportations-validator>=0.2.0 + sqlalchemy가 필요합니다.

연구 함수

• query_hcm - HCM 문서 데이터베이스 쿼리

추론 함수

X-KG 추론 계층은 지식 그래프와 검증된 실행 가능 기반 위에서 추론합니다. 수리 및 역설계 기능은 결과를 반환하기 전에 모든 후보를 transportations-library로 재실행하므로, 결과는 주장이 아니라 증명된 적합성을 갖습니다. 데이터베이스가 필요 없습니다.

• reasoning_propagate_change - 전방 추론: 변경된 입력의 영향을 받는 하류 매개변수

• reasoning_diagnose_failure - 후방 추론: 실패하는 매개변수의 상류 원인

• reasoning_repair_design - 귀추적 수리: Two-Lane Highway(HCM Ch.15)에 대한 최소 적합 수정

• reasoning_repair_freeway - 귀추적 수리: Basic Freeway(HCM Ch.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 분석 기능을 참조하세요.

Chapter 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 - 최소 적합 수정(Two-Lane Highway, HCM Ch.15)

• POST /reason/repair-freeway - 최소 적합 수정(Basic Freeway, HCM Ch.12)

• POST /reason/reconcile-codes - 취소 가능한 다중 관할권 판정

• POST /reason/inverse-design - 목표 지향 기하 구조 합성

• POST /validate/design-full - 인용 + 명확화와 함께 전체 규칙 말뭉치에 대한 검증

유틸리티

• GET /health - 상태 확인

• GET /registry/info - 레지스트리 정보

• POST /registry/reload - 함수 레지스트리 다시 로드

데이터 모델

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
}

새 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에 이슈 열기

• /docs에서 API 문서 확인

• /registry/info에서 함수 레지스트리 검토

• 유틸리티 스크립트로 설정 검증