parcoursmob/servers/mcp

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

1. HTTP request received at MCP endpoint
2. Tool name and arguments extracted
3. Addresses geocoded using Pelias geocoding service
4. Journey search executed via ApplicationHandler
5. 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:

1. 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
}

2. Implement the handler:

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

3. 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