# userharun/metro-mcp architecture

> Architecture diagram of the GitHub repository userharun/metro-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/userharun/metro-mcp
- Repository: https://github.com/userharun/metro-mcp

## Overview

Houston METRO MCP provides transit lookups through a locally launched stdio MCP server: an AI client invokes tools, the server delegates to a local provider, and results come from cached static GTFS data or live METRO feeds. The repository also includes a browser showcase backed by a Worker API and D1 catalog. The README documents MCP tools and resources; sampled source verifies the local provider and several Worker, web, and core relationships. Unsampled MCP dispatch details are not expanded.

Main entry points: [`packages/local/src/provider.ts`](https://github.com/userharun/metro-mcp/blob/main/packages/local/src/provider.ts) (Local Provider), [`packages/core/src/metro-client.ts`](https://github.com/userharun/metro-mcp/blob/main/packages/core/src/metro-client.ts) (Live Client), [`apps/cli/src/index.ts`](https://github.com/userharun/metro-mcp/blob/main/apps/cli/src/index.ts) (CLI Entry), [`packages/local/src/catalog.ts`](https://github.com/userharun/metro-mcp/blob/main/packages/local/src/catalog.ts) (GTFS Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local MCP"]
  node_cli["CLI Entry<br/>[index.ts]"]
  node_mcp["MCP Tools<br/>[index.ts]"]
  node_local_provider["Local Provider<br/>[provider.ts]"]
end

subgraph group_data["Transit Data"]
  node_local_catalog["GTFS Catalog<br/>[catalog.ts]"]
  node_cache[("Local Cache")]
  node_live_client["Live Client<br/>[metro-client.ts]"]
  node_arrivals["Arrival Parsing<br/>[arrivals.ts]"]
  node_alerts["Alert Parsing<br/>[alerts.ts]"]
  node_schemas["Data Contracts<br/>[schemas.ts]"]
end

subgraph group_worker["Worker API"]
  node_worker["Worker Routes<br/>[api.ts]"]
  node_worker_provider["Worker Provider<br/>[provider.ts]"]
  node_worker_catalog["D1 Catalog<br/>[catalog.ts]"]
  node_d1[("D1 Database")]
end

subgraph group_web["Web Showcase"]
  node_web["Showcase UI<br/>[App.tsx]"]
  node_showcase["Transit Demo<br/>[Showcase.tsx]"]
  node_web_api["Web API Client<br/>[api.ts]"]
  node_saved["Saved Routes<br/>[saved-routes.ts]"]
end

node_client(("AI Client"))
node_metro["METRO Feeds"]
node_worker_user(("Web Visitor"))

node_client -->|"launches"| node_cli
node_cli -->|"starts server"| node_mcp
node_cli -->|"creates provider"| node_local_provider
node_mcp -.->|"uses provider"| node_local_provider
node_local_provider -->|"delegates catalog"| node_local_catalog
node_local_catalog -->|"reads and writes"| node_cache
node_local_catalog -->|"downloads GTFS"| node_metro
node_local_provider -->|"creates client"| node_live_client
node_live_client -->|"fetches feeds"| node_metro
node_local_provider -->|"normalizes arrivals"| node_arrivals
node_local_provider -->|"normalizes alerts"| node_alerts
node_arrivals -->|"requests updates"| node_live_client
node_alerts -->|"requests alerts"| node_live_client
node_worker_user -.->|"visits"| node_web
node_web -->|"renders"| node_showcase
node_showcase -->|"requests data"| node_web_api
node_showcase -->|"uses saved routes"| node_saved
node_web_api -->|"fetches API"| node_worker
node_worker -->|"dispatches requests"| node_worker_provider
node_worker_provider -->|"queries catalog"| node_worker_catalog
node_worker_catalog -->|"queries"| node_d1

click node_cli "https://github.com/userharun/metro-mcp/blob/main/apps/cli/src/index.ts"
click node_mcp "https://github.com/userharun/metro-mcp/blob/main/packages/mcp/src/index.ts"
click node_local_provider "https://github.com/userharun/metro-mcp/blob/main/packages/local/src/provider.ts"
click node_local_catalog "https://github.com/userharun/metro-mcp/blob/main/packages/local/src/catalog.ts"
click node_live_client "https://github.com/userharun/metro-mcp/blob/main/packages/core/src/metro-client.ts"
click node_arrivals "https://github.com/userharun/metro-mcp/blob/main/packages/core/src/arrivals.ts"
click node_alerts "https://github.com/userharun/metro-mcp/blob/main/packages/core/src/alerts.ts"
click node_schemas "https://github.com/userharun/metro-mcp/blob/main/packages/core/src/schemas.ts"
click node_worker "https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/api.ts"
click node_worker_provider "https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/provider.ts"
click node_worker_catalog "https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/catalog.ts"
click node_web "https://github.com/userharun/metro-mcp/blob/main/apps/web/src/App.tsx"
click node_showcase "https://github.com/userharun/metro-mcp/blob/main/apps/web/src/Showcase.tsx"
click node_web_api "https://github.com/userharun/metro-mcp/blob/main/apps/web/src/api.ts"
click node_saved "https://github.com/userharun/metro-mcp/blob/main/apps/web/src/saved-routes.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_mcp,node_local_provider,node_client toneBlue
class node_local_catalog,node_cache,node_live_client,node_arrivals,node_alerts,node_schemas toneAmber
class node_worker,node_worker_provider,node_worker_catalog,node_d1 toneMint
class node_web,node_showcase,node_web_api,node_saved toneRose
class node_metro,node_worker_user toneIndigo
```

## Components

### Local MCP

- [CLI Entry](https://github.com/userharun/metro-mcp/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [MCP Tools](https://github.com/userharun/metro-mcp/blob/main/packages/mcp/src/index.ts): `packages/mcp/src/index.ts`
- [Local Provider](https://github.com/userharun/metro-mcp/blob/main/packages/local/src/provider.ts): `packages/local/src/provider.ts`

### Transit Data

- [GTFS Catalog](https://github.com/userharun/metro-mcp/blob/main/packages/local/src/catalog.ts): `packages/local/src/catalog.ts`
- **Local Cache**
- [Live Client](https://github.com/userharun/metro-mcp/blob/main/packages/core/src/metro-client.ts): `packages/core/src/metro-client.ts`
- [Arrival Parsing](https://github.com/userharun/metro-mcp/blob/main/packages/core/src/arrivals.ts): `packages/core/src/arrivals.ts`
- [Alert Parsing](https://github.com/userharun/metro-mcp/blob/main/packages/core/src/alerts.ts): `packages/core/src/alerts.ts`
- [Data Contracts](https://github.com/userharun/metro-mcp/blob/main/packages/core/src/schemas.ts): `packages/core/src/schemas.ts`

### Worker API

- [Worker Routes](https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/api.ts): `apps/worker/src/api.ts`
- [Worker Provider](https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/provider.ts): `apps/worker/src/provider.ts`
- [D1 Catalog](https://github.com/userharun/metro-mcp/blob/main/apps/worker/src/catalog.ts): `apps/worker/src/catalog.ts`
- **D1 Database**

### Web Showcase

- [Showcase UI](https://github.com/userharun/metro-mcp/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Transit Demo](https://github.com/userharun/metro-mcp/blob/main/apps/web/src/Showcase.tsx): `apps/web/src/Showcase.tsx`
- [Web API Client](https://github.com/userharun/metro-mcp/blob/main/apps/web/src/api.ts): `apps/web/src/api.ts`
- [Saved Routes](https://github.com/userharun/metro-mcp/blob/main/apps/web/src/saved-routes.ts): `apps/web/src/saved-routes.ts`

### Other components

- **AI Client**
- **METRO Feeds**
- **Web Visitor**

## Connections

- AI Client → CLI Entry: launches (evidence: `README.md`)
- CLI Entry → MCP Tools: starts server (evidence: `apps/cli/src/index.ts`)
- CLI Entry → Local Provider: creates provider (evidence: `apps/cli/src/index.ts`)
- MCP Tools → Local Provider: uses provider
- Local Provider → GTFS Catalog: delegates catalog (evidence: `packages/local/src/provider.ts`)
- GTFS Catalog → Local Cache: reads and writes (evidence: `packages/local/src/catalog.ts`)
- GTFS Catalog → METRO Feeds: downloads GTFS (evidence: `packages/local/src/catalog.ts`)
- Local Provider → Live Client: creates client (evidence: `packages/local/src/provider.ts`)
- Live Client → METRO Feeds: fetches feeds (evidence: `packages/core/src/metro-client.ts`)
- Local Provider → Arrival Parsing: normalizes arrivals (evidence: `packages/local/src/provider.ts`)
- Local Provider → Alert Parsing: normalizes alerts (evidence: `packages/local/src/provider.ts`)
- Arrival Parsing → Live Client: requests updates (evidence: `packages/core/src/arrivals.ts`)
- Alert Parsing → Live Client: requests alerts (evidence: `packages/core/src/alerts.ts`)
- Web Visitor → Showcase UI: visits
- Showcase UI → Transit Demo: renders (evidence: `apps/web/src/App.tsx`)
- Transit Demo → Web API Client: requests data (evidence: `apps/web/src/Showcase.tsx`)
- Transit Demo → Saved Routes: uses saved routes (evidence: `apps/web/src/Showcase.tsx`)
- Web API Client → Worker Routes: fetches API (evidence: `apps/web/src/api.ts`)
- Worker Routes → Worker Provider: dispatches requests (evidence: `apps/worker/src/index.ts`)
- Worker Provider → D1 Catalog: queries catalog (evidence: `apps/worker/src/provider.ts`)
- D1 Catalog → D1 Database: queries (evidence: `apps/worker/src/catalog.ts`)