基于 MCP 的面试教练:AIMLInterviews MCP Server 实战指南

原创2026-09-23 22:08:181,906 阅读
文章标签:示例工程教程人工智能

基于 MCP 的面试教练:AIMLInterviews MCP Server 实战指南

导读

aimlinterviews-mcp 是一个基于 Model Context Protocol(MCP) 实现的面试辅导服务器,它将 MCP 兼容的 AI 助手(如 Claude Code、Codex)接入本地 AIMLInterviews 课程仓库,让 AI 助手化身为一名遵守"防剧透"原则的 ML/AI 面试教练。本文以 MCP/README.md 为核心骨架,结合仓库内的 TypeScript 源码(MCP/src)与测试用例(MCP/test),系统讲解该服务器的安装配置、八大核心工具、三个内置 Prompt、两个 MCP Resource,以及目录索引、难度/标签推断、路径安全等底层实现原理。读完本文,你将能够独立部署该 MCP 服务器,理解其"绝不剧透参考答案、绝不执行候选代码"的安全模型,并掌握如何通过 AIMLINTERVIEWS_ROOT、claude mcp add 等命令把它接入主流 MCP 客户端。


一、定位:一个基于课程库的面试教练,而不是题库备份

aimlinterviews-mcp 的核心定位可以用一句话概括:把本地 AIMLInterviews 课程目录变成 AI 助手的面试教练知识源。它提供四类核心能力(见 MCP/README.md):

  1. 发现练习题(discover practice problems):从课程 Markdown 中索引出练习题并支持多维筛选;
  2. 提供渐进式提示(provide progressive hints):分三级给出逐步深入的解题思路引导;
  3. 审查候选答案(review candidate answers):按照各领域 Rubric 点评作答质量,但不公布参考答案;
  4. 构建备考计划(build preparation plans):围绕目标岗位或目标公司生成有源码出处的研究/练习序列。

其"防剧透(no-spoilers)"设计是区别于普通题库类工具的关键,体现在三个层面:

防剧透层面 实现要点
题目检索 get_problem 只返回题目提示与来源元数据,不包含参考答案
提示机制 get_hint 仅提供逐步深入的解题过程引导,不直接给答案
答案审查 review_answer 只做点评,绝不执行候选提交的代码

这一点在 MCP/README.md 中明确声明,并且被 test/service.test.ts 等测试用例所验证:getProblem 的输出中不包含测试夹具里的 SECRET 标记内容,review_answer 的返回中明确标注 does not provide a reference answer。


二、环境要求与依赖

根据 MCP/README.md 与 package.json,运行本服务器需要满足以下条件:

要求 说明
Node.js 20 或更高版本(package.json 中 engines 字段声明 "node": ">=20",见 MCP/package.json)
本地仓库 一份 AIMLInterviews 仓库的本地克隆(服务器读取其中 README.md 与 src/ 下的公开 Markdown)
MCP 客户端 任意 MCP 兼容客户端,官方示例为 Claude Code 或 Codex

从 MCP/package.json 可以看到其运行时依赖非常精简:

  • @modelcontextprotocol/server(^2.0.0):提供 MCP v2 的 McpServer、serveStdio 等服务端基础设施;
  • zod(^4.0.0):用于定义每个工具的参数 Schema 并在调用时做校验;
  • 开发依赖 @modelcontextprotocol/client、typescript、@types/node 用于本地测试与构建。

所有源码采用 ESM 模块("type": "module"),以 TypeScript 编写,构建产物输出到 dist/ 目录。


三、快速开始:接入 Claude Code 与 Codex

3.1 克隆仓库

首先在本地克隆 AIMLInterviews 仓库(MCP/README.md):

git clone https://github.com/alirezadir/AIMLInterviews.git
cd AIMLInterviews

注意:服务器依赖 npx -y aimlinterviews-mcp 拉取并运行 npm 包,因此需要网络能访问 npm registry,并且本地有 Node.js 20+ 环境。

3.2 通过 CLI 添加 MCP 服务器

Claude Code(MCP/README.md):

claude mcp add aimlinterviews -- npx -y aimlinterviews-mcp

Codex(MCP/README.md):

codex mcp add aimlinterviews -- npx -y aimlinterviews-mcp

两种方式均通过 npx -y aimlinterviews-mcp 启动服务器进程,服务器与客户端之间通过 stdio 通信(见 src/index.ts:serveStdio(() => createServer(), ...)),错误日志统一输出到 stderr。

3.3 手动 JSON 配置与 AIMLINTERVIEWS_ROOT

服务器启动时会自动在其工作目录及其父目录中向上查找仓库克隆(查找逻辑见下文第四节)。如果客户端从其他目录启动,就需要通过 AIMLINTERVIEWS_ROOT 环境变量显式指定仓库路径(MCP/README.md):

{
  "mcpServers": {
    "aimlinterviews": {
      "command": "npx",
      "args": ["-y", "aimlinterviews-mcp"],
      "env": {
        "AIMLINTERVIEWS_ROOT": "/path/to/your/AIMLInterviews/clone"
      }
    }
  }
}

关键约束(MCP/README.md):AIMLINTERVIEWS_ROOT 必须指向仓库根目录,即同时包含 README.md 和 src/ 的目录。


四、仓库发现机制:如何定位课程源

resolveRepositoryRoot(src/repository.ts)按以下优先级依次尝试候选路径:

  1. 显式传入的 repositoryRoot 参数(如测试中 createServer({ repositoryRoot: root }));
  2. 环境变量 AIMLINTERVIEWS_ROOT;
  3. 进程当前工作目录 process.cwd()。

对每个候选路径,findRepositoryRoot(src/repository.ts)会沿目录向上最多 10 层查找,只要某层目录满足"仓库特征"即命中。仓库特征的判定由 looksLikeRepository(src/repository.ts)完成,它要求以下 6 个关键文件全部存在:

README.md
src/lc-coding.md
src/MLC/ml-coding.md
src/ml-fundamental.md
src/MLSD/ml-system-design.md
src/behavior.md

这一设计保证了"在仓库任意子目录下启动也能找到课程源"。如果三个候选路径都找不到仓库,resolveRepositoryRoot 会抛出 RepositoryConfigurationError,提示用户克隆仓库并设置 AIMLINTERVIEWS_ROOT(src/repository.ts)。

仓库定位后,服务器会:

  • 通过 git rev-parse HEAD 记录当前源码提交号(失败时回退为 "unknown",见 src/repository.ts),用于给每个题目和章节标注来源版本;
  • 递归扫描 src/ 目录下的所有 .md 文件(跳过符号链接,见 src/repository.ts),建立内存目录。

提醒(MCP/README.md):拉取课程仓库更新后需要重启 MCP 客户端,服务器才会重建内存中的目录索引。


五、八大工具详解

服务器共注册 8 个工具(MCP/README.md),全部标记为只读(readOnlyHint: true、destructiveHint: false、idempotentHint: true、openWorldHint: false,见 src/server.ts),所有工具实现在 TutorService(src/service.ts)中。

工具 用途 核心参数
get_server_status 显示仓库根目录、源码提交号与目录统计 无
list_problems 按领域、难度、标签、公司、关键词筛选练习题 area, difficulty, tag, company, query, limit
get_problem 取回题目与来源元数据,不含答案 id
get_hint 请求 1/2/3 级渐进式防剧透提示 id, level
search_curriculum 检索相关章节及其源码位置 query, area, limit
get_learning_path 基于岗位与经验水平生成学习序列 goal, experience, weeks
get_company_prep 基于岗位生成公司备考计划 company, role, weeks
review_answer 按 Rubric 点评答案,不执行代码 id, answer

5.1 get_server_status —— 服务器健康检查

无参数调用,返回加载状态信息:仓库根目录 repositoryRoot、源码提交号 sourceCommit、目录生成时间 generatedAt,以及按领域分组的题目数量统计和题目/章节总数(src/service.ts)。适合在接入后第一时间确认服务器是否正确读取到了课程库。

5.2 list_problems —— 多维筛选练习题

通过 zod 定义输入 Schema(src/server.ts):

  • area:面试领域,取 AREAS 枚举值,共 7 个(src/types.ts):general-coding、ml-coding、pytorch、ml-fundamentals、genai、system-design、behavioral;
  • difficulty:easy / medium / hard;
  • tag:标签,如 attention、ranking、evaluation、multimodal、pytorch、agents 等(完整字典见 src/catalog.ts);
  • company:源码中显式提及的公司名。识别公司名单为 Amazon、Anthropic、Apple、Google、Meta、Microsoft、Netflix、OpenAI、Roku(src/catalog.ts);
  • query:自由文本,对标题、提示、领域、标签、公司做包含匹配(matchesProblem,src/service.ts);
  • limit:返回条数,默认 20,范围 1–100。

筛选在内存中对完整目录执行(src/service.ts),结果按领域、路径、行号排序,并以 id | title | area | difficulty 的紧凑文本格式返回,同时附带结构化数据 structuredContent。若筛选结果为空,会给出"放宽条件或改用 search_curriculum"的建议。

5.3 get_problem —— 只取题目,不取答案

输入 id(list_problems 返回的稳定 ID),返回题目标题、题目提示文本与来源信息(Source: <path>:<line> @ <commit>),并在末尾附上一句辅导语:"先澄清需求、说明思路,需要时再请求第 1 级提示"(src/service.ts)。

实现层面,目录构建阶段就会把"参考答案/题解"从索引中剥离:

  • 标题匹配 /(?:reference response|solution|answer key)/i 的章节被跳过(src/catalog.ts);
  • 题目正文中的代码块被替换为占位提示 <a href="https://link.gitcode.com/i/89ef27ecb5da5f7df68c964b9b78857f" target="_blank">code scaffold omitted; inspect the source file during practice](sanitizePrompt,[src/catalog.ts)。

test/catalog.test.ts 专门断言:构建出的目录 JSON 中绝不包含测试夹具里的 SECRET_REFERENCE_IMPLEMENTATION 与 SECRET_INLINE_ANSWER。

5.4 get_hint —— 三级渐进式防剧透提示

输入 id 和 level(仅允许 1、2、3 三个字面量,src/server.ts),返回对应级别的提示。提示按顺序请求:先 1 级、再 2 级、最后 3 级。

提示内容由 getProgressiveHint(src/hints.ts)根据题目领域从 AREA_GUIDANCE 中选取,三级引导分别对应:

级别 引导主题 前缀
1 澄清需求(clarify before solving) "Clarify before solving."
2 选择并论证方案(choose and justify an approach) "Choose and justify an approach."
3 不泄露答案的验证(validate without revealing the solution) "Validate without revealing the solution."

以 ml-coding 领域为例,三级引导为:先写下张量/数组形状、期望输出与数值边界 → 把数学定义与向量化/批处理/实现细节分离 → 检查不变量、数值稳定性、空输入退化情况与每步操作成本。每个领域(从 general-coding 到 behavioral 共 7 类)都有专门编写的三级引导文案(src/hints.ts)。返回中还附带 spoilerPolicy 字段声明"本提示只提供过程引导,不提供答案或实现"(src/service.ts)。

5.5 search_curriculum —— 检索章节与源码位置

输入 query(必填)、area(可选)、limit(默认 15,范围 1–50)。实现先将查询分词,再对每个章节按"标题命中 +5 分、正文命中 +1 分"打分排序(scoreSection,src/service.ts),返回章节 ID、标题与来源位置(路径+行号)。

重要特性:search_curriculum 只返回章节位置而非答案文本,以保持防剧透工作流(src/service.ts)。特别地,pytorch-ml-coding.md 被排除在章节索引之外(src/catalog.ts),因为它的主体内容本身就是带答案的编码练习。

5.6 get_learning_path —— 按岗位与经验生成学习序列

输入参数(src/server.ts):

  • goal:六个目标之一——ml-engineer、applied-scientist、genai-engineer、research-engineer、coding-intensive、leadership;
  • experience:early / mid / senior,默认 mid;
  • weeks:计划周数,默认 4,范围 1–16。

每个目标都映射到一组按优先级排序的领域(GOAL_AREAS,src/service.ts),例如:

  • ml-engineer → general-coding → ml-coding → pytorch → ml-fundamentals → system-design → behavioral;
  • applied-scientist → ml-fundamentals → genai → ml-coding → system-design → behavioral;
  • genai-engineer → genai → pytorch → ml-coding → system-design → behavioral。

计划生成时(src/service.ts)按经验水平设定每周目标题量(early 6 题 / mid 8 题 / senior 10 题),为每个领域划分起止周、挑选目录中的题目与章节主题,并输出带来源链接的问题 ID。文本结果末尾会附带学习方法建议:"独立尝试、按顺序请求提示,48 小时内重做错题"。

5.7 get_company_prep —— 基于岗位的公司备考计划

输入 company(1–100 字符)、role(1–150 字符)、weeks(默认 4,范围 1–12)。与学习路径不同,这里通过岗位关键词推断领域组合(roleAreas,src/service.ts):岗位含 manager|director|lead|strateg 映射到 leadership 领域组合,含 research 映射到 research-engineer,含 genai|llm|agent 映射到 genai-engineer,含 scientist 映射到 applied-scientist,否则默认 ml-engineer。

输出中明确声明(src/service.ts):

"This is a curriculum-based plan inferred from the role, not a claim about current company questions."

即:该计划是基于课程内容的岗位建议,不构成对任何公司私有或当前面试题的断言(MCP/README.md)。结果末尾还建议"以计时混合模拟收尾,并直接向招聘方确认当前面试流程细节"。

5.8 review_answer —— 按 Rubric 点评,绝不执行代码

输入 id 与 answer(1–100,000 字符),输出由三部分组成的点评(src/service.ts):

  1. 自动观察(answerObservations,src/service.ts):统计回答词数以校准深度;检测回答是否显式覆盖了假设/约束(assum|constraint|requirement)、验证/边界(test|edge case|failure|validate|evaluation)、权衡/理由(trade-?off|because|reason|choose|choice),对缺失项给出提醒;
  2. 领域 Rubric 清单:通用 3 条 + 领域专属 2 条(getAnswerReviewChecklist,src/hints.ts)。例如 pytorch 领域会检查形状/dtype/设备/梯度流/训练评估行为,以及参数注册与断点保存是否正确;system-design 领域会检查数据、标签、建模、服务、评估、反馈闭环,以及规模、可靠性、漂移、安全、实验等维度;
  3. 收尾引导:先改最弱的一点,并明确"本点评有意不提供参考答案"。

返回的结构化数据中 executedCode: false、referenceAnswerProvided: false 两个字段直接印证了安全模型:候选代码被当作纯文本处理,绝不执行(MCP/README.md)。


六、内置 Prompt 与 Resource

6.1 三个 Prompt

服务器注册了 3 个 Prompt(MCP/README.md),用于将整套工具编排为完整辅导流程(实现见 src/server.ts):

Prompt 功能 触发要点
interview_tutor 苏格拉底式防剧透辅导会话 可选参数 area / difficulty / topic;指示 AI 先选一题让候选人澄清并尝试,只在被请求时按级别给提示,绝不透露参考答案或隐藏内容,作答后调用 review_answer 并追问一个问题
mock_interview 面向目标岗位的计时模拟面试 参数 company / role / level(默认 mid)/ focus;先用 get_company_prep 圈定范围,再逐题面试,从沟通、假设、正确性、权衡、验证五个维度评估
study_plan 可执行的备考计划 参数同 get_learning_path;要求保留带来源的问题 ID,包含每周重点、练习、计时模拟、复盘与 48 小时重做安排

6.2 两个 Resource

  • aimlinterviews://catalog(src/server.ts):以 JSON 形式暴露题目与章节元数据(源码提交号、生成时间、题目、章节),但序列化时剔除 prompt 与 text 字段,确保 Resource 层面同样防剧透;
  • aimlinterviews://tutor-policy(src/server.ts):以 Markdown 形式暴露防剧透辅导规则(每次只出一题、先尝试后帮助、按顺序按请求给提示、不提供参考答案与完整实现、只审推理不执行代码、引用来源路径与提交号)。

七、目录构建原理:从 Markdown 到稳定 ID

理解 buildCatalog(src/catalog.ts)有助于理解工具行为。整个流程分三步:

1. 文件发现:递归扫描 src/ 下全部 .md 文件(跳过符号链接)。

2. 问题抽取(extractProblems,src/catalog.ts):用正则解析 1–4 级标题建立标题栈,然后按四种模式识别题目:

  • 标题为 Question 的章节:以父标题为题目名,正文为提示;
  • pytorch-ml-coding.md 中的编号加粗列表项(1. **...**),且不在目录(Contents)上下文中、内容形似问题;
  • 位于 "Sample Questions / Common Questions / System Design Sample Questions" 等章节下的列表项;
  • "Priority ML coding problems" 表格中的数据行(| Problem | Why it matters | 结构)。

isQuestionLike(src/catalog.ts)通过句末问号或以 build|calculate|design|explain|how|why|what 等动词/疑问词开头来判断某行文本是否构成问题。

3. 元数据推断:

  • 领域(inferArea,src/catalog.ts):按文件路径与标题上下文推断,如路径含 pytorch-ml-coding 归为 pytorch、含 MLC/ 归为 ml-coding、含 MLSD/ 归为 system-design、behavior.md 归为 behavioral、lc-coding.md 归为 general-coding、ml-fundamental.md 中涉及 LLM/GenAI/多模态等主题的归为 genai,其余归为 ml-fundamentals;
  • 难度(inferDifficulty,src/catalog.ts):命中 advanced|expert|hard|distributed|flashattention|grpo|rlhf|vla|diffusion 等关键词判定为 hard;system-design 领域或命中 medium|training loop|attention|pca|decision tree 判定为 medium;否则 easy;
  • 标签(inferTags,src/catalog.ts):从 10 个标签正则字典(algorithms、agents、attention、behavioral、coding、evaluation、llm、multimodal、pytorch、ranking、training)中按关键词匹配;
  • 公司:对 9 家知名公司名单做词边界匹配。

稳定 ID 的生成(makeId,src/catalog.ts):格式为 aiml:problem:<area>:<slug>-<hash>,其中 <slug> 由标题做小写化、NFKD 归一化、非字母数字替换为连字符后截取 52 字符,<hash> 是对 路径 + 标题 做 SHA-256 后取前 8 位十六进制。因此只要源码路径与标题不变,ID 就稳定不变。test/catalog.test.ts 验证了两次构建产生的 ID 序列完全一致,且所有 ID 均以 aiml:problem: 开头。

最后按 ID 去重、按领域/路径/行号排序(src/catalog.ts)。


八、内容与安全模型

服务器将安全模型显式写在 MCP/README.md 中,每一条都有源码佐证:

安全承诺 源码依据
只读 src/ 下的公开 Markdown,不内置重复题库 src/repository.ts 只扫描 src/ 下的 .md
稳定目录 ID 由源码路径与标题派生 makeId(src/catalog.ts)
每个题目/章节都带来源路径、行号与 Git 提交 Problem.sourcePath/sourceLine/sourceCommit(src/types.ts)
仓库读取做路径限定、大小限制、跳过符号链接 readRepositoryFile(src/repository.ts):解析后必须仍在仓库根内(拒绝 ../ 逃逸)、单文件上限 2 MB(MAX_SOURCE_BYTES)、walk 跳过符号链接
公司计划是课程型岗位建议,不声称掌握公司私有/当前面试题 getCompanyPrep 的显式声明(src/service.ts)
候选代码作为文本处理,绝不执行 review_answer 返回 executedCode: false(src/service.ts)
MCP 协议消息走 stdout,诊断走 stderr src/index.ts

路径穿越防护有专门测试:向 readRepositoryFile(root, "../outside.md") 传入越界相对路径会抛出 Refusing to read outside repository root 错误(test/catalog.test.ts)。


九、开发、测试与发布

9.1 本地开发

在 MCP/ 目录下执行(MCP/README.md):

cd MCP
npm install
npm test
npm pack --dry-run
  • npm test 实际执行 npm run build && node --test dist/test/*.test.js(MCP/package.json),即先编译再运行 Node 原生测试;
  • npm pack --dry-run 用于预览发布包内容(dist/src/、README.md、LICENSE)。

9.2 直接运行与交互式调试

从仓库根目录直接运行编译后的服务器(此时 AIMLINTERVIEWS_ROOT 指向仓库根):

AIMLINTERVIEWS_ROOT="$(cd .. && pwd)" npm start

或用 MCP Inspector 交互式调试:

npm run inspect

npm run inspect 底层调用 npx @modelcontextprotocol/inspector node dist/src/index.js(MCP/package.json),会启动一个可视化调试界面,可以逐个调用工具、查看 Schema 与返回结果。

9.3 测试覆盖

仓库的测试用 Node 内置测试运行器(node:test)编写,覆盖三个层面:

  • test/catalog.test.ts:目录构建的稳定性(两次构建 ID 一致)、防剧透(不含 SECRET 标记)、路径穿越防护、仓库根解析;
  • test/service.test.ts:TutorService 全流程(发现、取题、三级提示、章节搜索、学习路径、公司计划、答案点评),以及 MCP v2 工具 Schema 注册(toolInputSchemaJson)与未知 ID 返回 isError: true;
  • test/protocol.test.ts:用 @modelcontextprotocol/client + InMemoryTransport 建立真实 MCP v2 客户端-服务端会话,验证 listTools 能列出全部 8 个工具、callTool 能成功调用 list_problems。

测试使用的夹具仓库由 test/fixture.ts 动态生成到临时目录,包含覆盖全部 7 个领域的精简 Markdown 文件,其中特意埋入了 SECRET_REFERENCE_IMPLEMENTATION 与 SECRET_INLINE_ANSWER 以验证防剧透逻辑。

9.4 发布

发布到 npm 需要具有 aimlinterviews-mcp 包权限(MCP/README.md):

npm login
npm publish --access public

prepack 脚本会在打包前自动运行完整测试(MCP/package.json),确保发布内容通过验证。


十、设计参考与扩展方向

MCP/README.md 声明其工具分类与辅导工作流参考了 TorchLeet MCP server 的设计思路,但本实现是原创的:它直接读取 AIMLInterviews 课程库而非复制 TorchLeet 的内容。这一"以公开课程为知识源、以 MCP 协议为接口、以防剧透为行为准则"的模式,可以自然扩展到其他面试辅导场景——例如将 AREAS 扩展新的领域、在 inferTags 字典中补充新的标签、或在 GOAL_AREAS 中增加新的岗位画像,均无需改动工具接口即可生效。


总结

aimlinterviews-mcp 通过 8 个只读工具、3 个 Prompt 与 2 个 Resource,把 AIMLInterviews 课程仓库封装成一个安全、可追溯、防剧透的 ML/AI 面试教练。其核心价值在于:目录与课程仓库解耦(不内置题库)、内容可溯源(路径+行号+提交号)、行为有边界(不泄露答案、不执行代码)。无论是接入 Claude Code / Codex 立即开始练习,还是阅读 MCP/src 源码理解目录构建与安全实现,本仓库都提供了完整可验证的参考实现。

登录后查看全文
AIMLInterviews