5.0 KiB

Raw Blame History

MCP Server for PARCOURSMOB

This package implements a Model Context Protocol (MCP) HTTP server for the PARCOURSMOB application, exposing journey search functionality as an MCP tool.

Overview

The MCP server provides a standardized interface for AI assistants to search for multimodal journeys, including:

Public transit routes
Carpooling solutions (via operators like Mobicoop)
Solidarity transport
Organized carpools
Fleet vehicles
Local knowledge base solutions

Configuration

Enable the MCP server in your config file:

server:
  mcp:
    enabled: true
    listen: "0.0.0.0:8081"

Or via environment variables:

export SERVER_MCP_ENABLED=true
export SERVER_MCP_LISTEN="0.0.0.0:8081"

API Endpoints

Initialize

POST /mcp/v1/initialize

Returns server capabilities and protocol version.

List Tools

GET /mcp/v1/tools/list

Returns available MCP tools.

Call Tool

POST /mcp/v1/tools/call
Content-Type: application/json

{
  "name": "search_journeys",
  "arguments": {
    "departure": "123 Main St, Paris, France",
    "destination": "456 Oak Ave, Lyon, France",
    "departure_date": "2025-01-20",
    "departure_time": "14:30"
  }
}

Health Check

GET /health

Available Tools

search_journeys

Searches for multimodal journey options between two locations.

Parameters:

departure (string, required): Departure address as text
destination (string, required): Destination address as text
departure_date (string, required): Date in YYYY-MM-DD format
departure_time (string, required): Time in HH:MM format (24-hour)
passenger_id (string, optional): Passenger ID to retrieve address from account
exclude_driver_ids (array, optional): List of driver IDs to exclude from solidarity transport results

Example Request:

curl -X POST http://localhost:8081/mcp/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_journeys",
    "arguments": {
      "departure": "Gare de Lyon, Paris",
      "destination": "Part-Dieu, Lyon",
      "departure_date": "2025-01-20",
      "departure_time": "09:00"
    }
  }'

Response Format:

{
  "search_parameters": {
    "departure": {
      "label": "Gare de Lyon, Paris, France",
      "coordinates": { "type": "Point", "coordinates": [2.3736, 48.8443] }
    },
    "destination": {
      "label": "Part-Dieu, Lyon, France",
      "coordinates": { "type": "Point", "coordinates": [4.8575, 45.7605] }
    },
    "departure_date": "2025-01-20",
    "departure_time": "09:00"
  },
  "results": {
    "CarpoolResults": [...],
    "TransitResults": [...],
    "VehicleResults": [...],
    "DriverJourneys": [...],
    "OrganizedCarpools": [...],
    "KnowledgeBaseResults": [...]
  }
}

Architecture

Package Structure

mcp.go: HTTP server and request routing
tools.go: Tool registration and execution
journey_search.go: Journey search tool implementation

Flow

HTTP request received at MCP endpoint
Tool name and arguments extracted
Addresses geocoded using Pelias geocoding service
Journey search executed via ApplicationHandler
Results formatted and returned as JSON

Dependencies

The MCP server uses:

Pelias geocoding service (configured via geo.pelias.url)
ApplicationHandler for journey search business logic
All backend services (GRPC): solidarity transport, carpool service, transit routing, fleets, etc.

Integration with AI Assistants

The MCP server follows the Model Context Protocol specification, making it compatible with AI assistants that support MCP, such as Claude Desktop or other MCP-enabled tools.

Example Claude Desktop configuration:

{
  "mcpServers": {
    "parcoursmob": {
      "url": "http://localhost:8081/mcp/v1"
    }
  }
}

Development

Testing

Test the health endpoint:

curl http://localhost:8081/health

List available tools:

curl http://localhost:8081/mcp/v1/tools/list

Test journey search:

curl -X POST http://localhost:8081/mcp/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_journeys",
    "arguments": {
      "departure": "Paris",
      "destination": "Lyon",
      "departure_date": "2025-01-20",
      "departure_time": "10:00"
    }
  }'

Adding New Tools

To add a new MCP tool:

Define the tool in tools.go:

func (h *ToolsHandler) registerNewTool() {
    tool := &Tool{
        Name:        "tool_name",
        Description: "Tool description",
        InputSchema: map[string]any{...},
    }
    h.tools["tool_name"] = tool
}

Implement the handler:

func (h *ToolsHandler) handleNewTool(ctx context.Context, arguments map[string]any) (any, error) {
    // Implementation
}

Add to CallTool switch statement in tools.go

Notes

All times are handled in Europe/Paris timezone
Geocoding uses the first result from Pelias
Journey search runs multiple transport mode queries in parallel
Results include all available transport options for the requested route

5.0 KiB Raw Blame History