学生管理 MCP

stuManagementMcp 是一个基于 TypeScript 和 npm 的本地 stdio MCP 服务，提供平均分计算、成绩评价和学生姓名查询工具。

环境要求

• Node.js 22 或更高版本

• npm

Related MCP server: mcp-poc

安装与构建

在项目目录执行：

npm install
npm run build

构建后的服务入口为 dist/index.js。

使用 MCP Inspector 测试

先构建项目，再启动 Inspector：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

浏览器打开命令输出的 Inspector 地址，在 Tools 页面选择工具并填写参数。调试信息使用 console.error 输出，可在 Inspector 右侧的 Console 标签中查看。

注意：stdio MCP 的标准输出用于 MCP 协议通信，不要使用 console.log 打印调试信息，否则可能导致协议通信异常。

工具列表

calculate_average

计算三个数值的平均值。

输入：

{
  "a": 1,
  "b": 2,
  "c": 3
}

输出：

{
  "average": 2
}

evaluate_score

根据 0-100 的整数分数返回成绩评价。非整数或超出范围的输入会被拒绝。

输入：

{
  "score": 85
}

输出：

{
  "result": "良好"
}

评价规则：

get_student_name

根据固定学号查询学生姓名。

输入：

{
  "studentId": 10001
}

输出：

{
  "name": "李四"
}

未找到学号时，工具返回“未找到该用户”。

get_joke

从公开接口获取笑话。type 可选值为 random（随机笑话）、cold（冷笑话）和 duanzi（段子）。

输入：

{
  "type": "cold"
}

输出中的 joke 保留上游笑话接口返回的原始 JSON 内容。接口访问失败时，工具返回“获取笑话失败”。

get_call_logs_by_date

查询某一天的调用日志。date 必填，格式为 YYYY-MM-DD；可选 keyword 在整条日志中模糊匹配；可选 success 用于筛选成功或失败的调用。结果按时间倒序返回，最多 100 条。

{
  "date": "2026-08-12",
  "keyword": "get_student_name",
  "success": true
}

get_call_logs_by_range

查询闭区间日期范围内的调用日志。startDate 和 endDate 必填，格式均为 YYYY-MM-DD；其余筛选参数与单日查询相同。开始日期不能晚于结束日期。

{
  "startDate": "2026-08-11",
  "endDate": "2026-08-12",
  "success": false
}

调用埋点日志

每次进入工具业务处理的调用都会追加记录到：

log/YYYY-MM-DD/calls.jsonl

日期和时间使用中国大陆时区（Asia/Shanghai），时间格式为 YYYY-MM-DD HH:mm:ss.SSS。每行是一条独立 JSON 记录，包含工具名、调用参数、成功状态、错误信息和耗时（毫秒）。

示例：

{"timestamp":"2026-08-11 22:42:07.014","tool":"calculate_average","parameters":{"a":2,"b":3,"c":5},"success":true,"durationMs":20.01}

参数 schema 校验失败的请求不会进入业务代码，因此不会写入埋点日志。日志写入失败不会影响工具的正常返回。

宿舍规则知识库

知识库源文档为 docs/601宿舍管理规则.md，分块逻辑位于 src/rag/：优先按 Markdown 标题拆分，过长内容再按约 500 个字符均匀分块，并保留约 80 个字符的重叠上下文。

本版本使用本地关键词检索，不依赖 Docker、Python、ChromaDB 或 embedding 模型。索引数据保存为 src/db/dorm-rules-index.json。先调用 index_dorm_rules 将文档写入知识库；成功时返回分块数量。之后调用 search_dorm_rules 并传入问题：

{
  "query": "周五晚上需要熄灯吗？"
}

检索会提取问题中的中文词语、中文双字词和英文单词，在分块内容中进行匹配并按命中次数排序。后续可在不影响现有工具的前提下新增语义 embedding 检索工具。

在 CC Switch 中配置 stdio MCP

在 CC Switch 新增 MCP 页面中：

• MCP 标题：stuManagementMcp

• 显示名称：学生管理 MCP

• 启用到应用：勾选 Codex

在“完整的 JSON 配置”中填写：

{
  "type": "stdio",
  "command": "D:\\Program Files (x86)\\coding\\nodejs\\node.exe",
  "args": [
    "D:\\workspace\\mcp\\dist\\index.js"
  ]
}

添加配置后，完全退出并重启 Codex Desktop。之后直接使用自然语言请求调用工具，例如“调用 get_student_name 查询 studentId=10001”。修改 src/index.ts 后，需要再次执行 npm run build，然后重启 Codex Desktop 以加载新的构建产物。