knowledge-mcp

通过 MCP 检索 Markdown 笔记、定位原文并预览修改。

English

合成示例库的真实 MCP 输出；图中只展示 diff 的变更行，未写入文件。

快速开始

uvx --from git+https://github.com/bmdy6/knowledge-mcp knowledge-mcp --vault <路径>

将 <路径> 换成已有知识库的绝对路径。先试用可下载 main 的 ZIP，解压后选择 examples/vault；这是合成示例，无需 clone。 连接客户端后说：“在 personal 中搜索 question，返回路径、行号和片段。”需要 Python 3.10+、uv 和首次下载所需的网络。

Related MCP server: @okfshare/mcp

客户端配置

试用时，把下载包里的 examples/vault 复制到 /tmp/knowledge-mcp-demo。下面三份配置均使用该目录；长期使用请换成自己的绝对路径，重启客户端以载入配置。 uvx 必须在客户端的 PATH 中可用；首次下载可稍慢。

Claude Code

保存为项目的 .mcp.json：

{
  "mcpServers": {
    "knowledge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bmdy6/knowledge-mcp",
        "knowledge-mcp",
        "--vault",
        "/tmp/knowledge-mcp-demo"
      ]
    }
  }
}

Codex

加入 ~/.codex/config.toml：

[mcp_servers.knowledge]
command = "uvx"
args = ["--from", "git+https://github.com/bmdy6/knowledge-mcp", "knowledge-mcp", "--vault", "/tmp/knowledge-mcp-demo"]
startup_timeout_sec = 60

Cursor

保存为项目的 .cursor/mcp.json：

{
  "mcpServers": {
    "knowledge": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bmdy6/knowledge-mcp",
        "knowledge-mcp",
        "--vault",
        "/tmp/knowledge-mcp-demo"
      ]
    }
  }
}

接入后先读 knowledge://guide。客户端设置与路径说明见接入文档。

你能得到什么

• 搜索结果带文件路径、行号和原文片段，方便回到来源核实。

• show_diff 只预览修改；写入时 expected_text 必须在当前文件中唯一匹配。

• 每次访问都选定 scope，路径校验将文档操作限制在知识库内。

工作流程

1. 在 personal 或 company 中搜索，再用 read_range 读取原文。

2. 传入原文片段和替换文本，用 show_diff 审阅变化。

3. 确认后调用 apply_change，回读并校验；Git 提交由维护者处理。

工具

参数见 MCP 契约。新建文档固定为 review；删除、合并和移动也会改动文件。

选项

常见问题与限制

知识库如何组织？ personal/、company/ 各放 Markdown 笔记和概览 README.md，可选 archive/。Frontmatter 的 title、type、status、scope、日期等字段见内容模型。

写入有什么保护？ expected_text 是局部文本条件，须在当前文件恰好出现一次；先看 diff 再提交修改。绝对路径、.. 和跨 scope 文档路径会被拒绝，归档不可直接写入；scope 是文档边界，不能替代操作系统权限。详见写入安全。

支持语义检索吗？ 目前只有关键词检索（中文二元组 + BM25），没有向量检索，也不需要 embedding 服务。内容和检索结果仍需人工核实。

参与贡献

先提 Issue 说明问题；本地安装开发依赖后运行 uv run pytest -q。CI 覆盖 Ubuntu、macOS 和 Python 3.10、3.13。

许可证

MIT。