Auto Knowledge Sync MCP

将 LLM 开发会话中获得的技术知识整理为完整文档，并积累为个人或团队知识源的本地 MCP 服务器。MCP 在用户计算机上以 Docker 容器运行，知识的唯一事实来源(SSOT)保存在用户指定的 private GitHub repository 中。

为什么需要它？

开发过程中与 LLM 交流的说明、决策和注意事项虽然有用，但会话结束后很容易丢失。本项目将以下流程接入日常的 MCP 使用方式。

1. LLM 在会话中提出具有复用价值的技术知识。

2. MCP 检查文档的完整性、隐私信息、公司内部敏感信息以及是否包含原始代码。

3. 仅将已批准的提案提交到 GitHub repository。

4. 之后通过搜索、验证、challenge、重组持续更新知识。

存储的文档不是简单的关键词列表，而是解释概念、运作方式、技术意义、解决的问题、适用条件与局限性的独立 knowledge entry。如果需要代码示例，只允许使用新编写的示例，不得复制或改写现有业务代码。

Related MCP server: MCP Enhanced Data Retrieval System

主要特点

• 远程 SSOT：知识与变更历史以 GitHub commit 形式留存。本地仅存放可重新生成的搜索索引和临时数据。

• 敏感信息拦截：应用内置 secret·PII 检查与可选的按组织 deny rule，并采用检查失败即不保存的 fail-closed 策略。

• 显式审批：默认审批模式为 always。仅在需要时可设置为 on_risk 或 never，安全硬性门槛与高风险变更始终经过验证。

• 知识生命周期：除搜索外，还支持提交反例、检查 stale·重复内容、整理关系，以及提出 merge/split/reclassify/deprecate 建议。

• 无服务器运维：没有常驻运行的中央服务器或运维数据库。MCP 在 Codex、Claude Code 等 MCP 客户端需要时于本地运行。

• 最小权限：PAT 仅授予指定的一个 private repository，MCP 不要求 GitHub 组织、Actions、Pull request 权限。

环境要求

• Docker Desktop 或 Docker Engine

• 用作知识仓库的 private GitHub repository

• 仅选择该 repository 的 fine-grained PAT

  • Metadata: Read-only

  • Contents: Read and write

  • 不授予 Pull requests、Actions、Administration 权限

• 从源码构建时需要 Node.js 24 及以上版本和 Git

在保存公司资料前，请确认组织的外部 GitHub 使用政策。建议首次运行时使用合成的技术内容而非真实业务资料来验证连接。

快速开始

1. 准备源码与本地镜像

git clone https://github.com/One-armed-boy/auto-knowledge-sync-mcp.git
cd auto-knowledge-sync-mcp
npm ci
npm run build
docker build --tag auto-knowledge-sync-mcp:local .

2. 创建 PAT 文件与配置

不要将 PAT 直接写入 shell command line 或 YAML，而应通过 owner-only 文件管理。

CONFIG_DIR="$HOME/.config/auto-knowledge-sync"
PAT_FILE="$CONFIG_DIR/secrets/github_pat"

mkdir -p "$CONFIG_DIR/secrets"
umask 077
touch "$PAT_FILE"
chmod 600 "$PAT_FILE"
${EDITOR:-nano} "$PAT_FILE"

node dist/cli.js init \
  --repository <GITHUB_OWNER>/<PRIVATE_KNOWLEDGE_REPOSITORY> \
  --token-file "$PAT_FILE"

init 会创建默认配置文件，并在 repository 中引导 knowledge manifest。直接使用默认配置则无需手动修改 YAML。生成的默认路径如下。

$HOME/.config/auto-knowledge-sync/config.yaml
$HOME/.config/auto-knowledge-sync/secrets/github_pat

3. 连接诊断与 MCP 客户端注册

doctor 会检查 repository、PAT 权限、schema 兼容性、branch 与 cache 状态，并输出适用于 Codex·Claude Code 的注册命令。

CONFIG_FILE="$CONFIG_DIR/config.yaml"

node dist/cli.js doctor \
  --config-file "$CONFIG_FILE" \
  --token-file "$PAT_FILE" \
  --client-commands \
  --image-ref auto-knowledge-sync-mcp:local \
  --host-config-file "$CONFIG_FILE" \
  --host-token-file "$PAT_FILE"

在对应客户端中执行一次输出的 client_commands.codex 或 client_commands.claude 命令。注册后可通过以下方式确认连接。

codex mcp list
codex mcp get auto-knowledge-sync
claude mcp list
claude mcp get auto-knowledge-sync

如果需要直接运行主机构建结果而非镜像的 client 命令，请在 doctor --client-commands 中省略 --image-ref 与 host mount 选项。稳定的 release image 与 digest 固定的 Compose runtime 请参阅安装·运维文档。

基本用法

连接后，按以下顺序在 LLM 中使用。

1. 使用 repository_status 检查远程仓库与 schema 状态。

2. 使用 search_knowledge 或 get_knowledge 读取已有知识。

3. 使用 capture_knowledge 提出新的技术知识。

4. 确认结果的 privacy·completeness 检查后，使用 apply_proposal 提交。

5. 发现过时知识或反例时，使用 challenge_knowledge 或 maintain_knowledge。

提供的 MCP 工具如下。

所有变更均使用 idempotency key 与远程 HEAD 检查。发生冲突时，会提示重新搜索当前状态后再创建新提案。

配置

默认值采用保守设置。

schema_version: 1
repository:
  slug: owner/private-knowledge
publishing:
  approval_mode: always
privacy:
  fail_closed: true
search:
  lexical: true
  vector:
    enabled: false
maintenance:
  inline_budget_ms: 200
logging:
  content: never

大多数用户只需使用 init 生成的配置即可。仅在需要审批模式或按组织设置的阻断规则时，才使用 init --advanced 或 --privacy-rules-file。示例见 examples/privacy-rules.yaml。

详细选项与兼容性规则请参阅配置·运维文档，schema 请参阅 spec/schemas。

数据与安全原则

• private GitHub repository 是知识的唯一 SSOT，本地 SQLite 索引删除后可重新生成。

• 不得将业务原文、公司内部标识符、credential、private source code 放入 knowledge entry。

• 需要代码说明时，编写与原始代码相互独立的新示例。

• PAT 不会复制到 config 中，而是通过 read-only bind mount 传递给容器。

• 确保 config、PAT、private Markdown 与业务代码不进入 Git working tree 或 Docker build context。

• 日志中不记录知识正文与机密信息。

威胁模型与 privacy pipeline 请参阅安全·隐私文档，漏洞报告流程请参阅 SECURITY.md。

知识仓库格式

GitHub repository 中按 canonical schema 存储 knowledge entry、evidence card、challenge review、regression case 以及生成的 INDEX.md。目录、frontmatter、关系规则见知识仓库规范，搜索与更新策略见搜索·知识生命周期。

升级

release image 使用经过验证的 image digest 而非 mutable tag。通过 runtime init 创建稳定的 Compose descriptor 后，即使更换 PAT 或更新镜像也无需重新注册 MCP 客户端。先使用 upgrade --check 确认兼容性，再执行 runtime update-image --verified-release。schema·配置 migration 会随各版本 migration 文件自动应用，且不会随意覆盖原始配置。

详细流程请参阅迁移文档与安装·运维文档。

开发

如需贡献，请在 Node.js 24 及以上环境中执行以下命令。

npm ci
npm run check

测试·评估命令与变更规则请参阅测试·评估文档与系统架构。

延伸阅读

• 产品概述与需求

• 研究依据

• 系统架构

• MCP API 规范

• GitHub 存储·并发

• 安全·隐私

包许可证为 Apache-2.0。