Agent BM25 Knowledge MCP

一个面向 Claude Code、Kiro CLI、Codex 等 Agent 的本地知识检索工具。它模仿 Kiro CLI Fast Knowledge 的公开行为：对显式配置的文件或目录递归扫描、分块、构建持久化 BM25 索引，并通过 MCP 向 Agent 提供可解释检索。

它解决什么问题

普通 Agent 的 grep 很适合已知代码符号，但不适合在大量产品文档、PageIndex 节点或领域资料中进行排序召回。本工具提供：

• BM25 倒排索引，启动后无需重新扫描所有文件；
• 中文词语与字符二元组分词；
• camelCase、snake_case、路径和代码标识符分词；
• 配置式同义词；
• 原始 Query 与 Agent 扩展 Query 分路检索；
• RRF 或归一化加权分数融合；
• PageIndex JSON 的 node_id、title、keywords、path 保留；
• 命中词、分路排名、文件和行号解释；
• 只访问配置文件中授权的知识源。

快速开始

要求 Node.js 20 或更高版本。

cd /Users/zhangbairui/Desktop/agent-bm25-knowledge-mcp
npm install
npm run build
npm run index -- --config knowledge.config.example.json
npm run search -- \
  --config knowledge.config.example.json \
  --query "研发投入下降是不是裁员造成的" \
  --variant "研究开发支出下降原因 项目结项"

运行验证：

npm test
npm run smoke:mcp

指定检索内容

复制并修改 knowledge.config.example.json：

{
  "indexDir": ".knowledge-index",
  "synonyms": [
    {
      "canonical": "研发投入",
      "aliases": ["研发费用", "研究开发支出", "R&D expense"],
      "weight": 0.75
    }
  ],
  "sources": [
    {
      "name": "product-docs",
      "path": "/absolute/path/to/approved/docs",
      "description": "产品规范和设计文档",
      "include": ["**/*.md", "**/*.json"],
      "exclude": ["**/.git/**", "**/node_modules/**"],
      "parser": "auto",
      "chunkSize": 1600,
      "chunkOverlap": 240,
      "maxFileBytes": 2000000,
      "enabled": true
    }
  ]
}

parser 支持：

• text：所有匹配文件按普通文本分块；
• pageindex-json：强制按 PageIndex 风格节点解析；
• auto：JSON 中识别到 PageIndex 节点时保留节点元数据，否则按文本处理。

修改知识文件后重新构建：

npm run index -- --config /path/to/knowledge.config.json

Agent 也可以调用 knowledge_reindex，但该工具只会重建配置中已经授权的源，不能传入新路径。

MCP 工具

knowledge_list_sources

列出当前索引时间、授权知识源、文件数、chunk 数和跳过文件。

knowledge_search

主要参数：

{
  "query": "用户的原始问题，保留实体、数字和否定词",
  "query_variants": [
    {
      "text": "正式术语 同义词 缩写",
      "weight": 0.7,
      "purpose": "formal domain wording"
    }
  ],
  "source_names": ["product-docs"],
  "fusion": "rrf",
  "limit": 10,
  "response_format": "json"
}

不要把所有扩展词拼成一条查询。原始 Query 与扩展 Query 会独立排名后融合，从而保护型号、数字、否定词和用户原话。

knowledge_get_chunk

读取 knowledge_search 返回的一个完整 chunk。参数只能是索引生成的 chunk_id，不能传任意文件路径。

knowledge_reindex

重新扫描所有启用的配置源并原子替换索引。该工具会写索引文件，因此默认不建议在 Kiro 中自动批准。

接入 Kiro CLI

项目级 MCP 配置位置为 .kiro/settings/mcp.json。可直接使用本仓库的配置模板：

mkdir -p /path/to/your-project/.kiro/settings
cp configs/kiro-mcp.json /path/to/your-project/.kiro/settings/mcp.json

也可以执行：

kiro-cli mcp add \
  --name agent-knowledge \
  --command "node /Users/zhangbairui/Desktop/agent-bm25-knowledge-mcp/dist/index.js" \
  --scope workspace

然后确保 MCP 进程环境包含：

KNOWLEDGE_CONFIG=/absolute/path/to/knowledge.config.json

Kiro 会监听 mcp.json 并在会话空闲边界热更新。进入会话后使用 /mcp 检查四个工具是否加载。

接入 Claude Code

将 configs/claude-mcp.json 复制成项目根目录的 .mcp.json，或执行：

claude mcp add-json agent-knowledge \
  '{"type":"stdio","command":"node","args":["/Users/zhangbairui/Desktop/agent-bm25-knowledge-mcp/dist/index.js"],"env":{"KNOWLEDGE_CONFIG":"/absolute/path/to/knowledge.config.json"}}'

接入 Codex

把 configs/codex-config.toml.example 中的段落加入 Codex config.toml，或使用 codex mcp add 添加本地 stdio server。

推荐 Agent 工作方式

参考 AGENT_RETRIEVAL_PROMPT.md。核心循环是：

保留原始 Query
→ 生成少量目的明确的查询变体
→ knowledge_search
→ 查看命中词和 PageIndex 路径
→ knowledge_get_chunk 读取证据
→ 使用结果中发现的文档真实术语再次检索
→ 证据充分后停止

安全边界

• 知识路径只能在静态配置中指定，Agent 调用时不能增加路径；
• 目录扫描不跟随符号链接，并验证文件真实路径仍位于授权根目录；
• 默认排除 .git、node_modules、构建目录和虚拟环境；
• 限制文件大小、查询长度、查询变体数和返回字符数；
• stdio 模式只向 stderr 输出日志，避免破坏 MCP JSON-RPC；
• 索引使用临时文件加原子 rename，避免中断时留下半个索引。

当前限制与下一步

• 当前是单机 JSON 倒排索引，适合数万到中等规模 chunk；百万级 chunk 应迁移到 SQLite FTS5、Tantivy 或 Lucene/OpenSearch；
• 同义词配置按等价词组处理，非等价的上下位关系更适合由 Agent 作为低权重 query_variants 提供；
• PDF、DOCX 等二进制文件需要先转换成文本或 PageIndex JSON；
• 尚未实现 Kiro 的语义 Best 路线，可后续加入本地 embedding 并通过 RRF 与 BM25 融合；
• 尚未做文件系统 watcher，源内容变化后通过 CLI 或 knowledge_reindex 更新。

目录

src/index.ts                MCP stdio server
src/cli.ts                  index/search/inspect CLI
src/services/indexer.ts     文件发现、PageIndex 解析和倒排索引
src/services/search.ts      BM25、多查询和融合
src/services/tokenizer.ts   中文及代码分词
src/tests/                  单元测试
scripts/smoke-mcp.mjs       真实 MCP 客户端烟雾测试
evals/evaluation.xml        10 个只读 Agent 评测问题
RESEARCH.md                 调研结论与设计取舍