FAQ RAG MCP Server

一个为 Glean Solutions Engineering 技术练习特意打造的小型检索增强生成（RAG）应用。它为提供的 FAQ Markdown 文件建立索引，通过余弦相似度检索相关段落，经由 LLM 生成有依据的答案，并将结果作为一个本地 MCP 工具 ask_faq 暴露出来。

该项目完全跨平台：所有设置和运行命令都使用 uv，并且在 Windows、macOS 和 Linux 上完全相同。要把这个交给使用 Claude Code 的 Windows 用户？ 请从 START_HERE_WINDOWS.md 开始。仓库包含一个 CLAUDE.md 设置手册（Claude Code 会自动读取）以及一个可移植的项目级 .mcp.json 定义，用于 faq-rag 服务器。

三十秒说明

在进程启动时，Python 读取 FAQ 文件，将它们切分为大约 200 字符的块，创建嵌入向量，对其进行归一化，并将索引缓存在内存中。对于每个问题，它对问题进行嵌入，用余弦相似度对块进行排序，将最佳的四段文本块发送给配置好的 LLM，并且只返回最终的答案和源文件名。

flowchart LR
  A[FAQ Markdown files] --> B[~200-character chunks]
  B --> C[Document embeddings cached in RAM]
  Q[Question] --> D[Query embedding]
  C --> E[Cosine similarity]
  D --> E
  E --> F[Top 4 text chunks]
  F --> G[Grounded LLM generation]
  G --> H[answer + sources]
  H --> I[MCP client]

嵌入向量仅用于定位段落。LLM 收到的是原始问题和检索到的文本，而不是原始的嵌入向量。

Related MCP server: faq-rag

确切的 MCP 契约

工具：ask_faq

输入：

{
  "question": "How do I reset my password?",
  "top_k": 4
}

输出——没有额外的键：

{
  "answer": "Use the reset link on the login page [faq_auth.md].",
  "sources": ["faq_auth.md", "faq_sso.md"]
}

top_k 接受从 1 到 10 的整数，默认值为 4。

为什么选择 MCP 而不是提供的 HTTP 选项？

无论采用哪种封装，RAG 核心都是一样的。选择 MCP 是因为 AI 客户端可以发现工具模式、决定何时调用它、启动本地 Python 进程，并接收结构化结果，而无需自定义 HTTP 客户端、端口、URL 或健康检查端点。MCP 提高了互操作性；它本身并不会提高检索质量。

此实现使用任务要求的 stdio 传输方式。MCP 客户端将 mcp_server.py 作为本地子进程启动，并通过该进程的标准输入和输出交换 MCP 消息。服务器不会向 stdout 写入普通日志，因为该通道预留给协议流量使用。

设置（任何操作系统：Windows、macOS、Linux）

要求：

• Git

• uv — 它会自动下载兼容的 Python，因此无需单独安装 Python。Windows：winget install -e --id astral-sh.uv；macOS：brew install uv。

• 一个具有可用 API 额度的 OpenAI API 密钥

• 一个 MCP 客户端，例如 Claude Code 或 Cursor

这些命令在 PowerShell、zsh 和 bash 中是相同的：

git clone https://github.com/cq2wgwtzb5-lgtm/glean-faq-rag-mcp.git
cd glean-faq-rag-mcp
uv sync

通过复制 .env.example 来创建 .env.local，然后在编辑器中把 API 密钥添加到其中：

OPENAI_API_KEY=your_key_here

.env.local 已被 Git 忽略。切勿提交或分享它。

运行确定性测试（不调用 API）：

uv run pytest -q

在添加 MCP 之前，运行一次直接的端到端冒烟测试：

uv run rag_core.py

当会话在此文件夹中启动时，Claude Code 会自动发现已检入的 .mcp.json。按照 docs/WINDOWS_MCP_SETUP.md 中的步骤来批准、验证并调用它（这些步骤适用于所有操作系统）。Windows 用户也可以运行 setup_windows.ps1，它封装了相同的 uv 命令。

在机器上的任何聊天会话中使用它

项目级的 .mcp.json 仅在此文件夹内启动的会话中加载。要使 ask_faq 在机器上的每个 Claude Code 会话中都可用，请在用户范围内注册一次服务器，并使用克隆的绝对路径（在每种操作系统上命令相同）：

claude mcp add --scope user faq-rag -- uv run --directory "<absolute path to this repo>" mcp_server.py

仓库内的会话继续使用项目级条目；其他所有会话使用用户级条目。使用 claude mcp remove --scope user faq-rag 将其移除。

评估

单元测试使用确定性的模拟嵌入，并且不进行模型调用：

uv run pytest -q

实时评估器针对实际的模型 API 运行五个代表性问题，并检查预期的来源、必需的事实以及弃权行为：

uv run evaluate.py --output eval-results.json

eval-results.json 被有意忽略，因为模型输出和账户配置会有所不同。请在面试期间截图保存该报告或进行屏幕共享。

重要的设计决策

内存中的 NumPy 索引

提供的语料库只产生少量块。向量数据库会增加部署和审查的复杂性，而不会改善这个结果。归一化的 NumPy 向量使余弦相似度成为一个简单的矩阵-向量乘积。

边界感知的分块

目标仍然是大约 200 字符，正如要求的那样。该实现优先选择段落、行、句子和单词边界，这样文本就不会仅仅为了达到精确的数字而在任意位置被切断。

启动时的一次性嵌入处理

文档嵌入在进程启动时生成一次，并缓存在 RAM 中。每个问题都会获得一个全新的查询嵌入。该缓存是共享的语料库数据——不是对话或用户会话记忆。当进程退出时，缓存消失，并在下次启动时重建。

有依据的生成与引用

生成提示词将模型限制在检索到的 FAQ 上下文中，要求精确的文件名引用，并指示模型在 FAQ 没有回答问题时要明确说明。响应的 sources 列表保持检索顺序，并且只包含来自检索到的块的文件名。

明确的失败行为

当缺少 OPENAI_API_KEY 时，应用程序会立即失败；它会拒绝空白问题和无效的 top_k，使用 30 秒的模型超时，并允许两次 SDK 重试。错误仍然是 MCP 错误，而不是杜撰的 FAQ 答案。

已知限制与生产演进

此练习有意省略了持久化索引、增量摄取、访问控制、混合词法检索、重排序、新鲜度和权威性信号、审计日志以及按用户个性化。

在企业系统中，必须在检索之前强制执行权限，这样未经授权的文本就永远不会进入模型上下文。搜索质量还应使用词法、语义、新鲜度、权威性和图谱信号，而不仅仅是余弦相似度。这些是核心的生产关注点，但为三个本地文件实现它们会违背练习对轻量级解决方案的要求。

仓库指南

• rag_core.py — 摄取、分块、嵌入、检索和生成

• mcp_server.py — 一个基于 stdio 的 ask_faq MCP 工具

• faqs/ — 提供的 FAQ 语料库

• tests/ — 确定性的单元测试和配置测试

• evals/cases.json — 五个实时评估用例

• evaluate.py — 实时评估运行器

• pyproject.toml / uv.lock — 锁定的跨平台环境（uv sync）

• setup_windows.ps1 — 围绕相同 uv 步骤的 Windows 便捷包装脚本

• CLAUDE.md — Claude Code 的自动设置与教学说明

• .mcp.json — 可移植的项目级 Claude Code MCP 配置

• START_HERE_WINDOWS.md — 面向 Windows 用户的一次提示词交接说明

• docs/WINDOWS_MCP_SETUP.md — Claude Code 连接步骤

• docs/TALK_TRACK.md — 面试演示与预期问题

• docs/REQUIREMENTS_TRACEABILITY.md — 任务到代码的证据映射

• docs/VALIDATION.md — 已通过的检查以及剩余的实时测试边界

安全性

不要提交 API 密钥。在启用 MCP 服务器之前先对其进行审查；本地 stdio 服务器以启动客户端的用户的权限运行。此服务器只读取其配置的 FAQ 目录，并调用配置好的 OpenAI 模型。

面试准备

使用 docs/TALK_TRACK.md。它解释了架构、每个选择背后的原因、MCP 与 HTTP 的区别，以及这个小练习如何映射到 Glean 的企业搜索和有依据答案问题。