ibus-mcp
项目介绍
TMB 公交到站时间 MCP 服务器
这是一个提供 TMB（巴塞罗那大都会运输）公交站点实时到站信息的 Model Context Protocol (MCP) 服务器。
🚀 功能特性
- 实时公交到站信息：获取最新的公交车到站时间信息
- 多线路支持：查看服务于某个站点的所有公交线路
- 分钟显示：到站时间以分钟为单位显示，便于理解
- 详细信息：包括线路编号、目的地、方向及公交ID
- 符合MCP标准：与任何MCP客户端兼容，包括Claude Desktop
📋 预备条件
- Node.js 18+
- npm 或 yarn
- TMB API 凭证（在 https://developer.tmb.cat/ 获取）
🔧 安装步骤
- 克隆或创建项目：
mkdir tmb-bus-mcp
cd tmb-bus-mcp
- 安装依赖项：
npm install
- 设置您的TMB API凭证：
# 复制示例环境文件
cp .env.example .env
# 编辑.env并添加您的凭证
# TMB_APP_ID=your_app_id
# TMB_APP_KEY=your_app_key
- 构建项目：
npm run build
🎯 使用方法
方案1：使用客户端（测试）
客户端非常适合用于测试和开发：
# 设置环境变量
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
# 查询特定公交站点
npm run client 2775
# 列出可用工具
npm run client -- list
示例输出：
🚌 公交站点：Pl Espanya - FGC (108)
📅 查询时间：2025年11月6日，上午10:30:00
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🚍 线路H12 (212) → Gornal
方向：返回
下一班车：
• ⏱️ 2分钟（10:32:00）- 公交车#3673
• ⏱️ 16分钟（11:46:00）- 公交车#8531
方案2：与Claude Desktop结合使用
将服务器添加到您的Claude Desktop配置中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tmb-bus": {
"command": "node",
"args": ["/绝对路径/to/tmb-bus-mcp/dist/server.js"],
"env": {
"TMB_APP_ID": "your_app_id",
"TMB_APP_KEY": "your_app_key"
}
}
}
}
然后重启Claude Desktop。现在您可以询问Claude如下问题：
- "2775站有哪些公交车即将到达？"
- "Pl Espanya站下一班车什么时候到？"
- "显示108站所有公交车到站情况"
方案3：独立运行主机
独立运行服务器：
export TMB_APP_ID=your_app_id
export TMB_APP_KEY=your_app_key
npm run host
🛠️ 架构详解
MCP服务器 (src/server.ts)
核心组件：
- 通过MCP协议暴露
get_bus_arrivals工具 - 处理与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, // 查询时间戳
parades: [{
codi_parada: string, // 站点代码
nom_parada: string, // 站点名称
linies_trajectes: [{ // 服务此站点的线路
codi_linia: string, // 线路代码
nom_linia: string, // 线路名称
desti_trajecte: string, // 目的地
id_sentit: number, // 1=出站，2=回站
propers_busos: [{ // 即将到来的公交车
temps_arribada: number, // 到达时间戳
id_bus: number // 公交车标识符
}]
}]
}]
}
📝 类型安全
项目使用TypeScript并进行严格的类型检查。所有API响应都在src/types.ts中正确地进行了类型定义：
TMBApiResponse：原始API响应结构BusStopInfo：转换后的用户友好格式FormattedBusArrival：单个线路信息
🧪 测试不同的公交站点
尝试这些巴塞罗那公交站点：
2775：随机站点108：Pl Espanya - FGC1：Pl Catalunya2554：Sagrada Família
🔍 工作原理
- 客户端请求：MCP客户端（如Claude）调用带有站点代码的
get_bus_arrivals工具 - 服务器处理：MCP服务器通过stdio传输接收请求
- API查询：服务器进行身份验证后请求TMB的iBus API
- 数据转换：原始API响应被转换成可读格式
- 时间计算：到达时间戳转换为“几分钟后到达”
- 响应：格式化文本返回给客户端
┌─────────┐ ┌──────────┐ ┌─────────┐
│ 客户端 │────────▶│ MCP │────────▶│ TMB │
│ (Claude)│ │ 服务器 │ │ API │
└─────────┘ └──────────┘ └─────────┘
▲ │ │
│ ▼ │
│ 转换数据 │
│ │ │
└────────────────────┴────────────────────┘
🚦 错误处理
服务器处理各种错误场景：
- 缺少凭证：退出时带有清晰的错误消息
- 无效站点代码：返回用户友好的错误
- API错误：捕获并格式化API错误响应
- 网络问题：处理超时和连接错误
🔐 安全注意事项
- 永远不要提交您的
.env文件或API凭证 .env.example文件展示了没有真实凭证的格式- 凭证通过环境变量传递，而不是硬编码
- 生产部署时使用MCP内置的传输安全
📚 MCP协议详情
此服务器实现了MCP（模型上下文协议）：
- 传输：stdio（标准输入/输出）
- 能力：工具
- 工具名称：
get_bus_arrivals - 输入：
{ stopCode: string } - 输出：格式化文本，包含公交到站信息
🤝 贡献指南
要扩展此服务器：
- 在
server.ts的getTools()方法中添加新工具 - 在
handleToolCall()中实现处理器 - 根据需要更新
types.ts中的类型 - 使用客户端应用进行测试
📄 许可证
MIT
🙏 致谢
问题？ 查看MCP文档：https://modelcontextprotocol.io/