<div align="center">

kb-mcp-lite

面向AI代理的轻量级本地知识库 · 团队协作友好

pip install kb-mcp-lite — 让任何AI编程助手都拥有结构化、可查询、可同步的团队"第二大脑"

</div>

🎯 解决什么问题

当前的知识管理工具存在明显的断层：

• 面向人类的知识库（Notion/Obsidian）：需要手动维护，AI无法直接高效访问
• 向量数据库：需要复杂配置，没有结构化Schema，团队协作困难
• 团队文档散落在各个地方：代码注释、Wiki、PR描述、飞书文档，AI找不到也用不了

kb-mcp-lite 专门填补这个空白：专为AI代理设计，同时兼顾人类编辑和团队协作，让AI编程助手可以直接调用团队沉淀的所有技术知识。

✨ 核心能力详解

1. 📐 强Schema标准化与结构化Metadata

内置9种开箱即用的文档类型，覆盖技术团队90%的知识沉淀场景，所有类型支持结构化Typed Metadata并可通过Python子类扩展：

优势：

• 真实结构化元数据：支持 JSON 字段与 Frontmatter 无损互转，AI 可精确抽取与检索事实；
• 自动生成稳定ID（比如 dec/use-sqlite-fts5），可被跨文档可靠引用；
• 支持自定义扩展文档类型，满足团队个性化需求。

2. ⚡ Section 级细粒度切片与 Token 保护

传统知识库全量返回整篇文档极易挤占 Agent 上下文空间，造成 Token 浪费。

• 章节按需获取：kb_get(id="...", section="Architecture") / kb get --section "..." 仅提取目标标题章节；
• 智能目录感知：未指定章节时或章节不存在时，自动返回可用章节目录清单；
• 精准降耗：将长文档上下文消耗降低 70%~90%。

3. 🔍 多模式智能搜索

支持四种搜索模式，满足不同场景的查询需求：

• 词法搜索（默认）：基于 SQLite FTS5，BM25 排序，中英文混合优化，精准匹配关键词，适合查找确定的技术点与专有名词
• 模糊搜索：基于 Trigram 索引，容错拼写错误、缩写、别名，适合模糊记忆的查询
• 语义搜索（需安装 `kb-mcp-lite[vec]`）：基于 sqlite-vec 向量扩展，支持自然语言向量嵌入与语义距离匹配，适合通过模糊概念查找相关知识
• 混合检索（RRF 融合）：倒数排名融合（Reciprocal Rank Fusion）算法，智能加权词法、模糊与向量检索，自动优雅降级（未启用向量扩展时自动使用 FTS 混合）

搜索能力特性：

• 支持按文档类型、标签精确过滤
• 支持 vault="*" 跨库联合搜索
• 自动关联相关文档的反向链接与一跳邻居节点
• 搜索结果返回完整结构化信息与相关度评分，AI 可以直接消费
• 语义搜索采用异步嵌入队列机制，后台静默索引，不阻塞前台文档增删改写入

4. 📜 完整版本控制与审计

所有文档的增删改操作都会被完整记录：

• 查看任意文档的完整修改历史，每次变更都有版本号
• 支持版本对比，字段级差异展示，清楚知道改了什么
• 支持恢复到任意历史版本，误修改可以一键回滚
• 软删除机制，删除的文档可以随时恢复，不会丢失数据
• 审计日志记录所有操作，支持审计追踪

5. 🔗 类型化知识图谱

文档之间可以创建带关系的链接：

• 支持10种标准关系类型：relates-to、supersedes、superseded-by、depends-on、blocks、implements、references、governs、owned-by、tagged-with
• 支持自定义关系类型（在配置文件中定义）
• 自动生成反向链接，查找某个决策影响哪些项目，某个Bug关联哪些经验
• 支持影响分析：当文档变更时，自动识别所有下游受影响的文档
• 支持决策演进链追踪：查看决策如何随时间演变
• 支持知识图谱可视化（Web管理后台），直观看到知识之间的关联关系
• 链接完整性校验，自动检测失效链接

6. 🤝 Git原生团队协作 & 智能三方合并

完全基于Git的团队同步机制，学习成本为零：

• 智能元数据合并 (3-Way Merge)：多人同时修改文档时，对 tags / aliases / links / metadata 自动做集合并集合并，杜绝 Git 冲突；
• 自动化文件监听 (Auto-Watcher)：提供 kb watch 命令，支持事件驱动（Linux inotify、macOS FSEvents、Windows ReadDirectoryChangesW）和轮询模式，本地编辑 Markdown 文件实时增量同步至 SQLite 数据库；
• 自动链接提取：文档添加或更新时，自动从Markdown正文中提取文档引用（[text](id) 和 ` id 语法），创建 references` 关系链接；
• 数据库文件本地存储，不会提交到Git，每个成员有独立的本地实例；
• 完全兼容现有Git工作流，支持PR评审、分支管理、Code Owner等机制。

7. 🗄️ 多 Vault 隔离与跨库联合检索

支持创建多个独立的知识库，数据完全隔离且支持 MCP 动态路由：

• 不同项目、不同团队使用独立的vault，互不干扰；
• 跨库联合搜索：在 MCP 中支持 kb_search(query="...", vault="*")，一次调用同时检索全局公共库与当前项目私有库；
• 动态单库切换：kb_get(id="...", vault="work") 无需重启服务，随时精准路由；
• Vault管理：支持创建、切换、列出vault，以及Git同步操作。

8. ⏰ 智能计划任务

内置APScheduler任务调度器，支持自动维护任务：

• 自动提交：定时导出vault变更并Git提交（默认30分钟）
• 自动嵌入：定时处理嵌入队列（默认5分钟）
• 自动重建索引：定时重建FTS5索引（默认每天凌晨3点）
• 健康检查：定时运行健康检查（默认每周一上午9点）
• 清理任务：定时清理软删除超过30天的文档（默认每周日凌晨2点）
• 支持自定义任务间隔和Cron表达式
• 任务失败自动禁用，支持手动重新启用
• 跨进程安全，防止并发执行

10. 🖥️ 现代化 Web 管理控制台 (SPA)

内置基于 React + Tailwind CSS + HeroUI 打造的现代化管理后台（kb admin start 自动启动）：

• 深色/浅色主题适配：完美支持系统与手动切换，高对比度排版与磨砂玻璃质感；
• 知识图谱可视化：基于 vis-network 的交互式关系图谱拓扑展示，支持节点筛选、高亮与多跳关系钻取；
• 文档全生命周期管理：提供实时双栏 Markdown 协同编辑器、文档标签/类型过滤、版本差异对比（Diff Viewer）及一键历史回滚；
• 关系边与语义动词管理：带中文解释的标准关联动词选择器，直观建立文档间的前后置依赖、规范约束及决策替代链；
• Git 同步与冲突可视化：实时检查本地 SQLite 数据库与 Git 工作区状态，可视化查看未提交文档差异，支持一键拉取（Pull）与推送（Push）；
• 任务调度与健康看板：直观管理 APScheduler 自动化任务状态、嵌入队列进度及知识库健康诊断修复。

11. 🌐 MCP协议原生支持 (25工具/13资源/7提示)

完全兼容MCP（Model Context Protocol）标准协议，任何支持MCP的客户端（Claude Desktop、Cursor、Composio等）都可以直接接入，AI自动获得以下能力： #### 25个内置工具

批量导入/导出、prune、reindex、vault 和 Git 同步属于 CLI/Admin 生命周期能力，不会作为 MCP 文件系统工具暴露。

#### 13个结构化资源

#### 7个交互Prompt

🚀 快速开始使用

🔧 安装方式与依赖选项

kb-mcp-lite 默认采用纯净无 C 扩展的基础安装，保证极速且 100% 跨平台兼容。你可以根据功能需求选择安装对应的可选扩展包：

#### 1. 推荐方式：通过 uv tool 安装 CLI / MCP 服务

# 基础安装（包含 FTS5 全文检索、模糊搜索、多 Vault、Git 同步及 Web 控制台）
uv tool install kb-mcp-lite

# 🌟 推荐：安装包含向量/语义搜索支持（自动集成 sqlite-vec + pysqlite3）
uv tool install "kb-mcp-lite[vec]"

# 🚀 全功能完整版（包含向量语义搜索 + 原生事件驱动文件监听 watchfiles）
uv tool install "kb-mcp-lite[vec,v0_8]"

#### 2. 通过 pip 安装

# 基础安装
pip install kb-mcp-lite

# 开启语义搜索 (Semantic / Vector Search)
pip install "kb-mcp-lite[vec]"

# 开启全功能扩展 (包含 vec 与高性能文件监听)
pip install "kb-mcp-lite[vec,v0_8]"

📌 依赖扩展说明： - `kb-mcp-lite[vec]`：包含 sqlite-vec 与 pysqlite3。如果需要在 Web 控制台或 MCP 中使用 semantic（向量语义检索）或更高精度的 hybrid（混合排序），必须安装此扩展。未安装时系统将自动降级为 FTS5 全文及模糊检索。 - `kb-mcp-lite[v0_8]`：包含 watchfiles（Rust 实现的原生文件系统事件监听，支持 Linux inotify、macOS FSEvents、Windows ReadDirectoryChangesW）。未安装时 kb watch 将自动回退为 1 秒间隔的轮询监听。

个人用户基础使用

#### 1. 初始化知识库

kb init

会在默认路径 ~/.local/share/kb-mcp/ 创建默认vault的SQLite数据库。

#### 2. 添加第一个文档

kb add --type project \
       --title "kb-mcp-lite" \
       --tags "mcp,knowledge-base,python" \
       --body "面向AI代理的轻量级本地知识库，基于SQLite + FTS5 + MCP协议开发。"

#### 3. 搜索文档

# 默认搜索
kb search "MCP 知识库"

# 按类型过滤
kb search "sqlite" --type decision

# 模糊搜索
kb search "ft5" --fuzzy

#### 4. 查看已有文档

# 查看所有文档
kb list

# 按类型过滤
kb list --type lesson

# 按标签过滤
kb list --tags "sqlite,bug"

#### 5. 更多CLI命令

# 查看文档详情（完整）
kb get <文档ID>

# 按章节获取文档内容（仅提取特定标题内容，节省Token）
kb get <文档ID> --section "Architecture"

# 更新文档
kb update <文档ID> --title "新标题"

# 删除文档
kb delete <文档ID>

# 查看版本历史
kb history <文档ID>

# 对比版本差异
kb diff <文档ID> --v1 1 --v2 2

# 恢复到指定版本
kb restore <文档ID> --version 2

# 创建文档链接
kb link --from <文档ID1> --to <文档ID2> --rel "relates-to"

# 查看文档链接
kb links <文档ID>

# 影响分析
kb impact <文档ID>

# 决策演进链追踪
kb chain <决策文档ID>

# 关系类型管理
kb rel list                    # 列出所有标准关系类型
kb rel show supersedes         # 查看特定关系详情

# 自动监听 Markdown 目录实时增量同步入库
kb watch --interval 1.0

# 启动Web管理后台
kb admin start

# 计划任务管理
kb scheduler list              # 列出所有任务
kb scheduler status            # 查看调度器状态
kb scheduler run auto-commit   # 手动触发任务
kb scheduler history           # 查看执行历史

# 健康检查
kb doctor

# 统计信息
kb stats

# 清理软删除文档
kb prune --older-than 30

# Git差异分析
kb diff-check

👥 团队协作配置

#### 首次配置团队知识库

1. 管理员创建团队Git仓库（空仓库即可）
2. 管理员本地初始化vault并关联Git

   # 创建团队vault
   kb vault create team --desc "XX团队公共知识库"
   kb vault switch team
   
   # 克隆团队Git仓库到本地
   git clone <团队Git仓库地址> ~/team-kb
   
   # 关联vault和Git同步目录
   kb vault init-git --sync-dir ~/team-kb
   
   # 导出已有文档到Git目录并提交
   kb vault commit -m "初始化团队知识库"
   kb vault push

#### 新成员加入

# 1. 克隆团队知识库Git仓库
git clone <团队Git仓库地址> ~/team-kb

# 2. 创建本地vault
kb vault create team --desc "XX团队公共知识库"
kb vault switch team

# 3. 关联Git同步目录
kb vault init-git --sync-dir ~/team-kb

# 4. 拉取并导入所有文档
kb vault pull

#### 日常协作流程

graph LR
A[AI自动/手动添加修改文档] --> B[拉取最新变更]
B --> C{是否有冲突?}
C -->|是| D[解决Markdown文件冲突]
C -->|否| E[提交本地变更]
D --> E
E --> F[推送到远程仓库]

日常操作命令：

# 写文档前先拉取最新
kb vault pull

# AI添加/修改文档后，提交变更
kb vault commit -m "添加XX项目部署流程文档"

# 推送到远程仓库
kb vault push

#### AI工具自动同步配置 如果希望AI调用kb add添加文档后自动同步到Git，可以配置post-hook脚本，在~/.config/kb-mcp/config.yaml中添加：

hooks:
  post_add: "kb vault commit -m 'AI自动添加文档: {doc_title}' && kb vault push"
  post_update: "kb vault commit -m 'AI自动更新文档: {doc_title}' && kb vault push"

🤖 MCP客户端接入配置

#### Claude Desktop 配置 编辑 ~/.config/claude_desktop_config.json 添加：

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

重启Claude后，AI就可以直接访问你的知识库了。

#### Cursor 配置 在Cursor设置中找到MCP服务器配置，添加：

• 名称：kb
• 命令：kb
• 参数：["serve"]

#### 指定使用某个vault 如果有多个vault，可以指定启动时使用的vault：

"args": ["serve", "--vault", "team"]

#### Cline 配置 在Cline设置中找到MCP服务器配置，添加：

• 名称：kb
• 命令：kb
• 参数：["serve"]

#### OpenCode 配置 在OpenCode配置文件中添加：

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

🔌 高级用法

#### 自定义文档类型

from kb_mcp_lite.schema import Document, Field


class ApiDoc(Document):
    """API接口文档类型"""

    type: str = "api"
    id_prefix: str = "api"

    # 自定义字段
    endpoint: str = Field(description="接口路径")
    method: str = Field(description="HTTP方法")
    version: str = Field(description="接口版本")

    class Config:
        schema_extra = {
            "example": {
                "title": "用户获取接口",
                "endpoint": "/api/v1/user/{id}",
                "method": "GET",
                "version": "v1",
                "tags": ["user", "api"],
                "body": "接口返回用户的基本信息...",
            }
        }

注册后就可以使用 kb add --type api 创建这种类型的文档。

#### 批量导入现有Markdown文档

# 导入目录下所有Markdown文件
kb import ./docs/

# 试运行，查看会导入什么，不实际写入
kb import ./docs/ --dry-run

# 导入后输出JSON格式报告
kb import ./docs/ --json

要求Markdown文件顶部包含YAML frontmatter，至少有type和title字段。

#### 导出知识库

# 导出所有文档到指定目录
kb export ./export_dir/

# 强制覆盖已有文件
kb export ./export_dir/ --force

💡 最佳实践

文档命名与分类规范

1. 标题清晰准确：用动宾结构或者问题式标题，比如「Redis缓存击穿解决方案」而不是「Redis笔记」
2. 标签统一规范：所有标签小写，用短横线分隔，比如 redis-cache, bug-fix
3. 关联关系完整：创建文档时主动关联相关文档，比如决策记录关联对应的项目，经验教训关联对应的Bug决策
4. 及时更新：文档过时后及时更新，不要保留错误信息

团队协作规范

1. 提交信息规范：kb vault commit -m "提交信息" 要清晰说明修改内容
2. PR评审机制：重要文档变更走PR评审，保证知识质量
3. 定期清理：每个季度运行一次 kb doctor 检查知识库健康度，清理失效文档和链接

AI使用建议

1. 要求AI解决问题前先搜索知识库，优先使用已有方案
2. 解决完新问题后，要求AI自动沉淀到知识库作为经验
3. 定期让AI整理知识库，优化结构、补充关联、更新过时内容

🛠️ 开发指南

本地开发环境搭建

git clone https://github.com/HelloTomBruce/kb-mcp-lite
cd kb-mcp-lite

# 安装依赖（推荐使用uv）
uv sync --extra dev

# 运行测试
uv run pytest

# 代码检查
uv run ruff check .
uv run mypy src/

# 格式化代码
uv run ruff format .
uv run ruff check --fix .

项目结构说明

src/kb_mcp_lite/
├── cli.py              # Click CLI (28 commands)
├── mcp_server.py       # FastMCP server (25 tools, 13 resources, 7 prompts)
├── schema.py           # Document, Link, SearchHit, TypeRegistry, exceptions
├── store.py            # Store Protocol (interface contract)
├── store/              # SQLite存储核心
│   ├── sqlite.py       # SqliteStore (composes 4 mixins)
│   ├── search.py       # SearchMixin — FTS5 + vec0 hybrid search
│   ├── embedding.py    # EmbeddingMixin — vec0 vectors, similarity, duplicates
│   ├── versioning.py   # VersioningMixin — history, snapshots, diff, restore
│   ├── maintenance.py  # MaintenanceMixin — doctor, prune, stats, subgraph
│   ├── embedding_queue.py # EmbeddingQueue — async queue with state machine
│   └── connection.py   # Shared sqlite3 connection factory
├── md_io.py            # Markdown frontmatter parser + bulk import/export
├── vault.py            # Multi-vault management
├── admin/              # FastAPI 后端与静态托管
│   ├── routes_docs.py  # Document CRUD + search
│   └── routes_meta.py  # Overview, links, graph, settings
├── static/app/         # 构建后的现代化 SPA 静态资源
├── migrations/         # Forward-only SQL migration runner
├── config.py           # XDG config loader
├── embedder.py         # OpenAI-compatible embedding client
├── worker.py           # Background embedding worker thread
├── watcher.py          # File watcher (event/poll modes)
├── scheduler.py        # APScheduler task scheduler (5 built-in tasks)
├── graph_query.py      # Multi-hop graph query engine (BFS)
├── relations.py        # Typed relation vocabulary + impact analysis
├── link_parser.py      # Body-level reference parser [text](id)
├── context_guard.py    # Git diff → relevant decisions/lessons
├── merge.py            # 3-way Markdown merge
├── migrations.py       # Forward-only SQL migration runner
└── concurrency/
    └── write_lock.py   # Cross-process flock-based write lock

web/                    # 前端单页应用源码 (React + Tailwind + HeroUI)
├── src/                # 前端组件与页面
│   ├── pages/          # Documents, DocDetail, Git, Links, Graph, Scheduler 等
│   └── components/     # MarkdownRenderer, DiffViewer, Badges 等
└── package.json        # 前端构建配置

📌 状态说明

当前处于Beta测试阶段：

• API和存储格式从v0.5.0开始已经稳定，不会有破坏性变更
• v0.8.0 新增：auto-link、关系词汇、调度器、嵌入队列、多跳图查询等
• 生产环境使用建议锁定版本：kb-mcp-lite>=0.8,<0.9
• 欢迎提交Issue和PR，贡献代码请查看 CONTRIBUTING.md

📄 许可证

MIT License，可自由使用、修改、分发，保留版权声明即可。

🔗 相关链接

• GitHub仓库：https://github.com/HelloTomBruce/kb-mcp-lite
• PyPI包：https://pypi.org/project/kb-mcp-lite/
• 问题反馈：https://github.com/HelloTomBruce/kb-mcp-lite/issues
• 更新日志：https://github.com/HelloTomBruce/kb-mcp-lite/releases
• 架构文档：docs/architecture.md
• CLI参考：docs/cli-reference.md
• 关系词汇：docs/relation-vocabulary.md
• 计划任务：docs/scheduler.md