Click on "Deploy 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., "@knowledgehub search daily-work for API design patterns"
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.
KnowledgeHub 是面向本地多知识库的统一扫描、增量索引和 AI 检索基础设施。
它不搬运原始文件，而是注册多个知识目录，检测新增、修改和删除，更新本地 SQLite/FTS5 全文索引，并通过只读 MCP 同时向 Claude Code 和 Codex 提供带绝对路径、章节、行号和原文片段的检索能力。
实现版本：0.1.0
运行时：Python 3.12
项目目录：/Users/your-user/KnowledgeHub
实际配置：config/knowledge-bases.yaml
索引数据库：index/knowledge.db
已启用知识库：daily-work、business-dev
首次真实索引：2026-07-16，共 850 个文档、16,610 个 chunks
AI 接入：Claude Code 与 Codex 均已注册用户级/全局 knowledgehub MCP
调度：macOS launchd 每天本地时间 12:00 执行 kb reconcile --all
通知：复用本机 Lark 机器人脚本发送任务摘要
Related MCP server: Local Code MCP Server
多知识库、多根目录和 project_id 路由
Markdown、Text、YAML、JSON、HTML、PDF、DOCX 解析
SHA-256 增量检测与 Manifest 全量对账
SQLite WAL + FTS5 trigram 全文检索
1–2 字中文查询 LIKE 回退
显式 chunk_id 关联、scope/project 过滤
解析失败保留最后一次成功索引
敏感路径和敏感内容拒绝索引
只读 MCP：kb_search、kb_read、kb_project_context、kb_status
PID 锁、stale lock 恢复、当天成功去重、Lark 重试与 outbox
cd /Users/your-user/KnowledgeHub
# 校验配置
.venv/bin/kb config validate --config config/knowledge-bases.yaml
# 快速增量扫描：不做全局删除对账
.venv/bin/kb scan --scope daily-work --config config/knowledge-bases.yaml
# 完整 Manifest 对账：每日任务使用此命令
.venv/bin/kb reconcile --all --config config/knowledge-bases.yaml
# 全文检索
.venv/bin/kb search "半双工消息流" --scope daily-work --config config/knowledge-bases.yaml
# 项目知识路由
.venv/bin/kb project-context /Users/your-user/workspace/bit-news \
--config config/knowledge-bases.yaml
# 查看健康状态
.venv/bin/kb status --json --config config/knowledge-bases.yaml文档 | 说明 |
总体架构、数据模型、检测、索引、调度、安全与测试 | |
已安装 MCP、项目指令、检索流程与验证 | |
已安装 MCP、AGENTS.md 规则与验证 | |
手动扫描、launchd、日志、Lark、备份与恢复 | |
真实索引、MCP、Lark、launchd 和测试验收结果 | |
多知识库、包含/排除规则、调度和通知配置 |
/Users/your-user/KnowledgeHub/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── pyproject.toml
├── src/knowledgehub/
├── tests/
├── config/
│ ├── knowledge-bases.example.yaml
│ └── knowledge-bases.yaml # 本机实际配置，不提交凭据
├── docs/
├── deploy/
├── scripts/
├── index/ # SQLite 索引
├── run/ # PID、锁和当天成功标记
└── logs/ # 扫描日志、JSON 报告和通知 outboxIndexer 不修改、不删除、不移动原始知识文件。
MCP 只提供读取和检索，不提供写入/删除工具。
.env、私钥、证书、Token、凭据文件默认拒绝索引。
Lark Webhook 或应用凭据保留在项目目录外，不复制进 KnowledgeHub。
Resolve an absolute project path to its indexed project documentation.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden itself. 'Resolve ... to documentation' implies a read-only lookup and communicates that the documentation is indexed, but it does not disclose failure behavior, indexing prerequisites, or whether any side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single tight sentence with no filler and the key constraint 'absolute project path' is front-loaded. However, it is slightly terse and does not structure the optional limit behavior into the description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only one required parameter and an output schema, the description is minimally sufficient for a basic call. It falls short on sibling differentiation and the semantics of the optional limit parameter, but the core invocation path is understandable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning to project_path by specifying 'absolute', but it says nothing about the limit parameter, which remains only a title and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: resolving an absolute project path into its indexed project documentation. It clearly distinguishes this from generic search/read operations by focusing on project-level context, though it does not explicitly contrast itself with sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus kb_search, kb_read, or kb_status. It implies the input should be an absolute path, but it never states when path-to-documentation resolution is preferred over sibling operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one indexed document or a specific indexed chunk.
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_id | No | ||
| document_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden of behavioral disclosure. It only says 'read' without noting whether the operation is non-destructive, what the response contains, or what happens when chunk_id is omitted. It adds no behavioral context beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a clear front-loaded verb and no filler. Every word contributes to defining the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the output schema covers return values. The description adequately covers the basic operation, but it omits usage context relative to sibling tools and edge-case behavior, leaving moderate ambiguity for an agent deciding between reading and searching.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. The phrase 'or a specific indexed chunk' usefully implies that document_id selects the document and chunk_id selects a chunk within it. However, it does not explain defaults, optionality behavior, or any format details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Read') and a specific resource ('one indexed document or a specific indexed chunk'). It clearly distinguishes the read operation from the sibling search/context/status tools by naming the exact object being read, though it does not explicitly contrast itself with those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like kb_search or kb_project_context. It only states what the tool does and leaves the selection entirely to inference, which is a meaningful gap given the presence of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search indexed knowledge and return traceable document/chunk references.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| scopes | No | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the core behavior—searching and returning traceable references—but omits whether the operation is read-only, any authentication requirements, rate limits, or other behavioral traits. For a search tool, this is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the purpose and the output with no filler. Every word contributes meaning, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists, the description lacks usage context, parameter semantics for most parameters, and any differentiation from sibling tools. It is too minimal to fully enable correct invocation for a 4-parameter tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implicitly covers the 'query' parameter via 'Search'; 'limit', 'scopes', and 'project_id' are left unexplained in both the schema and description. This is a clear gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'indexed knowledge', and the return type 'traceable document/chunk references'. It conveys a specific, distinct function that separates it from siblings like kb_read, though it does not explicitly name or contrast them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as kb_read or kb_project_context. The description only restates the basic operation without any context, exclusions, or mention of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return KnowledgeHub index health and last scan information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Return ... information' reasonably implies a read-only, non-destructive operation, and the scoped output is helpful. However, it does not disclose potential behavior such as stale data, request cost, or whether the health check itself triggers a scan.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to the meaning, and it is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status tool with an output schema and clearly named siblings, this description is largely complete. It could be improved by stating whether health reflects the current live index state or the last persisted scan, but the output schema may already cover return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is effectively complete, so there is no parameter ambiguity. The description need not explain parameters because there are none; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Return') and a specific resource ('KnowledgeHub index health and last scan information'). This is distinct from the sibling tools, which all imply different operations (searching, reading, project context), so an agent can determine the tool's role immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for checking KnowledgeHub status and scan information, but it does not explicitly state when to use it versus siblings or when not to use it. There is no guidance about prerequisites, frequency, or interpretation of health results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0kb_project_contextkb_readkb_searchkb_statusScored across 4 tools
Each tool targets a distinct action: search, read, resolve project context, and check status. There is no functional overlap between them, so an agent can confidently select the right tool.
All tools share the consistent 'kb_' prefix and use snake_case, but two are verb-based (kb_search, kb_read) while two are noun-based (kb_project_context, kb_status). This is a minor deviation from a uniform verb_noun pattern.
With 4 tools, the server is well-scoped for querying a knowledge base. It is not too thin or overloaded, and each tool serves a clear purpose.
The tool set covers the core knowledge access workflows: search, read, get project context, and health status. Missing operations like listing all projects or documents are minor gaps that agents can work around via search.
Securely search and manage workspace context files for AI agents and teams.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your knowledge bases from any AI assistant using hybrid RAG.
A searchable knowledge base your assistant reads and writes.
