# 陶航爱学习 (taohang-aixuexi)

这是我第一次做mcp，我只是一个普通学生，做的如果有不好的地方，请各位多多见谅，我真的燃尽了，一个半月做的，很多东西都比较生疏与粗糙，各位轻点骂！拜托拜托！
给「帮初学者改 C 语言作业」场景用的 MCP server。跑在 Windows 上，建议搭配vscode的AI插件使用，我用的是hermes，配的deepseek V4 pro，大家根据自己的预算来弄比较好。
专门伺候 MinGW + GBK 中文注释这一套学生生态，让任何支持 MCP 的 AI
客户端（Claude Desktop / Cursor / VS Code / Hermes ...）都能安全地
读、改、编译、运行学生写的 .c 文件。

原名 c-tutor-mcp。GitHub 仓库名限 ASCII，所以叫 taohang-aixuexi，中文显示名「陶航爱学习」。
从一次次的真实家教经验里沉淀出来：GBK/UTF-8 编码自动探测、注释掉
的旧版本自动折叠、编译/运行排雷（残留进程锁 exe、死循环卡死）、
`.bak` 自动备份，外加 `get_playbook`（整套"找错手册"）和 `archive_error_note`（改完的坑归档进 Obsidian 错题本）。

> `archive_error_note` 是个人工作流：哥哥（用户）要求每次改完把新坑
> 按 现象→原因→❌错/✅对代码→口诀 追加到 `D:/Knowledgebase/Intelligence/TH的报错归纳/`
> 对应分篇 .md，只追加、先查重。别的机器/人用不到可以无视这个工具。

外加一个 `get_playbook` 把整套"找错手册"（铁律 +
常见坑清单 + 工作流）直接喂给陌生的 AI 客户端。

## 工具

| 工具 | 干什么 |
|---|---|
| `list_c_files` | 列目录下 .c/.exe（按修改时间倒序），帮定位作业 |
| `read_c_source` | GBK/UTF-8 自动探测读取；active 视图折叠注释、full 视图带行号 |
| `write_c_source` | 按原编码写回（GBK 文件仍写 GBK），首次写入自动备份 `.bak` |
| `compile_c` | gcc 编译，自动带 `-finput-charset=GBK -fexec-charset=UTF-8` |
| `run_c_exe` | 带超时跑 exe 并喂 stdin（防死循环卡死），UTF-8 解码输出 |
| `kill_stray_processes` | 清残留进程（gdb 调试残留等），解锁被占用的 exe |
| `archive_error_note` | 错题知识点归档进 Obsidian 错题本（只追加不覆盖，UTF-8） |
| `get_playbook` | 返回完整操作手册：铁律、编码规范、工作流、13 条常见坑 |

## 为什么有这些工具

学生作业的 .c 文件全是 GBK 编码的中文注释，而且习惯把旧版本整段
`//` 注释掉留在文件里。直接让 AI 读文件会乱码、会改到注释里的旧版
本。这些工具把坑都填了：编码探测、注释折叠、编译参数、超时保护、
自动备份。

## 环境要求

- Windows + [MinGW-w64](https://github.com/niXman/mingw-builds-binaries/releases)（`gcc` 在 PATH 里）
- Python 3.10+（建议用 [uv](https://docs.astral.sh/uv/) 管理）

## 安装

```bash
git clone <本仓库地址>
cd c-tutor-mcp
uv sync          # 或: uv pip install --python .venv/Scripts/python.exe "mcp>=1.2,<2"
```

## 接入客户端

所有客户端都是同一套配置：让 MCP 用 venv 里的 python 启动 `server.py`。

```json
{
  "mcpServers": {
    "c-tutor": {
      "command": "C:/绝对路径/c-tutor-mcp/.venv/Scripts/python.exe",
      "args": ["C:/绝对路径/c-tutor-mcp/server.py"]
    }
  }
}
```

配置放哪：

- **Claude Desktop**：`claude_desktop_config.json`（应用设置里可打开）
- **Cursor**：项目根 `.cursor/mcp.json`
- **VS Code**：`.vscode/mcp.json`（或装 Roo Code / Cline 后在其 MCP 设置里加）
- **通用**：任何支持 stdio MCP 的客户端，command + args 如上

## 使用提示（建议贴给 AI 客户端）

> 我要改 C 作业。先调 get_playbook 拿操作手册，再 list_c_files 找文件，
> read_c_source 看代码。没让我改就别写文件；改的时候加 // [改] 注释，
> 改完 compile_c 验证，run_c_exe 喂输入实测。

## 设计要点

- **单文件 server.py**，无框架，直接 `python server.py` 跑 stdio。
- **铁律进工具**：`write_c_source` 自动备份；`compile_c` 失败提示
  先清进程；`run_c_exe` 默认 10s 超时，死循环杀不掉就报错让你清残留。
- **playbook 是灵魂**：AI 客户端没有你的记忆，`get_playbook` 一次调用
  就把"没叫改别改 / 变量名禁用 L X l 1 x / 13 条常见坑"全给它。

## 自测

```bash
.venv/Scripts/python.exe smoke_test/test_mcp.py
```

会走完整 MCP 协议：读 GBK 文件 → 注释折叠 → 编译 → 带输入运行 →
改写备份 → 编码保持。全绿输出 `ALL OK`。

## 目录

```
server.py            MCP server（全部逻辑，单文件）
pyproject.toml       依赖声明（mcp>=1.2,<2）
smoke_test/          自测：demo_hw.c 样例 + test_mcp.py 协议测试
```

## 许可

MIT