Gtmcp

🚀 佐治亚理工学院综合MCP服务器

这是一个先进的MCP（模型上下文协议）服务器，它为大语言模型提供全面访问佐治亚理工学院学术和研究生态系统的能力，集成了多个佐治亚理工学院的系统，以实现智能工作流程。现已修复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
   

💻 使用示例

基础用法

基础课程调度

# 搜索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()

高级用法

在更复杂的场景中，你可以组合使用多个工具，以实现更强大的功能。例如，结合课程搜索和教师研究匹配，为特定的研究领域找到合适的课程和教师。

# 为机器人研究找到相关课程和教师
courses = find_courses_for_research(research_topic="robotics", term_code="202502")
faculty = find_faculty_research(research_area="robotics")
print("相关课程:", courses)
print("相关教师:", faculty)

📚 详细文档

ChatGPT集成设置

快速开始

1. 启动HTTP服务器：

   ./start_server_chatgpt.sh
   

   服务器默认运行在http://0.0.0.0:8080。

2. 配置ChatGPT：

   • 打开ChatGPT设置。
   • 转到“测试版功能”。
   • 启用“自定义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

速率限制

抓取器包含可配置的延迟和重试逻辑，以尊重佐治亚理工学院的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工具提供结构化的错误响应。

所有错误都以适当的严重级别进行记录，并包含有助于调试的上下文信息。

数据可用性说明

佐治亚理工学院可能不会保留下学期之后的课程详细信息，即使旧学期会显示在下拉菜单中。请始终检查请求学期的课程是否实际可用。

⚠️ 重要提示

佐治亚理工学院可能不会保留下学期之后的课程详细信息，即使旧学期会显示在下拉菜单中。请始终检查请求学期的课程是否实际可用。

💡 使用建议

在使用过程中，可根据实际需求灵活配置config.json文件，以优化服务器性能和功能。同时，定期运行测试脚本，确保系统的稳定性和可靠性。