Mobusmcp

🚀 🚌 Mo Bus / Ama Bus MCP Server (非官方)

Mo Bus / Ama Bus MCP Server 是一个非官方的、由人工智能驱动的巴士路线规划工具，专为奥里萨邦首府地区打造。它能让你通过Claude、ChatGPT或任何支持MCP协议的人工智能助手，使用自然语言查询，轻松规划在布巴内斯瓦尔、卡特卡和普里的日常通勤路线。

🚀 快速开始

启动服务器（独立运行）

# 首先激活虚拟环境
source .venv/bin/activate  # macOS/Linux
# 或者
.venv\Scripts\activate     # Windows

# 运行服务器
python -m src.server

服务器将开始监听MCP客户端连接。

与Claude Desktop配置

1. 从 Claude.ai 安装Claude Desktop。
2. 编辑Claude Desktop配置文件：
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json
3. 添加Mo Bus服务器配置：

{
  "mcpServers": {
    "mo-bus": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "C:\\path\\to\\MoBusMCP",
      "env": {
        "PYTHONPATH": "C:\\path\\to\\MoBusMCP",
        "SERPAPI_KEY": "your_serpapi_key_here"
      }
    }
  }
}

4. 重启Claude Desktop。
5. 开始规划你的行程！

✨ 主要特性

🚏 智能行程规划

• 自然语言查询：用简单的英语提问即可。
• 智能地理编码：使用谷歌地图（SerpAPI）和OpenStreetMap。
• 最近站点检测：自动查找最近的Mo Bus站点。
• 多路线建议：提供备选路线及其优缺点。
• 步行距离计算：准确知道需要步行的距离。
• 实时票价估算：根据距离和路线计算。

🗺️ 全面覆盖

• 60多条巴士路线：覆盖主要通道。
• 734个巴士站点：遍布布巴内斯瓦尔、卡特卡和普里。
• 3个主要城市：实现首府地区的互联互通。
• 特殊服务路线：包括机场、火车站和医院路线。

🤖 原生AI设计

• MCP协议：可与Claude Desktop、ChatGPT等配合使用。
• FastMCP框架：采用简洁、现代的Python实现。
• 基于工具的架构：模块化、可扩展的设计。
• 上下文感知：理解地标、地址和通俗名称。

🔧 开发者友好

• 文档完善：代码简洁，注释全面。
• 易于扩展：采用模块化服务架构。
• 基于环境的配置：通过简单的 .env 文件进行设置。
• 全面的错误处理：实现优雅降级。

🗺️ 官方巴士网络地图

这是奥里萨邦首府地区城市交通（CRUT）网络的完整站点和路线地图：

地图覆盖范围

• 主要网络：连接城市中心的所有主要路线。
• 站点位置：所有巴士站点的精确地理位置。
• 路线详情：采用颜色编码的路线，便于识别。
• 连接点：公交枢纽和换乘站。
• 服务区域：机场、火车站、医院和教育机构。

如需获取最新的官方信息，请访问 CRUT官方网站。

🏗️ 架构

系统设计

graph TD
    subgraph Client["🖥️ 客户端层"]
        Claude["Claude Desktop"]
        ChatGPT["ChatGPT"]
        Other["其他AI客户端"]
    end
    
    subgraph MCP["🔌 MCP协议层"]
        Protocol["stdin/stdout/HTTPS通信"]
    end
    
    subgraph Server["🚀 MCP服务器层<br/>FastMCP"]
        Journey["行程规划器"]
        Route["路线查找器"]
        Fare["票价计算器"]
    end
    
    subgraph Service["🌐 服务层"]
        Geocoding["地理编码服务<br/>SerpAPI + Nominatim"]
        SerpAPI["谷歌地图<br/>SerpAPI"]
        OSM["OpenStreetMap<br/>Nominatim"]
    end
    
    subgraph Data["💾 数据层"]
        JSON["JSON数据存储"]
        Routes["60多条路线"]
        Stops["734个站点"]
        Fares["票价结构"]
    end
    
    Claude --> Protocol
    ChatGPT --> Protocol
    Other --> Protocol
    Protocol --> Journey
    Protocol --> Route
    Protocol --> Fare
    Journey --> Geocoding
    Route --> Geocoding
    Fare --> JSON
    Geocoding --> SerpAPI
    Geocoding --> OSM
    JSON --> Routes
    JSON --> Stops
    JSON --> Fares
    
    classDef clientStyle fill:#FF6B6B,stroke:#C92A2A,color:#fff,stroke-width:2px
    classDef protocolStyle fill:#4ECDC4,stroke:#088395,color:#fff,stroke-width:2px
    classDef serverStyle fill:#95E1D3,stroke:#38ADA9,color:#000,stroke-width:2px
    classDef serviceStyle fill:#FFE66D,stroke:#F4A261,color:#000,stroke-width:2px
    classDef dataStyle fill:#A8DADC,stroke:#457B9D,color:#000,stroke-width:2px
    
    class Client clientStyle
    class MCP protocolStyle
    class Server serverStyle
    class Service serviceStyle
    class Data dataStyle

组件分解

项目结构

AmABUSMCP/
├── src/
│   ├── __init__.py                   # 包初始化
│   ├── server.py                     # FastMCP服务器入口点
│   ├── data/
│   │   ├── __init__.py              # 数据加载和辅助工具
│   │   └── (数据实用工具)
│   ├── services/
│   │   ├── __init__.py
│   │   ├── geocoding.py             # SerpAPI + OSM地理编码服务
│   │   └── planner.py               # 行程规划算法
│   └── utils/
│       ├── __init__.py
│       └── distance.py              # 半正矢距离计算
├── asset/
│   ├── ALL STOP AND ROUT MAP.png    # 官方网络地图
│   ├── homescreen_logo-*.png        # Mo Bus标志
│   ├── crut_logo-*.png              # CRUT标志
│   └── AMA_BUS_ODIA-*.png           # Ama Bus标志
├── mo_bus_complete_database.json    # 完整的路线和站点数据库
├── requirements.txt                  # Python依赖项
├── pyproject.toml                   # 项目配置
├── .env.example                     # 示例环境变量
├── .gitignore                       # Git忽略规则
└── README.md                        # 本文件

📦 安装指南

前提条件

• Python 3.10或更高版本 — 下载Python
• pip 或 uv（推荐使用，安装速度更快）
• SerpAPI密钥（可选，用于增强地理编码功能）
• Git — 用于克隆仓库

方法1：使用 uv（推荐 - 最快）

uv 是一个用Rust编写的超快速Python包安装工具。

# 步骤1：安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 步骤2：克隆仓库
git clone https://github.com/HimanshuMohanty-Git24/MoBusMCP.git
cd MoBusMCP

# 步骤3：创建虚拟环境
uv venv

# 步骤4：激活虚拟环境
# 在Windows上：
.venv\Scripts\activate
# 在macOS/Linux上：
source .venv/bin/activate

# 步骤5：安装依赖项
uv sync

方法2：使用 pip

# 步骤1：克隆仓库
git clone https://github.com/HimanshuMohanty-Git24/MoBusMCP.git
cd MoBusMCP

# 步骤2：创建虚拟环境
python -m venv venv

# 步骤3：激活虚拟环境
# 在Windows上：
venv\Scripts\activate
# 在macOS/Linux上：
source venv/bin/activate

# 步骤4：安装依赖项
pip install -r requirements.txt

环境设置

在项目根目录下创建一个 .env 文件：

# 可选：用于通过谷歌地图增强地理编码功能
SERPAPI_KEY=your_serpapi_key_here

# 可选：服务器配置
LOG_LEVEL=INFO
DEBUG_MODE=false

获取免费的SerpAPI密钥：

1. 访问 SerpAPI
2. 注册一个免费账户（包含免费额度）
3. 复制你的API密钥
4. 将其添加到 .env 文件中

💻 使用示例

示例查询

尝试向Claude提出以下任何问题：

💬 "显示所有前往机场的巴士路线"

💬 "我在KIIT校区，需要前往布巴内斯瓦尔火车站。我应该乘坐哪辆巴士？"

💬 "哪些巴士在主食堂站停靠？"

💬 "计算从巴拉蒙达到南丹坎南动物园的票价"

💬 "规划我早上8:30从KIIT到阿查里雅维哈尔的埃森哲公司的通勤路线"

💬 "路线10上的所有站点有哪些？"

💬 "我需要从卡特卡前往布巴内斯瓦尔，有哪些选择？"

💬 "查找我当前位置（提及地标）附近的最近巴士站"

响应格式

Claude将提供结构化的响应，包含以下内容：

📍 出发地: [你的起始点]
📍 目的地: [你要前往的地方]
🚌 巴士选项: [可用的路线编号]
🚶 步行距离: [到最近站点的距离]
⏱️ 行程时间: [预计时长]
💰 票价: [预计费用]
📅 备选路线: [如果有]

高级功能

• 多段行程规划：自动提供换乘建议。
• 基于时间的规划：考虑高峰时段和时刻表。
• 步行优化：尽量减少步行距离。
• 票价计算：根据实际路线计算。

⚙️ 配置

SerpAPI设置（可选但推荐）

SerpAPI提供准确的谷歌地图地理编码功能，以实现更好的位置匹配。 如果不使用SerpAPI：系统将回退到免费的OpenStreetMap Nominatim（可用但准确性较低）。

设置步骤

1. 在 SerpAPI 上注册（有免费套餐）。
2. 从仪表盘获取你的API密钥。
3. 添加到 .env 文件中：

SERPAPI_KEY=your_key_here

4. 重启服务器。

自定义

添加新路线

编辑 mo_bus_complete_database.json：

{
  "routes": {
    "NEW_ROUTE": {
      "route_number": "NEW_ROUTE",
      "route_name": "起点 ↔ 终点",
      "start": "起始位置",
      "end": "结束位置",
      "via": "途经点",
      "stops": ["站点1", "站点2", "站点3"],
      "distance_km": 10,
      "service": "常规"
    }
  }
}

添加新站点

在 src/data/__init__.py 中添加坐标：

coordinate_map = {
    'your_stop_id': {'lat': 20.2961, 'lon': 85.8245},
    'another_stop': {'lat': 20.3000, 'lon': 85.8300},
}

环境变量

# 服务器日志级别
LOG_LEVEL=INFO|DEBUG|WARNING|ERROR

# 启用开发调试模式
DEBUG_MODE=true|false

# API超时时间（秒）
API_TIMEOUT=30

# 最大步行距离（公里）
MAX_WALKING_DISTANCE=5

📊 数据来源

数据获取过程

⚠️ 重要声明：所有路线和站点数据均由开发者手动收集和整理。具体过程如下：

1. 数据源收集

• 从 CRUT网站 下载官方路线地图。
• 从Mo Bus/Ama Bus应用程序收集路线图片。
• 从官方来源收集时刻表PDF文件。
• 与OpenStreetMap数据进行交叉引用。

2. 数据提取

• 使用大语言模型（GPT-4、Claude）将图像转换为数据。
• 手动验证和交叉引用输出结果。
• 分批次多次解析路线。
• 根据实际观察进行验证。

3. 数据整合

• 将所有解析的路线合并为统一的JSON格式。
• 使用GPS手动添加主要站点的坐标。
• 验证路线顺序和连接点。
• 创建全面的票价表。

数据准确性和覆盖范围

⚠️ 数据可能存在不准确的情况：

• 部分路线可能已过时（CRUT会定期更新路线）。
• 站点名称可能与官方来源不同。
• 坐标可能不够精确。
• CRUT新增的路线可能未包含在内。
• 已停用的路线可能仍然存在。

当前覆盖范围：

• ✅ 60多条路线（CRUT运营的84条以上路线中的一部分）
• ✅ 734个巴士站点
• ✅ 首府地区的18个城市/区域
• ⚠️ 约70%的路线覆盖

帮助改进数据

我们积极需要社区的贡献！如果您发现：

• ❌ 错误的路线信息
• ❌ 缺失的巴士站点
• ❌ 错误的站点顺序
• ❌ 过时的路线
• ❌ 坐标不准确

请进行贡献：

1. 在 GitHub Issues 上打开一个问题，并提供详细信息。
2. 提交一个包含修正内容的拉取请求。
3. 分享您拥有的准确数据。

优先需求：

• 🔴 实时巴士位置
• 🔴 实时时刻表更新
• 🔴 准确的站点坐标（GPS）
• 🔴 缺失的44条路线文档

🤝 贡献

我们非常欢迎您的贡献！无论您是开发者、数据爱好者还是巴士通勤者，都有多种方式可以参与贡献。

贡献类型

1. 数据改进（无需编码！）

• 添加缺失的路线
• 修正错误的站点顺序
• 添加准确的GPS坐标
• 更新路线名称和详细信息
• 验证现有数据

2. 代码增强

• 提高地理编码的准确性
• 优化行程规划算法
• 添加新功能（如实时跟踪）
• 改进错误处理
• 优化性能
• 添加单元测试

3. 文档编写

• 改进README文档
• 添加代码注释和文档字符串
• 创建教程文章
• 翻译文档
• 创建视频教程

4. 集成与合作

• 与其他AI平台集成
• 构建网页/移动界面
• 创建CLI工具
• 开发移动应用

贡献流程

# 1. 在GitHub上分叉仓库
git clone https://github.com/YOUR-USERNAME/MoBusMCP.git
cd MoBusMCP

# 2. 创建一个功能分支
git checkout -b feature/your-feature-name

# 3. 进行更改
# 编辑文件、添加功能、改进数据等。

# 4. 提交更改
git add .
git commit -m "Add: 更改描述"

# 5. 推送到您的分叉仓库
git push origin feature/your-feature-name

# 6. 在GitHub上打开一个拉取请求
# 包括更改描述以及为什么需要这些更改

代码风格指南

• Python代码遵循 PEP 8 规范。
• 尽可能添加 类型提示。
• 为函数编写 文档字符串。
• 为复杂逻辑添加 注释。
• 保持函数 短小精悍。

提交消息格式

类型: 简要描述（最多50个字符）

可选的详细描述，解释为什么进行此更改。
引用问题：#123, #456

类型：Add:、Fix:、Improve:、Docs:、Refactor:、Test:

🤝 合作机会

🚨 呼吁CRUT和Chalo团队！

致：首府地区城市交通（CRUT）
致：Chalo应用开发团队
项目：Mo Bus MCP Server

您好！我是这个非官方Mo Bus MCP服务器的开发者，作为一名经常乘坐Mo Bus的通勤者，我出于热情开发了这个项目，旨在解决实际的通勤问题。

我们已经完成的工作

• ✅ 运行中的人工智能行程规划器：提供自然语言界面。
• ✅ 与Claude、ChatGPT和其他AI助手集成：通过MCP协议实现。
• ✅ 60条路线和734个站点：手动编译和验证。
• ✅ 智能地理编码：使用SerpAPI和OpenStreetMap。
• ✅ 模块化、可扩展的架构：易于增强功能。

我们可以共同构建的内容

• 🚀 实时巴士跟踪：集成实时位置信息。
• 🚀 实时时刻表更新：直接从CRUT系统获取。
• 🚀 准确的官方路线数据：来自您的数据库。
• 🚀 支付集成：通过AI实现Razorpay/UPI票务预订。
• 🚀 应用内票务：直接通过Claude/ChatGPT实现。
• 🚀 座位可用性：提供实时巴士拥挤信息。
• 🚀 延误通知：即时警报和备选方案。
• 🚀 多语言支持：提供奥里亚语、印地语和英语界面。

为什么要合作？

对于CRUT/Chalo：

• 📈 通过人工智能提高乘客数量。
• 💡 利用新兴技术创新通勤规划。
• 🌟 展示奥里萨邦作为人工智能公共交通领导者的形象。
• 📉 通过智能自动化减少支持查询。
• 🤝 建立技术达人通勤者社区。

对于社区：

• ✨ 准确的实时行程规划。
• 🎟️ 通过AI实现无缝票务预订。
• 📱 为所有用户提供更好的通勤体验。
• 🚌 鼓励使用公共交通。
• 🌍 提供可持续的城市出行解决方案。

让我们一起交流吧！

我愿意进行以下合作：

• 🤝 建立官方合作伙伴关系或签署谅解备忘录。
• 🔌 获取实时数据的API访问权限。
• 👨‍💻 联合开发功能。
• 📜 达成许可协议。
• 💼 寻找最适合大家的合作方式！

联系方式：在 GitHub Issues 上提出问题或通过GitHub联系我。

⚠️ 免责声明

非官方项目

这是一个非官方、社区驱动的项目，与以下机构没有关联、未得到其认可或与之无关：

• 首府地区城市交通（CRUT）
• 奥里萨邦政府
• Chalo应用程序或其任何开发者
• 任何官方Mo Bus/Ama Bus服务提供商
• 任何政府交通部门

数据准确性

不提供任何保证：本项目中的路线、站点和时刻表数据：

• 可能 不完整、过时或不准确。
• 是从公开可用的来源 手动编译 的。
• 未经过官方验证。
• 不应作为行程规划的唯一依据。
• 可能无法反映当前的运营情况。

始终独立验证

在出行前，请始终进行以下验证：

• ✓ 查看 官方Mo Bus/Ama Bus应用程序。
• ✓ 向 巴士售票员 确认路线。
• ✓ 访问 CRUT官方网站 获取官方时刻表。
• ✓ 检查是否有 服务变更或罢工。

责任免责声明

本项目的开发者和维护者：

• 按 “原样” 提供此软件，不提供任何形式的保证。
• 不承担以下责任：
  • 错过巴士或交通延误。
  • 错误或过时的路线信息。
  • 出行不便或错过预约。
  • 数据准确性问题。
  • 服务不可用。
• 不保证 数据准确性或服务可用性。
• 对因使用此软件而产生的任何损害 不承担责任。

自行承担风险

使用此MCP服务器即表示您承认并接受：

• 这是一个 实验性的社区驱动项目。
• 数据 可能不准确或严重过时。
• 您将 独立验证重要的行程信息。
• 您 完全自行承担使用此工具的风险。
• 您 免除开发者的任何责任。

📄 许可证

MIT许可证 — 完整详情请参阅 LICENSE 文件。

简单解释（TL;DR）

✅ 您可以：

• 自由使用本项目。
• 修改和重新分发。
• 用于商业用途。
• 创建衍生作品。

❌ 您必须：

• 包含原始许可证。
• 包含版权声明。
• 不追究我们的责任。

总结：可以自由使用和修改，但需自行承担风险！😊

📞 支持与社区

获取帮助

• 问题与漏洞：GitHub Issues
• 讨论：GitHub Discussions
• 文档：本README
• 电子邮件：[您的联系信息]

社区互动

• 🌟 如果您觉得这个项目有用，请给它加星。
• 🍴 分叉并贡献代码，共同改进项目。
• 💬 分享您的反馈和建议。
• 📣 向其他通勤者宣传这个项目。

🙏 致谢与鸣谢

组织

• CRUT（首府地区城市交通） — 运营Mo Bus/Ama Bus服务。
• 奥里萨邦政府 — 提供公共交通基础设施。
• Chalo应用团队 — 开发了原始的Mo Bus应用程序。

技术与库

• FastMCP — 优秀的MCP框架开发者。
• Claude & ChatGPT — 提供人工智能能力和数据提取功能。
• OpenStreetMap — 提供免费的地图数据和Nominatim服务。
• SerpAPI — 用于集成谷歌地图地理编码功能。
• 半正矢公式 — 用于准确的距离计算。