mcp-local-rag: Instructions file for Codex

AGENTS.md

为 mcp-local-rag 项目工作的 AI 编码 Agent 使用指南。

项目概述

mcp-local-rag 是一个本地 RAG（检索增强生成）MCP 服务器和 CLI 工具 — 带关键词增强的语义文档搜索，完全私有，零配置。支持摄入 PDF/DOCX/TXT/MD/HTML 文件，按语义（而非字符数）分块，使用 Transformers.js 生成嵌入向量，存入 LanceDB，并提供 7 个 MCP 工具和对应的 CLI 子命令。

• 包名：npm 上的 @damoqiongqiu/mcp-local-rag
• 许可证：MIT
• Node 版本：>= 22
• 包管理器：pnpm（锁文件：pnpm-lock.yaml）
• 语言：TypeScript 6.0，严格模式，ES Modules（"type": "module"）
• 模块系统：Node16（"module": "node16"），相对导入须带 .js 扩展名

常用命令

pnpm install              # 安装依赖
pnpm run build            # TypeScript 编译 → dist/
pnpm run dev              # 通过 tsx 运行（无需构建）
pnpm run test             # 运行全部测试（CPU，maxWorkers: 1）
pnpm run check:all        # 完整 CI 流水线（lint + format + unused + deps + build + test）
pnpm run check:fix        # 自动修复 lint 和格式化问题
pnpm run type-check       # tsc --noEmit

项目结构

src/
  index.ts              # 入口 — 路由到 CLI 或 MCP 服务器
  cli-main.ts           # CLI 调度器（ingest、query、list、delete、read-neighbors、status）
  server-main.ts        # MCP 服务器启动
  cli/                  # CLI 子命令实现 + 选项解析
  server/               # MCP 工具处理器、定义、输入解析、错误工具
  parser/               # 文档解析器（PDF 用 mupdf、DOCX 用 mammoth、TXT、MD、HTML、代码文件）
  chunker/              # 分块（SemanticChunker 语义分块 + CodeChunker AST 分块）
  embedder/             # Transformers.js 嵌入（通过 ONNX 加载 HuggingFace 模型）
  vectordb/             # LanceDB 操作、向量存储、类型定义
  ingest/               # 摄入流水线（计算分块、PDF 视觉标注）
  utils/                # 共享工具（base-dirs、errors、raw-data、scan、scope-match）
  __tests__/            # 全部测试套件（与 src/ 结构镜像）
skills/                 # 随包发布的 Agent Skills
scripts/                # 构建/测试辅助脚本

代码规范

格式化（Biome）

• 缩进：2 空格
• 引号：单引号（'）
• 分号：无（"semicolons": "asNeeded"）
• 尾逗号：ES5（"trailingCommas": "es5"）
• 行宽：100
• 自动修复：pnpm run check:fix

Lint 规则

• Biome 推荐规则 + noExplicitAny: "warn"（测试文件中关闭）
• noNonNullAssertion: "off"、useLiteralKeys: "off"
• knip 检查未使用的导出（pnpm run check:unused）
• dpdm 检查循环依赖（pnpm run check:deps）