tamu grades MCP

TAMU等级分配MCP服务器

一种模型上下文协议（MCP）服务器，提供德克萨斯农工大学成绩分布数据的智能查询。专为 克劳德代码 帮助学生对课程和讲师选择做出明智的决定。

为什么这很重要

问题得克萨斯州农工大学有70000多名学生，15个工程系和数千个课程部门。学生在选择课程和教授时依赖口口相传、过时的论坛帖子或盲目的运气，这往往会导致糟糕的学术成绩。

解决方案：此MCP服务器将静态成绩分布PDF转换为智能、可查询的AI上下文引擎。学生无需手动搜索数百页，即可提出自然问题，并获得由6190多个历史课程部分支持的即时、数据驱动的答案。

影响:

• 帮助学生避免高风险课程并选择最佳讲师
• 通过数据驱动的课程选择实现GPA优化
• 每学期节省数小时的人工研究
• 使以前锁定在PDF中的成绩数据的访问民主化

\[数据\]它的作用

此MCP服务器将得克萨斯A&M的工程级分布PDF转换为具有13个专门功能的可查询数据库。学生可以向Claude Code提出以下问题：

• “谁是CSCE 221最好的教授？”
• “向我展示GPA高于3.7的最简单的AERO课程”
• “哪些MEEN教授的不及格率最低？”
• “给我找一些小的、高GPA的部分来提高我的GPA”

创新和关键特征

新数据源：将非结构化的PDF成绩报告转换为结构化的、可人工智能查询的数据库，从而解锁以前LLM无法访问的上下文。

情境智能:

• 13个专门针对真实学生决策模式的查询功能
• 跨学期、讲师和部门的自动聚合
• 多维筛选（平均绩点、不及格率、班级规模、成绩分布）
• 成绩趋势的时间分析和基于学期的建议

技术效率:

• 即时（\ tamu_grades_mcp

cd tamu_grades_mcp

Create virtual environment with uv

uv venv source .venv/bin/activate # On Linux/WSL

OR

.venv\Scripts\activate # On Windows

Install dependencies

uv pip install fastmcp pandas pdfplumber

### 2.验证安装

Test that the server loads correctly

python -c "import tamu_grades; print('OK Server loaded successfully!')"

您应该看到：

Loading 2047 sections... Cached stats for 729 courses Server ready! OK Server loaded successfully!

### 3.配置克劳德代码

#### 适用于WSL（推荐给Windows用户）

编辑您的Claude Code配置文件：

- **视窗**: `C:\Users\\AppData\Roaming\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

**WSL配置** （建议用于Windows）：

{ "mcpServers": { "tamu-grades": { "type": "stdio", "command": "wsl", "args": [ "bash", "-c", "cd /home/deep/tamu_grades_mcp && source .venv/bin/activate && python tamu_grades.py" ] } } }

**本机Linux配置**:

{ "mcpServers": { "tamu-grades": { "type": "stdio", "command": "bash", "args": [ "-c", "cd /path/to/tamu_grades_mcp && source .venv/bin/activate && python tamu_grades.py" ] } } }

**重要**：更新 `/home/deep/tamu_grades_mcp` 到你的实际项目路径！

### 4.重新启动克劳德代码

更新配置后，完全重新启动Claude Code（不仅仅是关闭窗口-退出应用程序）。

## \[工具\]可用的MCP功能

服务器提供13个优化查询功能：

### 1. `max_gpa_instructor(dept_code, course_num)`

找到特定课程平均绩点最高的讲师。

**示例**: `max_gpa_instructor("CSCE", "221")`

KUHNLE A (GPA: 3.592, A%: 70.4%)

______________________________________________________________________

### 2. `compare_instructors(dept_code, course_num)`

将所有教授课程的讲师与GPA和成绩分布统计数据进行比较。

**示例**: `compare_instructors("CSCE", "221")`

Instructors for CSCE-221:

1. KUHNLE A: GPA 3.592, A% 70.4%, F% 0.0%, Total Students: 27
2. HASSANIKHENAR A: GPA 3.451, A% 58.2%, F% 1.4%, Total Students: 72
3. LEYK T: GPA 3.361, A% 48.2%, F% 0.0%, Total Students: 277

...

______________________________________________________________________

### 3. `easiest_courses(department, min_gpa=3.5)`

在GPA高于门槛的部门寻找课程。

**示例**: `easiest_courses("AERO", 3.7)`

AERO-689: GPA 4.000, A% 100.0% AERO-402: GPA 3.952, A% 90.5% AERO-491: GPA 3.833, A% 83.3% ...

______________________________________________________________________

### 4. `department_overview(dept_code)`

获取按平均GPA排名的系中的所有课程。

**示例**: `department_overview("CSCE")`

CSCE Department Overview (65 courses):

1. CSCE-181: GPA 4.000, A% 100.0%, F% 0.0%
2. CSCE-410: GPA 4.000, A% 100.0%, F% 0.0%
3. CSCE-689: GPA 3.978, A% 95.6%, F% 0.0%

...

______________________________________________________________________

### 5. `instructor_profile(instructor_name)`

获取讲师教授的所有课程及其统计数据。

**示例**: `instructor_profile("LEYK")`

Profile for LEYK T (3 courses):

1. CSCE-221: GPA 3.361, A% 48.2%, F% 0.0%
2. CSCE-121: GPA 3.234, A% 42.5%, F% 2.8%
3. CSCE-312: GPA 3.189, A% 38.9%, F% 0.0%

______________________________________________________________________

### 6. `lowest_fail_rate_courses(department, limit=10)`

查找一个系中失败率最低的课程。

**示例**: `lowest_fail_rate_courses("MEEN", 5)`

Lowest fail rate courses in MEEN:

1. MEEN-689: F% 0.0%, GPA 3.944, A% 88.9%
2. MEEN-629: F% 0.0%, GPA 3.800, A% 80.0%
3. MEEN-460: F% 0.0%, GPA 3.750, A% 75.0%

...

______________________________________________________________________

### 7. `high_gpa_sections(min_gpa=3.5, min_a_percent=50.0)`

查找所有部门中同时满足GPA和A%阈值的部门。

**示例**: `high_gpa_sections(3.8, 70.0)`

Sections with GPA >= 3.8 and A% >= 70.0: AERO-689-600 (BOWMAN W): GPA 4.000, A% 100.0% CSCE-181-501 (WALKER P): GPA 4.000, A% 100.0% MEEN-689-602 (ERTURK A): GPA 4.000, A% 100.0% ...

______________________________________________________________________

### 8. `course_grade_distribution(dept_code, course_num)`

获取课程所有部分的详细A/B/C/D/F明细。

**示例**: `course_grade_distribution("CSCE", "314")`

Grade Distribution for CSCE-314: Total Students: 156 Average GPA: 3.354

A: 51.3% B: 28.8% C: 16.7% D: 1.9% F: 1.3%

Sections: 4

______________________________________________________________________

### 9. `search_by_instructor(instructor_name)`

别名为 `instructor_profile` -按讲师搜索所有课程。

______________________________________________________________________

### 10. `gpa_boosters(min_gpa=3.7, max_enrolled=30)`

寻找高GPA、小班授课的课程（GPA优化的理想选择）。

**示例**: `gpa_boosters(3.8, 25)`

GPA Boosters (GPA >= 3.8, enrollment .pdf

Examples: GPA_Dist_Fall2024.pdf, GPA_Dist_Spring2025.pdf

2. Re-parse all data

python parse_grades.py

3. Restart Claude Code to reload the data

解析器将：

- 查找所有匹配的PDF文件
- 从文件名中提取学期/年份
- 将所有数据合并到 `tamu_grades.csv` 和 `tamu_grades.json`
- 添加 `semester` 和 `year` 用于跟踪数据来源的列

## \[性能\]性能优化

服务器使用预先计算的聚合进行快速查询：

- **课程级别统计**：启动时缓存
- **讲师课程统计**：启动时缓存
- **部门统计**：启动时缓存

这意味着，即使有2000多个部分，以前需要几秒钟的查询现在也会立即返回。

**启动时间**：加载和缓存所有数据大约需要1-2秒。

## \[测试\]测试

运行测试套件以验证所有功能是否正常工作：

python test_functions.py

预期产量：

Testing TAMU Grades MCP Functions ============================================================

1. Testing easiest_courses('CSCE', 3.5):

Found 52 courses Top course: CSCE-181 with GPA 4.000

1. Testing compare_instructors('CSCE', '314'):

Found 4 instructors for CSCE-314

...

============================================================ All tests completed successfully!

## \[用法\]Claude代码中的示例用法

配置后，您可以向Claude Code提出以下问题：

**Q**：“欧安会314分部最好的选择是什么？”

**A.**：克劳德会打电话的 `compare_instructors("CSCE", "314")` 并向您展示所有按GPA排名的讲师，以及详细的统计数据。

______________________________________________________________________

**Q**：“给我找下学期的简单工程课程”

**A.**克劳德可能会打电话来 `high_gpa_sections(3.7, 60.0)` 或 `easiest_courses("MEEN", 3.5)` 这取决于你的专业。

______________________________________________________________________

**Q**：“我需要通过小班授课来提高我的平均绩点”

**A.**：克劳德打来电话 `gpa_boosters(3.8, 25)` 寻找入学人数较少的高GPA部分。

______________________________________________________________________

**Q**：“我什么时候参加欧安会221-秋季还是春季？”

**A.**：克劳德打来电话 `best_semester_to_take("CSCE", "221")` 比较各学期的GPA，并推荐最佳时间。

______________________________________________________________________

**Q**：“随着时间的推移，CSCE 314的成绩是越来越容易还是越来越难？”

**A.**：克劳德打来电话 `grade_trend_analysis("CSCE", "314")` 显示每学期的GPA趋势和整体轨迹。

## 【建筑】技术建筑

此MCP服务器遵循一个针对速度和准确性进行优化的三级管道：

### 第一阶段：数据提取（parse_grades.py）

PDF Files → pdfplumber → Raw Text → Regex Parsing → Structured CSV/JSON

- 自动发现所有 `GPA_Dist_*.pdf` 目录中的文件
- 从文件名中提取学期/年份
- 使用模式匹配分析表格成绩数据
- 输出6190+行的标准化CSV

### 第二阶段：数据预处理（tamu_grades.py启动）

CSV → pandas DataFrame → GroupBy Aggregations → In-Memory Cache

- 服务器启动时加载等级数据（约1-2秒）
- 预先计算聚合统计数据：
  - **课程级别**：平均绩点、成绩分布、总入学人数（729门课程）
  - **讲师课程**：每门课程的每位讲师统计数据
  - **部门级**：所有课程按部门分组（15个部门）
- 存储在内存中以供即时检索

### 第3阶段：查询执行（MCP工具）

Claude Query → MCP Function Call → Cache Lookup → Formatted Response

- 11个专门功能映射到常见的学生查询
- 函数对预先计算的数据执行轻量级过滤
- 在\<50ms内返回格式化的、人类可读的结果

### 为什么采用这种方法？

**效率**：预计算消除了每个查询上的冗余聚合。比较100多名教练会立即发生，而不是几秒钟。

**可扩展性**：可以处理10000多个部分，对性能的影响最小。添加新学期是一个简单的重新解析。

**准确度**：单一真相来源（PDF）→ 结构化数据→ 缓存的统计数据消除了一致性错误。

**简洁**：具有最小依赖性的纯Python（FastMCP、pandas、pdfplumber）。没有数据库，没有外部服务。

## \[故障排除\]故障排除

### 服务器未出现在Claude代码中

1. 检查一下 `claude_desktop_config.json` 位置正确
1. 验证配置中的路径是否与实际项目路径匹配
1. 确保完全退出并重新启动Claude Code（而不仅仅是关闭窗口）
1. 检查克劳德代码日志是否有错误

### 启动服务器时导入错误

Make sure you're in the virtual environment

source .venv/bin/activate

Reinstall dependencies

uv pip install fastmcp pandas pdfplumber

### “未找到数据”错误

- 验证 `tamu_grades.csv` 存在并有数据（应为~1MB）
- 检查部门代码是否大写（例如，“CSCE”，而不是“CSCE”）
- 课程编号应该是没有连字符的字符串（例如，“221”，而不是“CSCE-221”）

## \[DATA\]数据集统计

当前数据集包括：

- **章节**: 6,190
- **独特课程**: 1,105
- **学期**：4（2024年秋季、2024年春季、2025年春季和2024年夏季）
- **导师**: 1,000+
- **部门**: 15

**涵盖的部门**:

- AERO（航空航天工程）
- 生物医学工程
- 陈（化学工程）
- 计算机科学与工程
- CVEN（土木与环境工程）
- ECEN（电气与计算机工程）
- 工程总工程师
- ETID（工程技术）
- MEEN（机械工程）
- 材料科学硕士
- MUEN（多学科工程）
- 核能工程
- OCEN（海洋工程）
- PETE（石油工程）

## \[许可证\]许可证

这个项目是为了教育目的。成绩分布数据来源于德克萨斯农工大学的公共记录。

## \[贡献\]贡献

要添加新功能，请执行以下操作：

1. 将您的功能添加到 `tamu_grades.py` 随着 `@mcp.tool()` 装饰器
1. 添加带有示例的综合文档字符串
1. 将测试添加到 `test_functions.py`
1. 使用新函数更新此README

## \[链接\]链接

- [FastMCP文档](https://gofastmcp.com)
- [克劳德代码下载](https://claude.ai/download)
- [MCP协议规范](https://modelcontextprotocol.io)

______________________________________________________________________

**内置**：FastMCP、pandas、pdfplumber
**对于**：得克萨斯农工大学工程系学生