使用说明

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

技术效率:

即时（<50ms）查询响应的预先计算的课程和讲师统计数据
可处理6190+节而不会降低性能
智能缓存将冗余计算减少95%

现实世界公用事业：解决了每学期数万名学生面临的实际问题，而不是玩具演示或人为的用例。

[文件]当前数据集

6190节课程 横跨 1105独特课程
4个学期：2024年秋季，2024年春季，2025年春季，2024夏季
15个工程部门 得克萨斯农工大学
包括平均绩点、A/B/C/D/F百分比、入学数据、讲师信息和学期/年
来源： GPA_Dist_Fall2024.pdf, GPA_Dist_Spring2024.pdf, GPA_Dist_Spring2025.pdf, GPA_Dist_Summer2024.pdf

[SETUP]安装说明

先决条件

Python 3.10+
紫外线（Python包管理器）
克劳德代码（Windows或WSL）

1.克隆和设置Python环境

cd /path/to/your/workspace
git clone <repository-url> 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\<YourName>\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 <= 25):
AERO-689-600 (BOWMAN W): GPA 4.000, A% 100.0%, Enrollment: 9
CSCE-181-501 (WALKER P): GPA 4.000, A% 100.0%, Enrollment: 18
MEEN-460-200 (SALDANA C): GPA 3.833, A% 83.3%, Enrollment: 6
...

11. `safest_courses(max_fail_rate=5.0)`

查找所有部门中失败率低于阈值的课程。

示例: safest_courses(2.0)

Safest courses (F% <= 2.0%):
1. AERO-689: F% 0.0%, GPA 3.944, A% 88.9%
2. CSCE-181: F% 0.0%, GPA 4.000, A% 100.0%
3. MEEN-689: F% 0.0%, GPA 3.944, A% 88.9%
...

12. `best_semester_to_take(dept_code, course_num)`

根据历史GPA数据分析哪个学期（秋季、春季、夏季）最适合修课。

示例: best_semester_to_take("CSCE", "221")

Best Semester Analysis for CSCE-221
==================================================
RECOMMENDATION: Take in Fall semester
Best Semester GPA: 3.592
GPA Difference: 0.231 points between best and worst

Semester Comparison:

#1 Fall: GPA 3.592, A% 70.4%, F% 0.0%, D% 0.0% ⭐ BEST
    Total Students: 27, Avg per Section: 27.0

#2 Spring: GPA 3.361, A% 48.2%, F% 0.0%, D% 0.0%
    Total Students: 277, Avg per Section: 138.5

💡 Significant difference detected! Taking Fall could improve your grade.

13. `grade_trend_analysis(dept_code, course_num)`

分析一门课程的成绩趋势，看看GPA是在提高、下降还是稳定。

示例: grade_trend_analysis("CSCE", "314")

Grade Trend Analysis for CSCE-314
==================================================
Overall Trend: IMPROVING ↗
GPA Change: up by 0.285 points
Average GPA: 3.354

Semester-by-Semester Breakdown:

Spring 2024: GPA 3.212, A% 45.0%, F% 2.5%, Students: 80
Fall 2024: GPA 3.497, A% 57.5%, F% 0.0%, Students: 76 (+0.285)

项目结构

tamu_grades_mcp/
├── README.md                          # This file
├── tamu_grades.py                     # Main MCP server (optimized)
├── tamu_grades.csv                    # Parsed grade data (2047 sections)
├── tamu_grades.json                   # Same data in JSON format
├── TAMU_Grades_per_class.pdf          # Source PDF
├── parse_grades.py                    # PDF parser script
├── claude-config-windows.json         # Example Claude Code config
├── test_functions.py                  # Test suite for all functions
└── .venv/                             # Python virtual environment

[更新]更新数据集

解析器自动处理所有 GPA_Dist_*.pdf 目录中的文件。

当您获得新的成绩分布PDF时：

# 1. Add new PDF files to the directory
# Make sure they follow the naming pattern: GPA_Dist_<Semester><Year>.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

2. 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代码中

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

启动服务器时导入错误

# 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（石油工程）

[许可证]许可证

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

[贡献]贡献

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

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

[链接]链接

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

使用说明

TAMU等级分配MCP服务器

为什么这很重要

[数据]它的作用

创新和关键特征

[文件]当前数据集

[SETUP]安装说明

先决条件

1.克隆和设置Python环境

2.验证安装

3.配置克劳德代码

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

4.重新启动克劳德代码

[工具]可用的MCP功能

1. max_gpa_instructor(dept_code, course_num)

2. compare_instructors(dept_code, course_num)

3. easiest_courses(department, min_gpa=3.5)

4. department_overview(dept_code)

5. instructor_profile(instructor_name)

6. lowest_fail_rate_courses(department, limit=10)

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

8. course_grade_distribution(dept_code, course_num)

9. search_by_instructor(instructor_name)

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

11. safest_courses(max_fail_rate=5.0)

12. best_semester_to_take(dept_code, course_num)

13. grade_trend_analysis(dept_code, course_num)