connected-car-mcp

Un servidor MCP (Model Context Protocol) sobre una flota sintética de vehículos conectados: telemetría, detección de anomalías basada en reglas y recomendaciones de mantenimiento, expuestos como cinco herramientas específicas en lugar de una interfaz de consulta abierta.

Construido como una pequeña ilustración autocontenida de un hábito de diseño específico: decidir qué pertenece detrás de un límite de herramienta y registrar cada llamada a través de él. Se ejecuta enteramente con datos sintéticos generados localmente: sin API externa, sin cuenta, sin fuente propietaria.

Por qué tiene esta forma

Todo el conjunto de datos podría exponerse a través de una única herramienta run_query(sql: str). Esa es la forma incorrecta para que un agente la llame de manera confiable: empuja el aprendizaje del esquema al modelo en el momento de la llamada, y no hay forma de delimitar o auditar "qué se puede preguntar" por capacidad. En su lugar:

Un modelo compone estas — resumen → elegir un vehículo marcado → extraer su telemetría → obtener una recomendación — en lugar de escribir consultas de forma libre contra filas brutas. También hace que la historia de auditoría sea trivial: solo hay cinco llamadas bien definidas que registrar, por lo que audit_log.jsonl (ver connected_car_mcp/audit.py) es una línea por llamada — marca de tiempo, herramienta, argumentos, duración, éxito/fracaso — sin lógica personalizada por herramienta. Un despliegue de producción emitiría el mismo registro como registros estructurados a través del hook middleware de MCPServer (que ve cada llamada JSON-RPC, herramienta o recurso) en lugar de un archivo local; el decorador aquí mantiene la demo ejecutable con cero infraestructura adicional.

Los umbrales de anomalía son simples y explicables (engine_temp_c >= 110, no un modelo entrenado) a propósito: los indicadores de un monitor de flota deben ser auditables por un humano, no solo precisos.

Related MCP server: mcp-live-telemetry

Datos

data/generate_telemetry.py genera un conjunto de datos determinista (semilla fija), totalmente sintético: 12 vehículos, lecturas cada 10 minutos durante 3 días. Algunos vehículos se siembran con fallos para que el detector de anomalías tenga una señal real que encontrar:

• CCV-004 — la temperatura del motor sube hasta el rango crítico (fallo del sistema de refrigeración)

• CCV-009 — el voltaje de la batería se degrada con el tiempo (batería/alternador defectuosos)

• CCV-002, CCV-011 — códigos de fallo DTC intermitentes

• CCV-006 — picos de velocidad ocasionales por conducción brusca

data/telemetry.csv está incluido en el repositorio para que se ejecute de inmediato; regenéralo con:

python data/generate_telemetry.py

Ejecutarlo

python -m venv .venv
.venv/Scripts/activate        # .venv/bin/activate on macOS/Linux
pip install -r requirements.txt

python -m connected_car_mcp.server   # starts the MCP server over stdio

Para probarlo desde Claude Desktop u otro cliente MCP, apúntalo al módulo con cwd establecido en la raíz del repositorio, por ejemplo en claude_desktop_config.json:

{
  "mcpServers": {
    "connected-car-fleet": {
      "command": "python",
      "args": ["-m", "connected_car_mcp.server"],
      "cwd": "/path/to/connected-car-mcp"
    }
  }
}

Luego pregunta algo como "¿Qué vehículos de la flota necesitan atención ahora mismo y por qué?" — el modelo llamará a fleet_health_summary, continuará con detect_anomalies en los vehículos marcados, y puede llamar a get_maintenance_recommendations para convertir eso en próximas acciones.

Pruebas

pip install pytest
pytest tests/

Cubre la capa de datos directamente (tamaño de la flota, manejo de vehículos desconocidos y que los fallos sembrados realmente se marquen) en lugar de hacer un recorrido completo a través de la capa de protocolo MCP.

Estructura del proyecto

connected_car_mcp/
  server.py       MCP tool + resource definitions
  data_store.py   Query layer over the telemetry CSV (pandas)
  audit.py        Per-call audit log decorator
data/
  generate_telemetry.py   Synthetic dataset generator
  telemetry.csv            Generated dataset (committed)
tests/
  test_data_store.py

Licencia

MIT — ver LICENSE.