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 — 用於集成谷歌地圖地理編碼功能。
• 半正矢公式 — 用於準確的距離計算。