Skip to main content
Glama
BairuiZhang

agent-bm25-knowledge-mcp

by BairuiZhang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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 保留；

  • 命中词、分路排名、文件和行号解释；

  • 只访问配置文件中授权的知识源。

Related MCP server: RepoChatMCP

快速开始

要求 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                 调研结论与设计取舍

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Alcove

    epicsagas
    A
    license
    A
    quality
    B
    maintenance
    MCP server that gives AI coding agents on-demand access to private project docs via BM25 ranked search. One setup for Claude Code, Cursor, Codex, Gemini CLI, and more. Docs stay private, never in public repos.
    15
    15
    Apache 2.0

  • RepoChatMCP

    gzmagyari
    A
    license
    A
    quality
    D
    maintenance
    A zero-dependency MCP server that enables searching and reading local Claude Code and Codex chat sessions, supporting full-text search, grep, and knowledge indexing from chat history.
    15
    6 npm
    MIT

  • localdocs-mcp

    Huntbae
    A
    license
    Not graded
    quality
    B
    maintenance
    A local document search MCP server that indexes personal files and enables hybrid search (BM25 + semantic) for Claude to find and cite internal materials.
    MIT