Gtmcp

🚀 佐治亞理工學院綜合MCP服務器

這是一個先進的MCP（模型上下文協議）服務器，它為大語言模型（LLMs）提供全面訪問佐治亞理工學院學術和研究生態系統的能力，集成了多個佐治亞理工學院的系統，以實現智能工作流程。現已修復OSCAR 500錯誤，確保課程搜索的可靠性，並實現了與ChatGPT的HTTP集成。

✨ 主要特性

ChatGPT集成 ✨ 新增：HTTP API服務器

• FastAPI HTTP服務器：提供完整的HTTP API，用於集成ChatGPT自定義工具。
• 支持CORS：支持來自ChatGPT域名的跨域請求。
• JSON響應：所有端點均返回適合ChatGPT使用的正確JSON格式。
• 自動文檔：在/docs端點提供交互式OpenAPI/Swagger文檔。
• 健康監控：實時進行服務健康檢查和監控。

核心課程調度（OSCAR系統） ✨ 已修復500錯誤

• 可用學期：獲取可用於課程搜索的學期列表。
• 學科查詢：獲取給定學期可用的系/學科列表。
• 課程搜索：按學科、課程編號或標題搜索課程，可靠性更高。
• 課程詳情：獲取詳細信息，包括座位可用性、候補名單信息和限制條件。
• 優化工作流程：通過實施正確的佐治亞理工學院導航模式，修復了500服務器錯誤。

研究與知識系統（SMARTech知識庫）

• 研究論文搜索：搜索500多篇研究論文、學位論文和出版物。
• 教師研究匹配：根據研究興趣和合作歷史查找教師。
• 研究趨勢分析：分析出版物隨時間的趨勢。
• 交叉引用：將研究領域與相關課程關聯起來。

校園基礎設施（場所與地理信息系統）

• 位置服務：搜索校園建築和設施。
• 無障礙信息：提供詳細的無障礙設施和路線規劃。
• 服務發現：查找提供特定服務（如視聽設備、餐飲等）的建築。
• 空間分析：路線規劃和鄰近搜索。

跨系統集成

• 研究 - 課程關聯：“哪些課程支持我的機器人研究？”
• 教師 - 課程匹配：“誰教授與我的研究領域相關的課程？”
• 資源優化：“在計算機科學大樓附近找到有網絡設備的實驗室”
• 學術規劃：“規劃包含研究機會的學位路徑”

📦 安裝指南

自動安裝（推薦）

1. 運行安裝腳本：

   ./setup.sh
   

   這將自動創建conda環境並安裝所有依賴項。

2. 啟動服務器：

   # 用於ChatGPT集成（HTTP API服務器）：
   ./start_server_chatgpt.sh
   
   # 用於擴展功能（所有佐治亞理工學院系統）：
   ./start_server_expanded.sh
   
   # 僅用於原始課程調度：
   ./start_server.sh
   

手動安裝

1. 創建conda環境：

   conda create -n gtmcp python=3.11 -y
   conda activate gtmcp
   

2. 安裝依賴項：

   pip install -r requirements.txt
   pip install -e .
   

3. 測試功能：

   # 測試原始課程調度：
   python test_server.py
   
   # 測試擴展多系統功能：
   python test_expanded_server.py
   

4. 運行單元測試：

   python -m pytest tests/ -v
   

5. 運行服務器：

   # ChatGPT HTTP API服務器：
   python -m gtmcp.server_fastapi --host 0.0.0.0 --port 8080
   
   # 擴展服務器（推薦）：
   python -m gtmcp.server_expanded
   
   # 僅用於原始課程調度：
   python -m gtmcp.server
   

🚀 快速開始

ChatGPT集成設置

快速入門

1. 啟動HTTP服務器：

   ./start_server_chatgpt.sh
   

   服務器默認運行在http://0.0.0.0:8080。

2. 配置ChatGPT：

   • 打開ChatGPT設置。
   • 轉到“Beta功能”。
   • 啟用“自定義GPT和工具”。
   • 創建新的自定義工具：
     • 名稱：佐治亞理工學院MCP服務器
     • 描述：訪問佐治亞理工學院的課程表和研究資源
     • URL：http://localhost:8080

可用的HTTP端點

GET  /                           # 服務器信息和功能
GET  /health                     # 系統健康狀態
GET  /tools                      # 可用的MCP工具
GET  /api/semesters             # 可用的學術學期
GET  /api/subjects/{term_code}   # 特定學期的學科
GET  /api/courses               # 課程搜索（查詢參數：term_code, subject）
GET  /api/courses/{term}/{crn}  # 詳細的課程信息
GET  /api/research              # 研究論文搜索（查詢參數：keywords, max_records）
GET  /docs                      # 交互式API文檔
GET  /openapi.json              # OpenAPI規範
GET  /.well-known/ai-plugin.json # ChatGPT AI插件清單
GET  /legal                     # 法律信息和條款

示例ChatGPT查詢

• “2025年春季有哪些計算機科學課程？”
• “查找關於機器學習的研究論文”
• “獲取2025年春季課程編號為12345的課程詳情”
• “2024年秋季有哪些可用的學科？”

📚 詳細文檔

MCP工具（17個綜合工具）

課程與學術工具

get_available_semesters

獲取可用學期的列表。

• 輸入：無
• 輸出：包含學期代碼和名稱的列表

get_subjects

獲取某一學期可用的學科/系。

• 輸入：term_code（例如，“202502”表示2025年春季）
• 輸出：學科代碼和名稱的列表

search_courses

在給定學期和學科中搜索課程。

• 輸入：
  • term_code：學期代碼
  • subject：學科代碼（例如，“CS”、“MATH”）
  • course_num（可選）：課程編號過濾器
  • title（可選）：標題搜索過濾器
• 輸出：包含匹配課程CRN的列表

get_course_details

獲取特定課程的詳細信息。

• 輸入：
  • term_code：學期代碼
  • crn：課程參考編號
• 輸出：詳細的課程信息，包括座位、候補名單、限制條件

研究與知識工具

search_research_papers

在佐治亞理工學院研究知識庫中搜索論文。

• 輸入：
  • keywords：搜索關鍵詞數組
  • subject_areas：要過濾的學科領域
  • date_from/date_until：日期範圍過濾器
  • max_results：要返回的最大結果數
• 輸出：包含摘要和元數據的研究論文列表

find_faculty_research

根據研究領域查找教師研究簡介。

• 輸入：research_area（例如，“機器人技術”、“人工智能”）
• 輸出：包含研究興趣和出版物的教師簡介

analyze_research_trends

分析關鍵詞隨時間的研究趨勢。

• 輸入：
  • keywords：要分析的關鍵詞
  • years：要分析的年數
• 輸出：包含每年出版物數量的趨勢分析

get_repository_info

獲取佐治亞理工學院研究知識庫的信息。

• 輸入：無
• 輸出：知識庫元數據和統計信息

校園與位置工具

search_campus_locations

搜索校園建築和位置。

• 輸入：
  • query：建築/位置名稱的搜索查詢
  • services：所需的服務（例如，“視聽設備”）
  • accessible：過濾輪椅可進入的位置
• 輸出：匹配的校園位置列表

get_location_details

獲取特定位置的詳細信息。

• 輸入：building_id：建築標識符
• 輸出：完整的位置詳細信息，包括服務和無障礙設施

find_nearby_locations

查找特定建築附近的位置。

• 輸入：
  • center_building_id：要搜索的中心建築
  • radius_meters：搜索半徑
  • services：要過濾的服務
• 輸出：半徑範圍內的附近位置列表

get_accessibility_info

獲取建築的詳細無障礙信息。

• 輸入：building_id：建築標識符
• 輸出：全面的無障礙功能和服務

跨系統集成工具

suggest_research_collaborators

根據研究興趣推薦潛在的合作者。

• 輸入：
  • research_area：合作的研究領域
  • keywords：特定的研究關鍵詞
• 輸出：推薦的教師和研究人員，以及重疊分析

find_courses_for_research

查找與特定研究領域相關的課程。

• 輸入：
  • research_topic：研究主題或領域
  • term_code：要搜索的學期（可選）
• 輸出：與研究相關的課程

check_system_health

檢查所有集成的佐治亞理工學院系統的健康狀態。

• 輸入：無
• 輸出：OSCAR、SMARTech、Places等系統的狀態報告

配置

服務器可以通過config.json進行配置：

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "log_level": "INFO"
  },
  "scraper": {
    "delay": 1.0,
    "timeout": 30,
    "max_retries": 3
  },
  "cache": {
    "enabled": true,
    "ttl_seconds": 3600
  }
}

命令行選項

# 使用自定義配置文件運行
python -m gtmcp.server --config /path/to/config.json

# 覆蓋特定設置
python -m gtmcp.server --host 127.0.0.1 --port 9000 --log-level DEBUG

# 使用自定義參數的啟動腳本
./start_server.sh --host 127.0.0.1 --port 9000

💻 使用示例

基礎課程調度

# 搜索2025年春季的計算機科學課程
search_courses(term_code="202502", subject="CS")

# 獲取特定課程的詳細信息
get_course_details(term_code="202502", crn="25645")

研究與教師發現

# 查找關於機器學習的研究論文
search_research_papers(keywords=["machine learning", "AI"], max_results=10)

# 查找從事機器人技術研究的教師
find_faculty_research(research_area="robotics")

# 分析人工智能研究5年的趨勢
analyze_research_trends(keywords=["artificial intelligence"], years=5)

校園導航與服務

# 查找配備視聽設備且無障礙的建築
search_campus_locations(services=["AV equipment"], accessible=True)

# 查找圖書館附近的位置
find_nearby_locations(center_building_id="library", radius_meters=500)

# 獲取某一建築的無障礙詳細信息
get_accessibility_info(building_id="klaus_building")

跨系統智能

# 查找支持可持續發展研究的課程
find_courses_for_research(research_topic="sustainability", term_code="202502")

# 為網絡研究推薦合作者
suggest_research_collaborators(research_area="networking", keywords=["wireless", "5G"])

# 檢查所有佐治亞理工學院系統的健康狀況
check_system_health()

速率限制

爬蟲程序包含可配置的延遲和重試邏輯，以尊重佐治亞理工學院的OSCAR系統：

• 默認請求間隔為1秒
• 每個請求的超時時間為30秒
• 最多重試3次，採用指數退避策略

測試

項目包含對所有集成系統的全面測試：

綜合測試套件（124多個測試）

• 38個HTTP服務器測試：FastAPI端點測試和ChatGPT集成驗證
• 17個外部服務器測試：通過子進程管理進行真實HTTP服務器集成測試
• 69多個MCP單元測試：原始MCP功能驗證和客戶端測試

HTTP服務器和ChatGPT集成測試

# 運行所有HTTP集成測試（38個測試）
python -m pytest tests/test_fastapi_server.py tests/test_external_server.py -v

# 運行FastAPI服務器測試（21個測試）
python -m pytest tests/test_fastapi_server.py -v

# 運行外部服務器測試（17個測試）  
python -m pytest tests/test_external_server.py -v

# 運行特定測試類別
python -m pytest tests/test_fastapi_server.py::TestFastAPIServerBasic -v
python -m pytest tests/test_external_server.py::TestExternalServerChatGPTCompatibility -v

單元測試

• 模型測試：數據驗證和序列化
• 配置測試：配置加載和驗證
• 客戶端測試：所有佐治亞理工學院系統客戶端，使用模擬響應
• 服務器測試：MCP服務器工具和錯誤處理
• 集成測試：跨系統工作流程驗證

運行所有測試：

python -m pytest tests/ -v

運行特定測試模塊：

python -m pytest tests/test_oscar_client.py -v
python -m pytest tests/test_smartech_client.py -v
python -m pytest tests/test_places_client.py -v
python -m pytest tests/test_server_expanded.py -v

集成測試

# 測試原始課程調度：
python test_server.py

# 測試擴展多系統功能：
python test_expanded_server.py

測試類別

FastAPI服務器測試（21個測試）

• ✅ 基本功能：根、健康和工具端點
• ✅ OSCAR集成：使用模擬數據進行學期、學科、課程和詳情測試
• ✅ 研究集成：論文搜索和研究端點
• ✅ ChatGPT兼容性：CORS、JSON響應、AI插件清單、法律端點
• ✅ 性能：併發請求、大響應、錯誤恢復

外部服務器測試（17個測試）

• ✅ 真實HTTP服務器：子進程啟動和外部HTTP測試
• ✅ ChatGPT集成：跨域請求和響應驗證
• ✅ 服務器可靠性：負載測試、內存穩定性、錯誤恢復
• ✅ API文檔：OpenAPI規範和交互式文檔驗證

系統健康檢查

# 快速檢查所有系統的健康狀況：
python -c "
from gtmcp.server_expanded import *
import asyncio
asyncio.run(main())
" --help

錯誤處理

應用程序包含全面的錯誤處理：

• 網絡錯誤：採用指數退避策略的重試邏輯
• 解析錯誤：優雅處理格式錯誤的HTML
• 驗證錯誤：輸入驗證，提供清晰的錯誤消息
• 服務器錯誤：為MCP工具提供結構化的錯誤響應

所有錯誤都會以適當的嚴重級別進行日誌記錄，幷包含有助於調試的有用上下文信息。

數據可用性說明

佐治亞理工學院可能不會保留下學期之後的課程詳細信息，即使下拉菜單中顯示有較舊的學期。請始終檢查所請求學期的課程是否實際可用。