parcoursmob/servers/mcp/README.md

# 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:

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

Or via environment variables:
```bash
export SERVER_MCP_ENABLED=true
export SERVER_MCP_LISTEN="0.0.0.0:8081"
```

## API Endpoints

### Initialize
```http
POST /mcp/v1/initialize
```

Returns server capabilities and protocol version.

### List Tools
```http
GET /mcp/v1/tools/list
```

Returns available MCP tools.

### Call Tool
```http
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
```http
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:**
```bash
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:**
```json
{
  "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:
```json
{
  "mcpServers": {
    "parcoursmob": {
      "url": "http://localhost:8081/mcp/v1"
    }
  }
}
```

## Development

### Testing

Test the health endpoint:
```bash
curl http://localhost:8081/health
```

List available tools:
```bash
curl http://localhost:8081/mcp/v1/tools/list
```

Test journey search:
```bash
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`:
```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:
```go
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