# 学生管理 MCP

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

## 环境要求

- Node.js 22 或更高版本
- npm

## 安装与构建

在项目目录执行：

```powershell
npm install
npm run build
```

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

## 使用 MCP Inspector 测试

先构建项目，再启动 Inspector：

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

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

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

<img width="2827" height="1402" alt="image" src="https://github.com/user-attachments/assets/cba72265-d0c2-4d4c-a63b-ed64642bbcd0" />


## 工具列表

### calculate_average

计算三个数值的平均值。

输入：

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

输出：

```json
{
  "average": 2
}
```

### evaluate_score

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

输入：

```json
{
  "score": 85
}
```

输出：

```json
{
  "result": "良好"
}
```

评价规则：

| 分数范围 | 评价 |
| --- | --- |
| 0-59 | 不及格 |
| 60-70 | 及格 |
| 71-89 | 良好 |
| 90-100 | 优秀 |

<img width="1566" height="640" alt="image" src="https://github.com/user-attachments/assets/e7733620-e0f6-45a4-ab82-85ebe850c73f" />


### get_student_name

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

| 学号 | 姓名 |
| --- | --- |
| 10000 | 张三 |
| 10001 | 李四 |
| 10002 | 王五 |
| 10003 | 赵六 |
| 10004 | 钱七 |

输入：

```json
{
  "studentId": 10001
}
```

输出：

```json
{
  "name": "李四"
}
```

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

<img width="1638" height="386" alt="image" src="https://github.com/user-attachments/assets/d04b20a6-ba5f-471d-9c31-5c5bbbd17728" />


### get_joke

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

输入：

```json
{
  "type": "cold"
}
```

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

<img width="1561" height="443" alt="image" src="https://github.com/user-attachments/assets/5f1f18dc-90d7-458a-9409-4a68bb5894c3" />


### get_call_logs_by_date

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

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

### get_call_logs_by_range

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

```json
{
  "startDate": "2026-08-11",
  "endDate": "2026-08-12",
  "success": false
}
```
<img width="1548" height="1234" alt="image" src="https://github.com/user-attachments/assets/4d76c964-7511-4e63-99ab-3ac1f01e0847" />


## 调用埋点日志

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

```text
log/YYYY-MM-DD/calls.jsonl
```

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

示例：

```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 校验失败的请求不会进入业务代码，因此不会写入埋点日志。日志写入失败不会影响工具的正常返回。

<img width="2803" height="595" alt="image" src="https://github.com/user-attachments/assets/ad986e5a-ea4b-4f20-ba29-947625a3b25c" />

## 宿舍规则知识库

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

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

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

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

<img width="1936" height="1213" alt="image" src="https://github.com/user-attachments/assets/51fd9fe3-ba69-4927-9883-6192f2b9a599" />

<img width="1399" height="473" alt="image" src="https://github.com/user-attachments/assets/977319bb-e7ea-427d-8c32-2456436a1563" />


## 在 CC Switch 中配置 stdio MCP

在 CC Switch 新增 MCP 页面中：

- MCP 标题：`stuManagementMcp`
- 显示名称：`学生管理 MCP`
- 启用到应用：勾选 `Codex`

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

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

<img width="1693" height="1357" alt="image" src="https://github.com/user-attachments/assets/64cc9317-e7ad-4029-a39d-bcb14ca58e7a" />


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