Servidor MCP de la API de SNCF

Este proyecto proporciona un contenedor Python modular para la API de SNCF, con una interfaz de servidor MCP que se integra perfectamente con Claude Desktop para la planificación inteligente de viajes y la recuperación de información de trenes en toda Francia.

Tabla de contenido

• Descripción general
• Características
• Instalación
• Obtener una clave API
• Configuración
  • Configuración de Claude Desktop
  • Variables de entorno
• Herramientas MCP disponibles
  • Planificación de viajes
  • Información de la estación
  • Monitoreo de interrupciones
• Ejemplos de uso
• Solución de problemas
• Funciones avanzadas

Descripción general

El servidor MCP de SNCF proporciona una interfaz completa para los servicios API de los Ferrocarriles Nacionales Franceses (SNCF), lo que le permite:

• Planifique viajes en tren entre ciudades de Francia
• Obtenga información detallada sobre las estaciones de tren
• Consultar horarios de salidas y llegadas
• Monitorear las interrupciones del servicio
• Encuentra lugares cercanos y opciones de transporte

La estructura está organizada de la siguiente manera:

• sncf_api/ - El paquete principal para la interacción con la API de SNCF
  • __init__.py - Inicialización del paquete
  • config.py - Ajustes de configuración
  • client.py - Cliente de API base
  • api.py - Interfaz API principal que combina todos los módulos
  • search.py - Puntos finales relacionados con la búsqueda
  • journey.py - Puntos finales de planificación de viajes
  • stations.py - Puntos finales relacionados con la estación
  • networks.py - Puntos finales de red y modo de transporte
  • disruptions.py - Puntos finales relacionados con interrupciones
  • station_finder.py - Búsqueda eficiente de estaciones por coordenadas
  • csv_station_finder.py - Búsqueda de estaciones mediante una base de datos CSV
  • vehicle_journey.py - Información detallada del viaje en tren
• sncf_server.py : implementación del servidor MCP con todos los puntos finales de la herramienta
• train_stations_europe.csv - Base de datos de estaciones de tren europeas con coordenadas

Características

• Planificación inteligente de viajes : planifique viajes entre cualquier ciudad de Francia con selección automática de estaciones
• Detalles completos de la estación : obtenga información detallada sobre las estaciones, incluyendo:
  • Tipos de transporte disponibles (trenes, autobuses, tranvías)
  • Lugares y puntos de interés cercanos
  • Información de coordenadas y accesibilidad
• Horarios en tiempo real : acceda a información actualizada de salidas y llegadas
• Monitoreo de interrupciones : Manténgase informado sobre las interrupciones del servicio
• Búsqueda inteligente de estaciones : localice estaciones por nombre de ciudad, nombre de estación o coordenadas
• Mecanismos de respaldo : las coordenadas codificadas para las principales ciudades garantizan la confiabilidad incluso cuando fallan las búsquedas de API
• Registro detallado : registro completo para depuración y supervisión

Instalación

Prerrequisitos

• Python 3.6+
• pip (administrador de paquetes de Python)

Paso 1: Clonar el repositorio

Paso 2: Instalar dependencias

Si falta el archivo requirements.txt, instale los siguientes paquetes: requests mcp

Obtener una clave API

Antes de utilizar este servidor, debe obtener una clave API de SNCF:

1. Visita el portal API de la SNCF
2. Crea una cuenta o inicia sesión
3. Suscríbete al servicio API de "Navitia"
4. Completar el proceso de registro
5. Una vez aprobado, recibirás tu clave API en el panel de tu cuenta.

La clave API parece una cadena UUID (por ejemplo, 01293485-3NS3-3242-23AZ-3241324512 ).

Configuración

Configuración de Claude Desktop

Para integrar las herramientas MCP de SNCF con Claude Desktop:

1. Instale Claude Desktop si aún no lo ha hecho
2. Abrir la configuración del escritorio de Claude :
   • Vaya a la configuración de Claude Desktop
   • Abra el archivo de configuración (generalmente ubicado en %APPDATA%\Claude\claude_desktop_config.json )

Reemplace path/to/sncf-mcp-new con la ruta real a su directorio de instalación.

3. Guarde el archivo de configuración y reinicie Claude Desktop

Herramientas MCP disponibles

Una vez configurado, las siguientes herramientas estarán disponibles en Claude Desktop:

Planificación de viajes

plan_journey_by_city_names

Planifique un viaje entre dos ciudades de Francia.

Parámetros:

• from_city : Nombre de la ciudad de salida (p. ej., "París")
• to_city : Nombre de la ciudad de destino (p. ej., "Marsella")
• datetime : Hora de salida o llegada opcional (formato: AAAAMMDDTHHMMSS)
• datetime_represents : "salida" o "llegada" (predeterminado: "salida")
• include_station_details : si se debe incluir información detallada de la estación

Ejemplo de mensaje para Claude:

Información de la estación

get_station_details

Obtenga detalles completos sobre las estaciones de tren de una ciudad.

Parámetros:

• city_name : Nombre de la ciudad donde buscar estaciones
• station_name : Nombre de estación específico opcional
• station_id : ID de estación directa opcional
• include_transport_types : Si se debe incluir el análisis del tipo de transporte
• include_nearby_places : Si se debe incluir información de lugares cercanos
• nearby_distance : Radio de búsqueda en metros para lugares cercanos
• nearby_count : Número máximo de lugares cercanos para regresar

Ejemplo de mensaje para Claude:

get_station_schedule

Obtenga los horarios de salida y llegada de una estación.

Parámetros:

• city_name : Nombre de la ciudad donde buscar estaciones
• station_name : Nombre de estación específico opcional
• station_id : ID de estación directa opcional
• count : Número de salidas/llegadas para regresar
• datetime : Fecha y hora opcional desde la que comenzar
• duration : Duración opcional en segundos
• data_freshness : Nivel de frescura de los datos (tiempo real o base_schedule)

Ejemplo de mensaje para Claude:

Monitoreo de interrupciones

check_disruptions

Consulte las interrupciones actuales en la red de transporte de la SNCF.

Parámetros:

• coverage : El área de cobertura (predeterminado: "sncf")
• count : Número máximo de interrupciones para regresar
• station_id : Filtro opcional para una estación específica
• line_id : Filtro opcional para una línea específica
• since : Solo interrupciones válidas después de esta fecha
• until : Solo interrupciones válidas antes de esta fecha
• fetch_train_details : si se deben obtener detalles adicionales sobre los trenes afectados

Ejemplo de mensaje para Claude:

Ejemplos de uso

Planificar un viaje

Puedes pedirle a Claude que planifique un viaje entre dos ciudades de Francia:

Claude utilizará la herramienta plan_journey_by_city_names para:

1. Encuentra las principales estaciones en ambas ciudades
2. Planifique el viaje óptimo entre ellos
3. Presentarle horarios de salida/llegada, duraciones y detalles de conexión.

Obtener información de la estación

Para obtener información detallada sobre una estación:

Claude utilizará la herramienta get_station_details para proporcionar:

1. Información básica de la estación (nombre, ID, coordenadas)
2. Tipos de transporte disponibles (trenes, autobuses, tranvías)
3. Lugares y puntos de interés cercanos

Consulta de horarios de trenes

Para consultar las próximas salidas o llegadas:

Claude usará la herramienta get_station_schedule para mostrar:

1. Próximas salidas desde Burdeos
2. Información de destino
3. Detalles de la plataforma cuando estén disponibles
4. Actualizaciones de estado en tiempo real

Monitoreo de interrupciones

Para comprobar si hay interrupciones del servicio:

Claude utilizará la herramienta check_disruptions para:

1. Encuentra disrupciones relevantes
2. Explicar el impacto en los servicios
3. Proporcionar detalles adicionales sobre los trenes afectados

Solución de problemas

Problemas comunes

"No se proporcionó ninguna clave API"

• Asegúrese de haber agregado su clave API SNCF a la configuración de Claude Desktop
• Compruebe que la variable de entorno esté referenciada correctamente en la configuración del servidor MCP

No se encontraron estaciones para esta ciudad

• Intente utilizar un nombre de ciudad más específico
• Para ciudades más pequeñas, intente usar el nombre de una ciudad más grande cercana.
• El sistema tiene coordenadas codificadas para las principales ciudades francesas, lo que debería funcionar de manera confiable.

"Error al conectar con la API de SNCF"

• Comprueba tu conexión a Internet
• Verifique que su clave API sea válida y no esté vencida
• Es posible que la API de SNCF esté experimentando un tiempo de inactividad; inténtelo de nuevo más tarde

"Error al inicializar el buscador de estaciones CSV"

• Asegúrese de que el archivo train_stations_europe.csv esté en la ubicación correcta
• Verifique los permisos del archivo para asegurarse de que el archivo sea legible

Funciones avanzadas

Coordenadas codificadas

El sistema incluye coordenadas codificadas para las principales ciudades francesas para garantizar la confiabilidad incluso cuando falla la búsqueda API:

• París (48.853, 2.348)
• Marsella (43.303, 5.380)
• Lyon (45.760, 4.860)
• Toulouse (43.611, 1.454)
• Niza (43.704, 7.262)
• Nantes (47.217, -1.542)
• Estrasburgo (48.585, 7.735)
• Burdeos (44.826, -0.556)
• Lille (50.638, 3.072)
• Rennes (48.103, -1.672)
• Grenoble (45.192, 5.716)

Análisis del tipo de transporte

La herramienta get_station_details puede analizar y categorizar los tipos de transporte disponibles en una estación:

• Trenes de larga distancia (TGV, Intercités)
• Trenes regionales (TER)
• Transporte local (autobuses, tranvías, metros)
• Otros servicios (taxis, bicicletas compartidas)

Búsqueda de lugares cercanos

La herramienta de detalles de la estación puede encontrar puntos de interés cerca de una estación:

• Otras paradas de transporte
• Instalaciones públicas
• Puntos de interés
• Puntos de dirección

Esta función es especialmente útil para los viajeros que planean su próximo viaje desde una estación.

Contribuyendo

¡Agradecemos cualquier contribución para mejorar el servidor MCP de la SNCF! No dude en enviar solicitudes de incorporación de cambios o abrir incidencias para solucionar errores y solicitar nuevas funciones.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

• SNCF por proporcionar la API
• El equipo de Navitia por su API integral de transporte público
• Claude AI para capacidades de integración inteligente

Creado por Christian delage ( dr.christian.delage@gmail.com )