Study Assistant

一个本地 Model Context Protocol (MCP) 服务器，将教学大纲文档转换为可搜索的学习知识库。服务器读取 files/ementas 中的文档，提取其文本，并使用 Genkit 与 Ollama Cloud 生成摘要和结构化详情。

架构

本仓库是一个 pnpm monorepo。mcp 包包含 Express 和 MCP 服务器，而 files/ementas 是唯一向工具暴露的文档目录。

服务器绑定到 127.0.0.1，并提供以下端点：

• GET /health：进程健康状态，不包含机密或提供方详情。

• /mcp：无状态的 MCP Streamable HTTP 端点。

• list_ementas：列出支持的文件及其元数据和缓存摘要。

• get_ementa：返回提取的文本和结构化的教学大纲详情。

支持的格式为 PDF、DOCX、Markdown 和纯文本。符号链接、路径和不支持的扩展名将被拒绝。

Related MCP server: Educational Tutor MCP Server

要求

• Node.js 20 或更高版本。

• pnpm 10（Corepack 可以提供固定版本）。

• Ollama Cloud API 密钥。

设置

从仓库根目录安装依赖：

corepack pnpm install

将 mcp/.env.example 复制到仓库根目录的 .env 或 mcp/.env，然后提供 API 密钥：

OLLAMA_API_KEY=your-key

默认模型是 gpt-oss:120b。可选设置如下：

OLLAMA_MODEL=gpt-oss:120b
OLLAMA_BASE_URL=https://ollama.com
OLLAMA_TIMEOUT_MS=60000
MCP_PORT=3000

环境文件会被 Git 忽略。切勿提交 API 密钥。

无论 pnpm 从哪个目录启动该包，应用程序都会显式解析这两个位置。已有的系统环境变量优先；当两个文件定义了相同的变量时，mcp/.env 优先于根目录的 .env。

将教学大纲文件直接放在 files/ementas 中，然后启动开发服务器：

corepack pnpm dev

MCP 端点将在 http://127.0.0.1:3000/mcp 上可用。

连接 Codex

服务器运行后，在本地 Codex 客户端中注册其 URL：

codex mcp add studyAssistant --url http://127.0.0.1:3000/mcp

等效的 Codex 配置：

[mcp_servers.studyAssistant]
url = "http://127.0.0.1:3000/mcp"

此 localhost 端点供本地 Codex 客户端使用，不会暴露给远程 ChatGPT 客户端。

命令

从仓库根目录运行以下命令：

corepack pnpm dev       # Watch and run the TypeScript server
corepack pnpm build     # Build the production JavaScript
corepack pnpm start     # Run the compiled server
corepack pnpm typecheck # Check strict TypeScript types
corepack pnpm lint      # Run ESLint
corepack pnpm test      # Run the Vitest suite

dev 和 build 从不运行测试套件。生产编译也会排除 src/__tests__，因此测试夹具和模拟对象无法被服务器加载，也不会输出到 dist。

生成的分析结果存储在 .cache/ementas.json 中。当文档的大小或修改时间发生变化时，缓存条目将失效。如果 Ollama Cloud 暂时不可用，有效的缓存结果仍然可以使用。

安全与故障行为

API 密钥从环境中加载，并且只会在 Ollama 授权标头中发送。它不会包含在健康检查响应、MCP 响应或应用程序日志中。云请求设有超时，并会重试瞬时的 429、500 和 502 故障。在 list_ementas 中，单个文件的失败会被隔离；get_ementa 会报告 MCP 工具错误。