# joooook/12306-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/joooook/12306-mcp
- Repository: https://github.com/joooook/12306-mcp

## Overview

12306-mcp exposes 12306 ticket-search capabilities as MCP tools and a station-data resource, over stdio or HTTP. The main workflow is an MCP client request routed to a search tool, which resolves station codes, queries 12306 and returns formatted/filtered results; the README also documents filtering, route-stop queries and transfer searches. Most runtime behavior is concentrated in src/index.ts, so several distinct responsibilities share that path. The excerpt shows only selected implementation sections; documented but unsampled features are represented without guessing their internal calls.

Main entry points: [`src/index.ts`](https://github.com/joooook/12306-mcp/blob/main/src/index.ts) (Search tools), [`src/types.ts`](https://github.com/joooook/12306-mcp/blob/main/src/types.ts) (Ticket models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["MCP access"]
  node_stdio["stdio transport<br/>[index.ts]"]
  node_http["HTTP transport<br/>[index.ts]"]
  node_mcp["MCP server<br/>[index.ts]"]
end

subgraph group_search["Ticket search"]
  node_tools["Search tools<br/>[index.ts]"]
  node_date["Date utility<br/>[index.ts]"]
  node_ticket["Ticket search<br/>[index.ts]"]
  node_filter["Result filtering<br/>[index.ts]"]
  node_transfer["Transfer search<br/>[index.ts]"]
  node_stops["Route-stop query<br/>[index.ts]"]
end

subgraph group_domain["Rail data"]
  node_station["Station data<br/>[index.ts]"]
  node_tickettypes["Ticket models<br/>[types.ts]"]
end

subgraph group_integration["12306 integration"]
  node_rail["12306 services"]
end

node_client(("MCP client"))

node_client -->|"uses"| node_stdio
node_client -->|"uses"| node_http
node_stdio -->|"connects"| node_mcp
node_http -->|"starts server"| node_mcp
node_mcp -->|"registers"| node_tools
node_tools -->|"provides"| node_date
node_tools -->|"provides"| node_ticket
node_tools -->|"provides"| node_transfer
node_tools -->|"provides"| node_stops
node_ticket -->|"resolves stations"| node_station
node_ticket -->|"queries"| node_rail
node_ticket -->|"filters results"| node_filter
node_transfer -->|"queries"| node_rail
node_transfer -->|"filters results"| node_filter
node_ticket -->|"uses models"| node_tickettypes
node_transfer -->|"uses models"| node_tickettypes
node_station -.->|"loads data"| node_rail

click node_stdio "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_http "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_mcp "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_tools "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_date "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_ticket "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_filter "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_transfer "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_stops "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_station "https://github.com/joooook/12306-mcp/blob/main/src/index.ts"
click node_tickettypes "https://github.com/joooook/12306-mcp/blob/main/src/types.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_stdio,node_http,node_mcp,node_client toneBlue
class node_tools,node_date,node_ticket,node_filter,node_transfer,node_stops toneAmber
class node_station,node_tickettypes toneMint
class node_rail toneRose
```

## Components

### MCP access

- [stdio transport](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [HTTP transport](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [MCP server](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`

### Ticket search

- [Search tools](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Date utility](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Ticket search](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Result filtering](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Transfer search](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Route-stop query](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`

### Rail data

- [Station data](https://github.com/joooook/12306-mcp/blob/main/src/index.ts): `src/index.ts`
- [Ticket models](https://github.com/joooook/12306-mcp/blob/main/src/types.ts): `src/types.ts`

### 12306 integration

- **12306 services**

### Other components

- **MCP client**

## Connections

- MCP client → stdio transport: uses (evidence: `README.md`)
- MCP client → HTTP transport: uses (evidence: `README.md`)
- stdio transport → MCP server: connects (evidence: `src/index.ts`)
- HTTP transport → MCP server: starts server (evidence: `src/index.ts`)
- MCP server → Search tools: registers (evidence: `src/index.ts`)
- Search tools → Date utility: provides (evidence: `src/index.ts`)
- Search tools → Ticket search: provides (evidence: `README.md`)
- Search tools → Transfer search: provides (evidence: `README.md`)
- Search tools → Route-stop query: provides (evidence: `README.md`)
- Ticket search → Station data: resolves stations (evidence: `src/index.ts`)
- Ticket search → 12306 services: queries (evidence: `src/index.ts`)
- Ticket search → Result filtering: filters results (evidence: `src/index.ts`)
- Transfer search → 12306 services: queries (evidence: `src/index.ts`)
- Transfer search → Result filtering: filters results (evidence: `src/index.ts`)
- Ticket search → Ticket models: uses models (evidence: `src/index.ts`)
- Transfer search → Ticket models: uses models (evidence: `src/index.ts`)
- Station data → 12306 services: loads data
