REDIS_URL=redis://localhost:6379
OPENAI_API_KEY=sk-your-openai-api-key-here

docker-compose up -d

pnpm install      # Install dependencies
pnpm build        # Compile TypeScript
pnpm start        # Start server
pnpm test         # Run MCP Inspector
pnpm lint         # Check code
pnpm format       # Format code
pnpm check        # Lint & format check
pnpm check:fix    # Auto-fix issues

{
  "mcpServers": {
    "porto-alegre-mcp-server-llm-bus": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

curl -X POST http://localhost:3000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I want to go from UFRGS to the Airport with at most 1 transfer",
    "sessionId": "user-123"
  }'

Para ir da UFRGS ao Aeroporto com no máximo 1 baldeação, o agente irá:

1. Buscar paradas próximas à UFRGS
2. Encontrar rotas que conectam à região do Aeroporto
3. Calcular opções de viagem considerando transferências
4. Apresentar as melhores rotas com tempos estimados

O resultado incluirá:
- Opções de rotas com detalhes de paradas
- Tempos estimados de viagem
- Informações sobre transferências necessárias
- Distância de caminhada até as paradas

sequenceDiagram
    participant U as User
    participant C as Claude Desktop
    participant A as Agent
    participant N as NLP Processor
    participant PS as ProximitySearch
    participant RP as RoutePlanning
    participant T as MCP Tools
    participant API as PoA API
    participant R as Redis
    
    U->>+C: "Quero ir da UFRGS ao Aeroporto"
    C->>+A: Process Query
    
    A->>+N: Extract Intent & Entities
    N->>N: Identify: origin="UFRGS", destination="Aeroporto"
    N-->>-A: Parsed Data
    
    A->>+T: Get stops data
    T->>+R: Check Cache
    alt Cache Hit
        R-->>T: Cached Stops
    else Cache Miss
        T->>+API: Fetch Stops
        API-->>-T: Stops Data
        T->>R: Cache Data
    end
    T-->>-A: All Stops Data
    
    A->>+PS: Find stops near UFRGS & Airport
    PS-->>-A: Nearby stops for both locations
    
    A->>+RP: Plan routes with transfers
    RP->>RP: Calculate: transfers, time, walking distance
    RP-->>-A: Ranked route options
    
    A-->>-C: Formatted Response with Routes
    C-->>-U: Route Options with Details
    
    Note over U,R: Now uses ProximitySearchService<br/>and RoutePlanningService

graph LR
    A[Raw Query] --> B[Intent Classification]
    B --> C[Entity Extraction]
    C --> D[Context Enrichment]
    D --> E[Action Planning]
    
    E --> F{Tool Selection}
    F -->|Geographic| G[stops-fetcher]
    F -->|Route Info| H[routes-fetcher] 
    F -->|Details| I[route-details-fetcher]
    
    G --> J[Cache Layer]
    H --> J
    I --> J
    
    J --> K[Response Validation]
    K --> L[Memory Update]
    L --> M[Response Generation]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:2px,color:#000
    style M fill:#66bb6a,stroke:#2e7d32,stroke-width:3px,color:#fff
    style J fill:#f06292,stroke:#c2185b,stroke-width:2px,color:#fff
    style F fill:#9575cd,stroke:#512da8,stroke-width:2px,color:#fff
    style E fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000

O agente irá:

1. Buscar todas as paradas de ônibus disponíveis
2. Filtrar paradas próximas ao Parque Farroupilha (até 300m)
3. Verificar quais rotas dessas paradas conectam ao Centro
4. Apresentar resultados organizados por distância

O resultado incluirá:
- Lista de paradas próximas com localização
- Rotas disponíveis de cada parada
- Distância da parada até o parque
- Informações de tempo de viagem estimado

O agente irá:

1. Identificar a rota solicitada pelo usuário
2. Buscar informações detalhadas da rota
3. Obter sequência de paradas e coordenadas
4. Compilar informações de horários e características

O resultado incluirá:
- Pontos de origem e destino da rota
- Lista completa de paradas na sequência
- Coordenadas do trajeto
- Informações básicas da rota

graph TB
    A[User Query] --> B[NLP Processor]
    B --> C{Query Type?}
    
    C -->|Route Planning| D[Route Planner]
    C -->|Stop Search| E[Stop Finder] 
    C -->|Semantic Search| F[Semantic Search]
    C -->|General Info| G[Info Retriever]
    
    D --> H[MCP Tools Layer]
    E --> H
    F --> H
    G --> H
    
    H --> I[stops-fetcher]
    H --> J[routes-fetcher]
    H --> K[route-details-fetcher]
    
    I --> L[PoA Transport API]
    J --> L
    K --> L
    
    L --> M[Redis Cache]
    M --> N[Basic Validation]
    N --> O[Memory Update]
    O --> P[Agent Response]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:3px,color:#000
    style P fill:#66bb6a,stroke:#2e7d32,stroke-width:3px,color:#fff
    style L fill:#ffb74d,stroke:#f57c00,stroke-width:2px,color:#000
    style M fill:#f06292,stroke:#c2185b,stroke-width:2px,color:#fff
    style C fill:#9575cd,stroke:#512da8,stroke-width:2px,color:#fff
    style H fill:#81c784,stroke:#388e3c,stroke-width:2px,color:#000

flowchart TD
    A[Incoming Message] --> B[NLP Processing]
    B --> C[Extract Intent & Entities]
    C --> D[Load Memory Context]
    
    D --> E{Planning Loop}
    E --> F[Planner Decision]
    F --> G[Select MCP Tool]
    G --> H[Execute Tool Call]
    
    H --> I[Validate Response]
    I --> J{Valid?}
    J -->|No| K[Fallback Strategy]
    J -->|Yes| L[Update Memory]
    
    K --> F
    L --> M{Goal Satisfied?}
    M -->|No| F
    M -->|Yes| N[Generate Response]
    
    N --> O[Final Output]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:2px,color:#000
    style E fill:#ffeb3b,stroke:#f57f17,stroke-width:2px,color:#000
    style I fill:#ba68c8,stroke:#7b1fa2,stroke-width:2px,color:#fff
    style M fill:#66bb6a,stroke:#2e7d32,stroke-width:2px,color:#fff
    style O fill:#4caf50,stroke:#1b5e20,stroke-width:3px,color:#fff
    style J fill:#ff7043,stroke:#d84315,stroke-width:2px,color:#fff

sequenceDiagram
    participant C as Claude Desktop
    participant M as MCP Server
    participant A as Agent
    participant P as PoA API
    participant R as Redis
    
    C->>+M: Tool Call Request
    M->>+A: Process with LLM Agent
    A->>A: NLP + Planning
    
    loop Planning Steps (max 3)
        A->>+M: MCP Tool Call
        M->>+R: Check Cache
        alt Cache Hit
            R-->>-M: Cached Data
        else Cache Miss
            M->>+P: API Request
            P-->>-M: Response Data
            M->>R: Update Cache
        end
        M-->>-A: Tool Response
        A->>A: Validate & Plan Next
    end
    
    A-->>-M: Final Response
    M-->>-C: Structured Result
    
    Note over C,R: Enhanced with proximity search,<br/>route planning, and semantic search

// planner decides next action (MCP tool) based on user's goal
while (!done && steps < 3) {
  const plan = planner.decide(goal, memory, lastResult);
  const result = callMCPTool(plan.tool, plan.args); // stops/routes/route-details
  const ok = validator.check(result);               // types, ranges, fields
  if (!ok) { fallbackOrFix(); }
  updateMemory(result);
  done = planner.isSatisfied(result, goal);
}

erDiagram
    Route {
        string id
        string code
        string name
    }
    
    Stop {
        string code
        string terminal
        string latitude
        string longitude
        array routes
    }
    
    RouteDetails {
        string id
        string code
        string name
        array coordinates
    }
    
    Route ||--o{ Stop : serves
    Route ||--|| RouteDetails : details

interface Memory {
  conversation: Array<{
    role: "user" | "assistant";
    content: string;
    timestamp: Date;
  }>;
  lastResults: Array<{
    tool: MCPTool;
    args: Record<string, any>;
    result: any;
  }>;
  userPreferences: {
    maxTransfers?: number;
    accessibilityNeeds?: boolean;
  };
}

graph TB
    A[Client Request] --> B[Process Request]
    B --> C{Cache Available?}
    C -->|Yes| D[Return Cached]
    C -->|No| E[Call PoA API]
    
    E --> F{API Success?}
    F -->|Yes| G[Cache & Return]
    F -->|No| H[Return Error]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:2px,color:#000
    style G fill:#66bb6a,stroke:#2e7d32,stroke-width:2px,color:#fff
    style H fill:#f44336,stroke:#c62828,stroke-width:2px,color:#fff
    style C fill:#9575cd,stroke:#512da8,stroke-width:2px,color:#fff
    style F fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#fff

flowchart TD
    A[API Request] --> B{PoA API}
    B -->|Success| C[Return Data]
    B -->|Timeout/Error| D{Cache Available?}
    
    D -->|Yes| E[Return Cached Data + Warning]
    D -->|No| F[Return Graceful Error]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:2px,color:#000
    style C fill:#66bb6a,stroke:#2e7d32,stroke-width:2px,color:#fff
    style E fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#fff
    style F fill:#f44336,stroke:#c62828,stroke-width:2px,color:#fff
    style B fill:#9575cd,stroke:#512da8,stroke-width:2px,color:#fff
    style D fill:#81c784,stroke:#388e3c,stroke-width:2px,color:#000

graph LR
    A[API Response] --> B[Basic Validation]
    B --> C{Valid Data?}
    
    C -->|Yes| D[Accept & Process]
    C -->|No| E[Log Warning & Continue]
    
    style A fill:#4fc3f7,stroke:#0277bd,stroke-width:2px,color:#000
    style D fill:#66bb6a,stroke:#2e7d32,stroke-width:2px,color:#fff
    style E fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#fff
    style C fill:#9575cd,stroke:#512da8,stroke-width:2px,color:#fff
    style B fill:#81c784,stroke:#388e3c,stroke-width:2px,color:#000

graph TB
    A[Health Endpoint] --> B{System Check}
    B --> C[Redis Status]
    B --> D[Basic Connectivity]
    
    C --> E{Connected?}
    D --> F{API Reachable?}
    
    E -->|Yes| G[✅ Healthy]
    E -->|No| H[⚠️ Cache Issues]
    
    F -->|Yes| G
    F -->|No| I[⚠️ API Issues]
    
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000
    style G fill:#4caf50,stroke:#2e7d32,stroke-width:2px,color:#fff
    style H fill:#ff9800,stroke:#f57c00,stroke-width:2px,color:#fff
    style I fill:#f44336,stroke:#c62828,stroke-width:2px,color:#fff
    style B fill:#2196f3,stroke:#1565c0,stroke-width:2px,color:#fff

// Simple metrics tracking
interface BasicMetrics {
  requestCount: number;
  errorCount: number;
  cacheHits: number;
  cacheMisses: number;
  lastResponse: Date;
}

// POST /agent/chat
interface ChatRequest {
  message: string;           // Natural language query
  sessionId: string;         // User session identifier
  preferences?: {            // Optional user preferences
    maxTransfers: number;
    walkingDistance: number;
    accessibilityNeeds: boolean;
  };
  context?: {                // Optional context
    currentLocation?: Location;
    previousSearches?: string[];
  };
}

interface ChatResponse {
  response: string;          // Natural language response
  confidence: number;        // 0-1 confidence score
  metadata: {
    processingTime: number;  // ms
    toolsUsed: string[];     // MCP tools called
    cacheHits: number;       // Cache efficiency
    fallbacksTriggered: boolean;
  };
  data?: {                   // Structured data if applicable
    routes?: Route[];
    stops?: Stop[];
    alerts?: Alert[];
  };
}

interface StopsResponse {
  stops: Stop[];
  pagination: {
    cursor: string | null;
    hasMore: boolean;
    total: number;
  };
  metadata: {
    source: 'cache' | 'api';
    freshness: number;       // minutes since fetch
  };
}