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として残ります。ローカルには再生成可能な検索インデックスと一時データのみ置きます。

• 機密情報の遮断: built-in secret・PII検査と選択的な組織別deny ruleを適用し、検査失敗時は保存しないfail-closedポリシーを使用します。

• 明示的承認: デフォルトの承認モードはalwaysです。必要な時だけon_riskまたはneverに設定でき、セキュリティhard gateと高リスク変更は常に検証されます。

• 知識ライフサイクル: 検索だけでなく、反例の提出、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をbootstrapします。デフォルト設定をそのまま使えば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にはknowledge entry、evidence card、challenge review、regression caseと生成されたINDEX.mdがcanonical schemaに従って保存されます。ディレクトリ・frontmatter・関係ルールは知識リポジトリ仕様、検索と更新ポリシーは検索・知識ライフサイクルに説明されています。

アップグレード

release imageはmutable tagの代わりに検証済みのimage digestを使用します。runtime initでstable 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です。