STARWARCLOUD STARWAR.AI
返回市场
ibus-mcp

ibus-mcp

作者：esteveavi4 星标更新：2025-11-06
安装使用来源：spider==github.com

项目介绍

TMB 公交到站时间 MCP 服务器

这是一个提供 TMB（巴塞罗那大都会运输）公交站点实时到站信息的 Model Context Protocol (MCP) 服务器。

🚀 功能特性

  • 实时公交到站信息：获取最新的公交车到站时间信息
  • 多线路支持：查看服务于某个站点的所有公交线路
  • 分钟显示：到站时间以分钟为单位显示，便于理解
  • 详细信息：包括线路编号、目的地、方向及公交ID
  • 符合MCP标准：与任何MCP客户端兼容，包括Claude Desktop

📋 预备条件

🔧 安装步骤

  1. 克隆或创建项目：
mkdir tmb-bus-mcp
cd tmb-bus-mcp
  1. 安装依赖项：
npm install
  1. 设置您的TMB API凭证：
# 复制示例环境文件
cp .env.example .env

# 编辑.env并添加您的凭证
# TMB_APP_ID=your_app_id
# TMB_APP_KEY=your_app_key
  1. 构建项目：
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应用程序ID
  • app_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 - FGC
  • 1：Pl Catalunya
  • 2554：Sagrada Família

🔍 工作原理

  1. 客户端请求：MCP客户端（如Claude）调用带有站点代码的get_bus_arrivals工具
  2. 服务器处理：MCP服务器通过stdio传输接收请求
  3. API查询：服务器进行身份验证后请求TMB的iBus API
  4. 数据转换：原始API响应被转换成可读格式
  5. 时间计算：到达时间戳转换为“几分钟后到达”
  6. 响应：格式化文本返回给客户端
┌─────────┐         ┌──────────┐         ┌─────────┐
│  客户端 │────────▶│   MCP    │────────▶│   TMB   │
│ (Claude)│         │  服务器  │         │   API   │
└─────────┘         └──────────┘         └─────────┘
     ▲                    │                    │
     │                    ▼                    │
     │              转换数据             │
     │                    │                    │
     └────────────────────┴────────────────────┘

🚦 错误处理

服务器处理各种错误场景：

  • 缺少凭证：退出时带有清晰的错误消息
  • 无效站点代码：返回用户友好的错误
  • API错误：捕获并格式化API错误响应
  • 网络问题：处理超时和连接错误

🔐 安全注意事项

  • 永远不要提交您的.env文件或API凭证
  • .env.example文件展示了没有真实凭证的格式
  • 凭证通过环境变量传递，而不是硬编码
  • 生产部署时使用MCP内置的传输安全

📚 MCP协议详情

此服务器实现了MCP（模型上下文协议）：

  • 传输：stdio（标准输入/输出）
  • 能力：工具
  • 工具名称：get_bus_arrivals
  • 输入：{ stopCode: string }
  • 输出：格式化文本，包含公交到站信息

🤝 贡献指南

要扩展此服务器：

  1. 在server.ts的getTools()方法中添加新工具
  2. 在handleToolCall()中实现处理器
  3. 根据需要更新types.ts中的类型
  4. 使用客户端应用进行测试

📄 许可证

MIT

🙏 致谢

问题？ 查看MCP文档：https://modelcontextprotocol.io/