Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agent-bm25-knowledge-mcp search my indexed knowledge base for R&D expense trends"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个面向 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: local-Rag
要求 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.jsonAgent 也可以调用 knowledge_reindex，但该工具只会重建配置中已经授权的源，不能传入新路径。
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 中自动批准。
项目级 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.jsonKiro 会监听 mcp.json 并在会话空闲边界热更新。进入会话后使用 /mcp 检查四个工具是否加载。
将 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"}}'把 configs/codex-config.toml.example 中的段落加入 Codex config.toml，或使用 codex mcp add 添加本地 stdio server。
参考 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 installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Local-first RAG engine with MCP server for AI agent integration.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/BairuiZhang/agent-bm25-knowledge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server