HCM-LLM MCP Server

Un servidor Model Context Protocol (MCP) basado en FastAPI para el análisis del Manual de Capacidad de Carreteras (HCM) y cálculos de ingeniería de transporte. Hasta ahora, este servidor proporciona un análisis exhaustivo de carreteras de dos carriles siguiendo la metodología del Capítulo 15 del HCM.

Características

• Búsqueda semántica sobre la documentación del HCM

• Análisis completo del Capítulo 15 del HCM (carretera de dos carriles) y del Capítulo 12 (autopista básica)

• Cobertura completa de los capítulos del HCM, del 10 al 28, a través de tres herramientas de capacidad (hcm_analyze, hcm_describe, hcm_validate) con 33 métodos, cada uno de los cuales toma el JSON de caso de ejemplo de la propia biblioteca y se valida contra su problema de ejemplo publicado

• Puerta de validación de entrada contra las restricciones de HCM/AASHTO (a través de transportations-validator)

• Validación de todo el corpus (más de 300 reglas en HCM/AASHTO/MUTCD/HSM/ADA/...) con citas, reglas condicionadas por terreno/contexto y solicitudes de aclaración: se ejecuta en proceso, sin base de datos

• Razonamiento basado en grafo de conocimiento: reparación de diseño abductiva (de dos carriles y autopista básica), reconciliación derrotable de código, diseño inverso y encadenamiento hacia adelante/atrás: cada candidato de reparación se vuelve a ejecutar a través de la biblioteca verificada

• Registro de funciones basado en YAML para una fácil extensibilidad

• Interfaz de llamada a funciones con más de 15 funciones de análisis de transporte

• Compatibilidad con servidores MCP para la integración con asistentes de IA (compatible con Claude)

• Endpoints de API RESTful para acceso directo

• Generación dinámica de endpoints basada en el registro

• Suite de pruebas integral y herramientas de validación

Related MCP server: MCP WebAnalyzer

Conectar al servidor MCP remoto

Este servidor se puede utilizar como backend para agentes de código de IA como Claude Desktop, lo que les permite realizar análisis de transporte complejos y acceder a la documentación del HCM de forma dinámica.

Para habilitar esta funcionalidad, añade el servidor a la configuración de tu asistente de IA como un servidor MCP.

Para usuarios de Claude Desktop

Desde la configuración de usuario, puedes encontrar la pestaña Connectors y hacer clic en Add custom connector.

Luego añade https://api.hcm-calculator.com/mcp a tu configuración de Claude.

Para usuarios de GitHub Copilot en VSCode

También puedes usar este servidor con GitHub Copilot configurándolo como un servidor MCP personalizado.

Para ello, escribe Ctrl+p y selecciona MCP: Open User Configuration y modifica lo siguiente en tu mcp.json:

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

Conectar al servidor MCP local

También puedes ejecutar este servidor localmente para fines de desarrollo o pruebas.

uv venv

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

uv pip install .

Luego, ejecuta el servidor.

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

# Start the server.
python mcp_server_fastapi.py

Para usuarios de Claude Desktop

Abre Claude Desktop y añade el servidor como un servidor MCP personalizado con la URL http://localhost:8000/mcp.

Añade a tu configuración de Claude Desktop (claude_desktop_config.json):

Nota: Parece que estos ajustes json no funcionan últimamente (https://github.com/anthropics/claude-code/issues/4188), y tampoco funcionaron en mi entorno de escritorio.

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

Para usuarios de GitHub Copilot en VSCode

Lo mismo que arriba, puedes usar este servidor con GitHub Copilot configurándolo como un servidor MCP personalizado.

Para ello, escribe Ctrl+p y selecciona MCP: Open User Configuration y modifica lo siguiente en tu mcp.json:

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

Entonces puedes usar la interfaz de llamada a funciones directamente en tu editor de código.

Estructura del proyecto

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

Configuración

Variables de entorno

Crea un archivo .env basado en .env.example. Copia y pega el siguiente contenido, o 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

Registro de funciones

Las funciones se definen en 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"]

Variantes de ablación (superficies MCP restringidas)

Para la ablación 2x2 de la Tabla 5 / Figura 7, la misma aplicación se puede lanzar exponiendo solo un subconjunto de herramientas, de modo que un modelo pueda evaluarse en cada condición de forma aislada:

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

Ambos lanzadores son envoltorios ligeros que establecen dos variables de entorno antes de importar la aplicación:

• HCM_MCP_INCLUDE_OPS — identificadores de operación separados por comas que expone la superficie MCP (sin establecer = todos). El filtrado utiliza FastApiMCP(include_operations=...).

• HCM_ENABLE_RAG — establecido en false para omitir la carga del modelo de incrustación + almacén vectorial (la variante solo-kg no necesita ninguno).

Apunta cada cliente MCP de VS Code / Claude Desktop al puerto de la variante bajo prueba (p. ej. http://localhost:8001 para solo-kg) para que el modelo vea solo las herramientas de esa variante. La variante base es simplemente ningún servidor MCP adjunto.

Uso de la API

Análisis completo de carreteras

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

Interfaz de llamada a funciones

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

Listar funciones disponibles

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

Consultar la documentación del 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
  }'

Funciones disponibles

Funciones del Capítulo 15

• chapter15_identify_vertical_class - Paso 1: Identificar el rango de clase de alineación vertical

• chapter15_determine_demand_flow - Paso 2: Calcular las tasas de flujo de demanda y la capacidad

• chapter15_determine_vertical_alignment - Paso 3: Determinar la clasificación de la alineación vertical

• chapter15_determine_free_flow_speed - Paso 4: Calcular la velocidad de flujo libre

• chapter15_estimate_average_speed - Paso 5: Estimar la velocidad media de viaje

• chapter15_estimate_percent_followers - Paso 6: Estimar el porcentaje de vehículos que siguen

• chapter15_determine_follower_density_pl - Paso 8a: Densidad de seguidores para carriles de adelantamiento

• chapter15_determine_follower_density_pc_pz - Paso 8b: Densidad de seguidores para segmentos PC/PZ

• chapter15_determine_segment_los - Paso 9: Calcular el Nivel de Servicio del segmento

• chapter15_determine_facility_los - Paso 10: Calcular el Nivel de Servicio de la instalación

• chapter15_complete_analysis - Procedimiento completo del Capítulo 15 del HCM

Funciones del Capítulo 12 (Segmentos de autopista básica)

Una familia de ecuaciones diferente a la del Capítulo 15: la cadena lane width -> FFS -> capacity/speed -> density -> LOS. Requiere transportations-library>=0.1.12.

• chapter12_determine_free_flow_speed - Paso 2: Estimar y ajustar la velocidad de flujo libre

• chapter12_estimate_capacity - Paso 3: Capacidad base y ajustada (pc/h/ln)

• chapter12_estimate_demand_volume - Paso 4: Tasa de flujo por carril v_p

• chapter12_calculate_speed - Paso 5a: Velocidad media espacial mediante la curva velocidad-flujo

• chapter12_estimate_density - Paso 5b: Densidad D = v_p / S

• chapter12_determine_segment_los - Paso 6: Nivel de Servicio del segmento

• chapter12_complete_analysis - Procedimiento completo de autopista básica del Capítulo 12 del HCM

Capacidades de análisis del HCM (cobertura completa de capítulos)

Cada método del HCM que implementa la biblioteca de cálculo, capítulos 10 al 28, detrás de tres herramientas de capacidad. El método es un argumento, no una herramienta: treinta y tres esquemas casi idénticos costarían contexto a cada llamador y embotarían la selección de herramientas, y las diez herramientas publicadas anteriormente ya tienen forma de capacidad.

• hcm_analyze — {method, config}. Ejecuta un método. La descripción de la herramienta incluye el catálogo de métodos, una línea compacta por cada uno, y method es una enumeración de los treinta y tres identificadores.

• hcm_describe — {method?}. Con un método: el esquema de su entrada, el significado de sus campos de resultado y el caso de ejemplo que lo valida. Sin uno: el catálogo, cada identificador de método con su capítulo y un resumen de una línea. Llama a esto primero; así es como un llamador aprende la forma de un método sin leer los bindings de Rust.

• hcm_validate — {method, config}. Analiza y comprueba una configuración sin ejecutar el análisis, devolviendo los errores de validación de la propia biblioteca u ok. Iterar sobre una configuración cuesta un análisis sintáctico en lugar de un análisis completo. Veinticuatro de los treinta y tres métodos tienen un paso de validación real detrás del constructor (deserialización de serde, comprobaciones de rango del constructor y, para el Capítulo 15, los rangos de parámetros del Exhibit 15-8 mediante tl.validate_input); los otros nueve son puntos de entrada JSON únicos en la biblioteca donde el análisis sintáctico y el cálculo son una sola llamada, y así lo indican en la respuesta en lugar de ejecutar el análisis y llamarlo validación.

La entrada es siempre el JSON de caso de ejemplo (fixture) de la propia biblioteca de cálculo, pasado como config, no un segundo esquema aplanado inventado para la capa MCP. Un caso de ejemplo de transportations-library/tests/ExampleCases/hcm/ se puede entregar sin modificaciones. Requiere transportations-library>=0.3.7.

Cada método incluye su ejemplo resuelto en hcm_mcp_server/data/examples/<method>.json, y tests/test_methods.py ejecuta cada uno de ellos a través de hcm_analyze frente a los valores publicados de ese problema de ejemplo, con las tolerancias que establece la propia suite de pruebas de la librería de cálculo.

Cada método también mantiene una ruta REST con la forma del método en /analysis/hcm/<method-with-hyphens> para quienes llaman a la API directamente. Las rutas no son herramientas MCP, por lo que no consumen nada del contexto de quien las invoca.

Los rechazos de dominio llevan el mensaje propio de la librería. Una pendiente de flujo mixto sin digitalizar, un PCE de pendiente ascendente específica fuera de dominio y una configuración malformada devuelven {"success": false, "error": "..."} con las palabras de la librería, porque esos mensajes indican qué cubren los datos HCM publicados.

Estas herramientas no están en la superficie MCP predeterminada. mcp_server_fastapi.py es el brazo de ablación ct, y las diez herramientas que anuncia por defecto son la superficie contra la que se ejecutó el experimento publicado (consulte tests/test_frozen_surface.py). Establezca HCM_MCP_FULL_COVERAGE=true para añadir las tres herramientas de capacidad al montaje MCP. Sin ello, siguen siendo accesibles a través de REST y de /tools/call.

Funciones de Validación

• validation_validate_design_full - Valida un diseño contra el corpus completo de reglas (más de 300 reglas: HCM, AASHTO, MUTCD, HSM, ADA, OpenDRIVE, ...) con citas, reglas condicionadas por terreno/jurisdicción y solicitudes de aclaración cuando falta una entrada o su contexto es ambiguo. Se ejecuta en proceso sobre el corpus semilla incluido — sin base de datos. (Las herramientas de los Capítulos 15/12 utilizan una pasarela de cortafuegos semántico más ligera; este es el motor completo.) Requiere transportations-validator>=0.2.0 + sqlalchemy.

Funciones de Investigación

• query_hcm - Consulta la base de datos de documentación HCM

Funciones de Razonamiento

La capa de razonamiento X-KG razona sobre el grafo de conocimiento y el sustrato ejecutable verificado. La reparación y el diseño inverso re-ejecutan cada candidato a través de transportations-library antes de devolverlo, por lo que los resultados quedan demostrados como conformes en lugar de simplemente afirmados. No se requiere base de datos.

• reasoning_propagate_change - Encadenamiento hacia adelante: parámetros posteriores afectados por una entrada modificada

• reasoning_diagnose_failure - Encadenamiento hacia atrás: causas anteriores de un parámetro que falla

• reasoning_repair_design - Reparación abductiva: corrección mínima conforme para una carretera de dos carriles (HCM Cap. 15)

• reasoning_repair_freeway - Reparación abductiva: corrección mínima conforme para una autopista básica (HCM Cap. 12)

• reasoning_reconcile_codes - Adjudicación derrotable de disposiciones normativas en conflicto, con un rastro de argumentación

• reasoning_inverse_design - Síntesis dirigida por objetivos: geometrías factibles que alcanzan un LOS objetivo

Dependencias: las funciones de razonamiento requieren transportations-validator>=0.2.0 y transportations-library>=0.1.12 (esta última para el enlace BasicFreeways utilizado por reasoning_repair_freeway). Ambas están en PyPI, por lo que una instalación normal con pip install (o uv sync) las resuelve.

Endpoints de la API

Acceda al directorio de endpoints de la API para realizar análisis o consultar la documentación HCM.

Nota: /docs, la descripción detallada de los endpoints de la API, está en construcción y estará disponible pronto.

Endpoints Principales

• POST /tools/call - Ejecuta cualquier función registrada

• POST /tools/list - Lista las funciones disponibles con filtrado

• GET /mcp/discovery - Descubrimiento de capacidades MCP

Análisis HCM por método

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

Las rutas por método aceptan {"config": { ... }} en el esquema del caso de ejemplo de ese método. Consulte Capacidades de Análisis HCM más arriba para ver la lista completa.

Análisis del Capítulo 15

• POST /analysis/chapter15/complete - Análisis HCM completo

• POST /analysis/chapter15/segment - Análisis de un segmento individual

Investigación

• POST /tools/query-hcm - Consulta la base de datos HCM

• POST /research/search_hcm_by_chapter - Busca contenido HCM por capítulo específico

• GET /research/get_hcm_section - Obtiene el contenido de una sección HCM específica

• POST /research/summarize_hcm_content - Resume el contenido HCM para un tema

Razonamiento y Validación

Endpoints dedicados (y por tanto herramientas MCP de primera clase) para la capa de razonamiento X-KG y la validación de corpus completo. Cada uno resuelve su implementación desde el registro, por lo que la superficie se mantiene sincronizada con function_registry.yaml.

• POST /reason/propagate-change - Encadenamiento hacia adelante de impactos posteriores

• POST /reason/diagnose-failure - Encadenamiento hacia atrás de causas anteriores

• POST /reason/repair-design - Corrección mínima conforme (carretera de dos carriles, HCM Cap. 15)

• POST /reason/repair-freeway - Corrección mínima conforme (autopista básica, HCM Cap. 12)

• POST /reason/reconcile-codes - Adjudicación derrotable multijurisdiccional

• POST /reason/inverse-design - Síntesis de geometría dirigida por objetivos

• POST /validate/design-full - Valida contra el corpus completo de reglas con citas y aclaraciones

Utilidades

• GET /health - Comprobación de estado

• GET /registry/info - Información del registro

• POST /registry/reload - Recarga el registro de funciones

Modelos de Datos

Segmento de Carretera

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

Instalación de Carretera

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

Añadir Nuevos Capítulos HCM

1. Crear el Módulo de Función

Cree 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. Actualizar el Registro

Añada a 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. Reiniciar el Servidor

El registro cargará automáticamente las nuevas funciones.

Desarrollo

Ejecutar Pruebas

Nota: Las pruebas se añadirán pronto.

pytest tests/

Validar el Registro

Nota: Aún no se utiliza.

python scripts/validate_registry.py

Configurar la Base de Datos de Desarrollo

python scripts/import_hcm_docs.py

Personalización

Modelos de Análisis Personalizados

Amplíe los modelos en core/models.py:

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

Funciones Personalizadas

1. Implemente la función en el módulo correspondiente

2. Añádala a functions_registry.yaml

3. Reinicie el servidor o llame a /registry/reload

Soporte

Este proyecto está en versión beta y por ahora tiene principalmente fines de investigación. ¡Se agradecen enormemente las contribuciones o comentarios!

Para problemas y preguntas:

• Abra un issue en GitHub

• Consulte la documentación de la API en /docs

• Revise el registro de funciones en /registry/info

• Valide la configuración con los scripts de utilidad