TMB总线到达时间MCP服务器
一种模型上下文协议（MCP）服务器，为TMB（巴塞罗那大都市交通）公交车站提供实时公交车到达信息。
🚀 特性
- 实时巴士到达：获取有关公共汽车何时到达的最新信息
- 多线支持：查看停靠站的所有公交线路
- 时间（分钟）：到达时间以分钟为单位，便于理解
- 详细信息：线路号、目的地、方向和公交车ID
- 符合MCP标准：适用于任何MCP客户端，包括Claude Desktop
📋 先决条件
- Node.js 18+
- npm或纱线
- TMB API证书（请访问https://developer.tmb.cat/)
🔧 安装
- 克隆或创建项目：
mkdir tmb-bus-mcp
cd tmb-bus-mcp- 安装依赖项：
npm install- 设置您的TMB API凭据：
# Copy the example environment file
cp .env.example .env
# Edit .env and add your credentials
# TMB_APP_ID=your_app_id
# TMB_APP_KEY=your_app_key- 构建项目：
npm run build🎯 用法
选项1：使用客户端（测试）
客户端非常适合测试和开发：
# Set environment variables
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
# Query a specific bus stop
npm run client 2775
# List available tools
npm run client -- list输出示例：
🚌 Bus Stop: Pl Espanya - FGC (108)
📅 Query Time: 11/6/2025, 10:30:00 AM
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚍 Line H12 (212) → Gornal
Direction: return
Next arrivals:
• ⏱️ 2 min (at 10:32:00) - Bus #3673
• ⏱️ 16 min (at 10:46:00) - Bus #8531选项2：与Claude Desktop一起使用
将服务器添加到您的Claude Desktop配置中：
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json\ 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tmb-bus": {
"command": "node",
"args": ["/absolute/path/to/tmb-bus-mcp/dist/server.js"],
"env": {
"TMB_APP_ID": "your_app_id",
"TMB_APP_KEY": "your_app_key"
}
}
}
}然后重新启动Claude Desktop。你现在可以问克劳德这样的问题：
- “2775站有哪些公交车？”
- “下一班公共汽车什么时候到西班牙广场？”
- “显示所有到达108站的巴士”
选项3：使用主机（独立）
独立运行服务器：
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
npm run host🛠️ 架构说明
MCP服务器(src/server.ts)
核心组件：
- 暴露
get_bus_arrivals通过MCP协议的工具 - 处理与TMB的iBus API的通信
- 将原始API响应转换为用户友好的格式
- 在stdio传输上运行，便于集成
主要职责：
- 工具注册和发现
- 请求验证
- API通信与错误处理
- 数据转换和格式化
主机应用程序(src/host.ts)
一个简单的包装：
- 将MCP服务器作为子进程启动
- 管理环境变量
- 处理优雅关机
何时使用： 用于没有MCP客户端的独立部署或测试。
客户端应用程序(src/client.ts)
演示客户端：
- 通过stdio连接到MCP服务器
- 列出可用工具
- 使用参数调用工具
- 显示格式化结果
何时使用： 用于测试、开发或作为参考实现。
🔌 API集成详细信息
服务器连接到TMB的iBus API：
端点： https://api.tmb.cat/v1/itransit/bus/parades/{stopCode}
参数：
app_id：您的TMB应用程序IDapp_key：您的TMB应用程序密钥
响应结构：
{
timestamp: number, // Query timestamp
parades: [{
codi_parada: string, // Stop code
nom_parada: string, // Stop name
linies_trajectes: [{ // Lines serving this stop
codi_linia: string, // Line code
nom_linia: string, // Line name
desti_trajecte: string, // Destination
id_sentit: number, // 1=Outbound, 2=Return
propers_busos: [{ // Upcoming buses
temps_arribada: number, // Arrival timestamp
id_bus: number // Bus identifier
}]
}]
}]
}📝 类型安全
该项目使用具有严格类型检查的TypeScript。所有API响应都已正确键入 src/types.ts:
TMBApiResponse：原始API响应结构BusStopInfo：转换后的用户友好格式FormattedBusArrival：个别线路信息
🧪 测试不同的公交车站
试试这些巴塞罗那巴士站：
2775：随机停止108：PL西班牙-FGC1：加泰罗尼亚2554： 圣家族
🔍 运作原理
- 客户端请求：MCP客户端（如Claude）调用
get_bus_arrivals带有停止代码的工具 - 服务器处理：MCP服务器通过stdio传输接收请求
- API查询：服务器向TMB的iBus API发出经过身份验证的请求
- 数据转换：原始API响应转换为可读格式
- 时间计算：到达时间戳转换为“到达前的分钟数”
- 响应：格式化文本返回给客户端
┌─────────┐ ┌──────────┐ ┌─────────┐
│ Client │────────▶│ MCP │────────▶│ TMB │
│ (Claude)│ │ Server │ │ API │
└─────────┘ └──────────┘ └─────────┘
▲ │ │
│ ▼ │
│ Transform Data │
│ │ │
└────────────────────┴────────────────────┘🚦 错误处理
服务器处理各种错误情况：
- 缺少凭据：退出时显示明确的错误消息
- 停止代码无效：返回用户友好错误
- API错误：捕获并格式化API错误响应
- 网络问题：处理超时和连接错误
🔐 安全说明
- 永远不要承诺你的
.env文件或API凭据 - 这
.env.example文件显示了没有真实凭据的格式 - 凭据是通过环境变量传递的，而不是硬编码的
- 将MCP的内置传输安全性用于生产部署
📚 MCP协议详细信息
此服务器实现MCP（模型上下文协议）：
- 运输：stdio（标准输入/输出）
- 能力：工具
- 工具名称:
get_bus_arrivals - 输入:
{ stopCode: string } - 输出：带巴士到达信息的格式化文本
🤝 贡献
要扩展此服务器，请执行以下操作：
- 在中添加新工具
server.tsgetTools()方法 - 在中实现处理程序
handleToolCall() - 更新类型
types.ts根据需要 - 使用客户端应用程序进行测试
📄 许可证
麻省理工学院
🙏 鸣谢
- TMB API：https://developer.tmb.cat/
- MCP-SDK：https://github.com/anthropics/modelcontextprotocol
______________________________________________________________________
问题？ 请查看MCP文档，网址为https://modelcontextprotocol.io/