@daanrongen/tfl-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +138 -0
  2. package/build/index.js +22385 -0
  3. package/build/index.js.map +171 -0
  4. package/package.json +32 -0
package/README.md ADDED
@@ -0,0 +1,138 @@
1
+ # TfL MCP Server
2
+
3
+ A state-of-the-art [Model Context Protocol](https://modelcontextprotocol.io/) server for the [Transport for London Unified API](https://api.tfl.gov.uk/), covering all 14 API domains and 87 endpoints.
4
+
5
+ ## Tools (80 total)
6
+
7
+ | Domain | Tools | Coverage |
8
+ | ----------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
9
+ | **AccidentStats** | `tfl_accident_stats` | Road accidents by year |
10
+ | **AirQuality** | `tfl_air_quality` | Live pollution forecasts (NO2, O3, PM10, PM2.5, SO2) |
11
+ | **BikePoint** | `tfl_bike_points_all`, `tfl_bike_point_search`, `tfl_bike_point_by_id` | Santander Cycles availability |
12
+ | **Cabwise** | `tfl_cabwise_search` | Licensed taxis & minicabs near a location |
13
+ | **Journey** | `tfl_journey_plan`, `tfl_journey_modes` | Full journey planner (all modes) |
14
+ | **Line** | 14 tools | Status, routes, disruptions, arrivals, timetables, stop sequences |
15
+ | **Mode** | `tfl_mode_active_service_types`, `tfl_mode_arrivals` | Cross-mode service info |
16
+ | **Occupancy** | 5 tools | Car parks, bike docks, EV charge connectors |
17
+ | **Place** | 7 tools | Search, geo lookup, postcode streets, place types |
18
+ | **Road** | 8 tools | TLRN status, disruptions, closures, roadworks |
19
+ | **Search** | 5 tools | Full-text TfL site/data search |
20
+ | **StopPoint** | 17 tools | Search, arrivals, disruptions, crowding, routes, taxi ranks, car parks |
21
+ | **Vehicle** | 3 tools | ULEZ compliance, emissions surcharge, vehicle arrival tracking |
22
+
23
+ ## Setup
24
+
25
+ ### 1. Install Bun
26
+
27
+ ```bash
28
+ curl -fsSL https://bun.sh/install | bash
29
+ ```
30
+
31
+ ### 2. Install dependencies
32
+
33
+ ```bash
34
+ bun install
35
+ ```
36
+
37
+ ### 3. Build
38
+
39
+ ```bash
40
+ bun run build
41
+ ```
42
+
43
+ ### 4. Get a TfL API key (free)
44
+
45
+ Register at [https://api-portal.tfl.gov.uk/](https://api-portal.tfl.gov.uk/). Without a key, requests are rate-limited to ~500/day.
46
+
47
+ ### 5. Configure Claude Desktop
48
+
49
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
50
+
51
+ ```json
52
+ {
53
+ "mcpServers": {
54
+ "tfl": {
55
+ "command": "bun",
56
+ "args": ["run", "/ABSOLUTE/PATH/TO/tfl-mcp/src/index.ts"],
57
+ "env": {
58
+ "TFL_API_KEY": "your_api_key_here"
59
+ }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Or using the compiled build (faster startup):
66
+
67
+ ```json
68
+ {
69
+ "mcpServers": {
70
+ "tfl": {
71
+ "command": "bun",
72
+ "args": ["/ABSOLUTE/PATH/TO/tfl-mcp/build/index.js"],
73
+ "env": {
74
+ "TFL_API_KEY": "your_api_key_here"
75
+ }
76
+ }
77
+ }
78
+ }
79
+ ```
80
+
81
+ ## Development
82
+
83
+ ```bash
84
+ bun run dev # run with --watch (hot reload)
85
+ bun run start:dev # run src/index.ts directly
86
+ bun test # run test suite
87
+ bun test --watch # run tests in watch mode
88
+ ```
89
+
90
+ ## Journey planner — location IDs
91
+
92
+ The most common failure mode is passing a free-text name to `tfl_journey_plan`, which causes TfL to return a 300 disambiguation response. The tool handles this gracefully and returns suggested `parameterValue` IDs to use on retry.
93
+
94
+ **Preferred ID formats (most to least reliable):**
95
+
96
+ | Format | Example | Notes |
97
+ | ----------- | ----------------- | ------------------------------------------------------ |
98
+ | ICS code | `1000129` | Most reliable — use output from `tfl_stoppoint_search` |
99
+ | Naptan ID | `940GZZLUVIC` | Reliable for tube/rail stations |
100
+ | Postcode | `N1C4TB` | Always resolves unambiguously |
101
+ | Coordinates | `51.5308,-0.1238` | Always unambiguous |
102
+ | Free text | `King's Cross` | May trigger disambiguation |
103
+
104
+ **Common station ICS codes:**
105
+
106
+ | Station | ICS code |
107
+ | ------------------------ | --------- |
108
+ | King's Cross St. Pancras | `1000129` |
109
+ | Victoria | `1000248` |
110
+ | Waterloo | `1000254` |
111
+ | London Bridge | `1000135` |
112
+ | Paddington | `1000184` |
113
+ | Liverpool Street | `1000134` |
114
+ | Euston | `1000078` |
115
+ | Canary Wharf | `1001006` |
116
+ | Brixton | `1000023` |
117
+ | Stratford | `1000222` |
118
+
119
+ ## Architecture
120
+
121
+ ```
122
+ src/
123
+ ├── index.ts # Entry point — wires all modules into one MCP server
124
+ ├── client.ts # Shared HTTP client — API key injection, 300 disambiguation handling
125
+ ├── accident.ts # AccidentStats domain
126
+ ├── air-quality.ts # AirQuality domain
127
+ ├── bike-point.ts # BikePoint domain
128
+ ├── cabwise.ts # Cabwise domain
129
+ ├── journey.ts # Journey domain — disambiguation-aware
130
+ ├── line.ts # Line domain (14 tools)
131
+ ├── mode.ts # Mode domain
132
+ ├── occupancy.ts # Occupancy domain
133
+ ├── place.ts # Place domain
134
+ ├── road.ts # Road domain
135
+ ├── search.ts # Search domain
136
+ ├── stop-point.ts # StopPoint domain (17 tools)
137
+ └── vehicle.ts # Vehicle domain
138
+ ```