tchMaterial-parser-mcp

为 happycola233/tchMaterial-parser 提供 MCP（Model Context Protocol）适配层，使 AI 客户端可以调用教材搜索、解析与下载等能力。

本项目采用 wrapper repository + Git submodule 结构。上游 tchMaterial-parser 保持独立，不把 MCP 逻辑侵入上游源码。

目录

tchMaterial-parser-mcp/
├── upstream/
│   └── tchMaterial-parser/       # 官方仓库 Git submodule
├── src/
│   └── tchmaterial_parser_mcp/
│       ├── adapters.py           # 上游兼容边界
│       ├── schemas.py            # MCP 稳定数据结构
│       ├── tools.py              # MCP tools
│       └── server.py             # MCP server
├── tests/
├── docs/
└── scripts/

Related MCP server: Moodle MCP Server

克隆

git clone --recurse-submodules <this-repository-url>
cd tchMaterial-parser-mcp

如果已经普通 clone：

git submodule update --init --recursive

初始化

./scripts/setup.sh

脚本会初始化 submodule、创建 .venv、安装 MCP SDK 和本项目，并运行测试。 同时会以 editable 模式安装当前 submodule，因此 MCP 使用的就是外层仓库固定的上游 commit。

启动本地 stdio MCP Server：

./scripts/run-mcp.sh

该命令正常启动后不会打印业务输出，而是等待 MCP Host 通过 stdin/stdout 通信。

运行不下载文件的在线冒烟测试：

./scripts/smoke-live.sh

上游更新

./scripts/update-upstream.sh

脚本会把 submodule 更新到官方 main 最新提交，然后运行上游兼容性测试。外层仓库最终只记录新的 submodule commit 指针。

下载目录

默认下载到：

~/Downloads/tchMaterial-parser

可以通过环境变量修改：

TCHMATERIAL_MCP_DOWNLOAD_DIR=/path/to/materials

download_material 不接受任意输出目录参数，避免模型把文件写到未授权的系统位置。

Codex

本地 stdio 启动命令为：

/home/cislunar/App/tchMaterial-parser-mcp/scripts/run-mcp.sh

推荐给下载 tool 配置较长超时时间，因为大体积 PDF 可能超过普通 MCP tool 的默认超时。

详细约束见：

• docs/architecture.md

• docs/upstream-maintenance.md

• docs/mcp-tools.md

• THIRD_PARTY_NOTICES.md

当前状态

第一版已提供 search_materials、get_material、resolve_material、download_material 四个 MCP Tool，并使用官方 MCP Python SDK v2 的 stdio transport。download_material 默认只下载 PDF；如果教材还包含 MP3 等关联资源，推荐先由 resolve_material 检查并询问用户是否需要一起下载，用户未特别要求时仍保持 PDF-only。