Auto Knowledge Sync MCP

A local MCP server that organizes technical knowledge gained from LLM development sessions into complete documents and accumulates them as a personal or team knowledge source. The MCP runs as a Docker container on the user's computer, and the single source of truth (SSOT) for knowledge is kept in a private GitHub repository designated by the user.

Why is this needed?

Explanations, decisions, and cautions exchanged with an LLM during development are useful, but they easily disappear when the session ends. This project connects the following flow to your usual MCP usage pattern.

1. The LLM proposes technical knowledge worth reusing from the session.

2. The MCP checks the proposal for completeness, personal or company-sensitive information, and inclusion of original source code.

3. Only approved proposals are committed to the GitHub repository.

4. Knowledge is continuously updated through search, verification, challenge, and restructuring.

Stored documents are not simple keyword lists but standalone knowledge entries that explain concepts, how they work, technical significance, the problems they solve, and applicable conditions and limitations. When code examples are needed, only new examples are allowed—not copies or modifications of existing work code.

Related MCP server: MCP Enhanced Data Retrieval System

Key Features

• Remote SSOT: Knowledge and change history are recorded as GitHub commits. Only a regenerable search index and temporary data are kept locally.

• Sensitive Information Blocking: Built-in secret and PII checks plus optional organization-specific deny rules are applied, using a fail-closed policy that does not save anything when checks fail.

• Explicit Approval: The default approval mode is always. It can be set to on_risk or never only when needed, and security hard gates and high-risk changes are always verified.

• Knowledge Lifecycle: Supports not only search but also counterexample submission, stale and duplicate checks, relationship cleanup, and merge/split/reclassify/deprecate proposals.

• Serverless Operation: There is no always-on central server or operational database. The MCP runs locally when MCP clients such as Codex or Claude Code need it.

• Least Privilege: The PAT is granted only to the designated private repository, and the MCP does not require GitHub organization, Actions, or Pull request permissions.

Requirements

• Docker Desktop or Docker Engine

• A private GitHub repository to serve as the knowledge store

• A fine-grained PAT scoped to that repository only

  • Metadata: Read-only

  • Contents: Read and write

  • Do not grant Pull requests, Actions, or Administration permissions

• Node.js 24 or later and Git if building from source

Check your organization's external GitHub usage policy before storing company materials. On first run, it is recommended to verify the connection with synthetic technical content rather than actual work materials.

Quick Start

1. Prepare the source and local image

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. Create the PAT file and configuration

Do not put the PAT directly into a shell command line or YAML; manage it in an owner-only file.

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 creates the default configuration file and bootstraps the knowledge manifest into the repository. If you use the default configuration, you do not need to edit the YAML directly. The generated default paths are as follows.

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

3. Run connection diagnostics and register the MCP client

doctor checks the repository, PAT permissions, schema compatibility, and branch and cache status, and prints registration commands for Codex and 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"

Run the printed client_commands.codex or client_commands.claude command once in the corresponding client. After registration, you can verify the connection as follows:

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

If you need a client command that runs the host's build output directly instead of the image, omit --image-ref and the host mount options in doctor --client-commands. For a stable release image and a digest-pinned Compose runtime, see the installation and operations document.

Basic Usage

After connecting, use the following sequence with the LLM:

1. Check the remote repository and schema status with repository_status.

2. Read existing knowledge with search_knowledge or get_knowledge.

3. Propose new technical knowledge with capture_knowledge.

4. After checking the privacy and completeness results, commit with apply_proposal.

5. If outdated knowledge or counterexamples are found, use challenge_knowledge or maintain_knowledge.

The provided MCP tools are as follows:

All changes use idempotency keys and remote HEAD checks. If a conflict occurs, you are guided to search the current state again and create a new proposal.

Configuration

The defaults are set conservatively.

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

Most users only need the configuration generated by init. Use init --advanced or --privacy-rules-file only when you need approval modes or organization-specific block rules. Examples are in examples/privacy-rules.yaml.

For detailed options and compatibility rules, see the Configuration and Operations document; for the schema, see spec/schemas.

Data and Security Principles

• The private GitHub repository is the sole SSOT for knowledge, and the local SQLite index can be deleted and recreated.

• Do not include work originals, company identifiers, credentials, or private source code in knowledge entries.

• If code explanation is needed, write a new example independent of the original.

• The PAT is not copied into the config; it is passed to the container via a read-only bind mount.

• Keep the config, PAT, private Markdown, and work code out of the Git working tree and Docker build context.

• Logs do not record knowledge content or secrets.

For the threat model and privacy pipeline, see the Security and Privacy document; for vulnerability reporting procedures, see SECURITY.md.

Knowledge Repository Format

The GitHub repository stores knowledge entries, evidence cards, challenge reviews, regression cases, and a generated INDEX.md according to the canonical schema. Directory, frontmatter, and relationship rules are described in the Knowledge Repository Specification, and search and update policies are described in Search and Knowledge Lifecycle.

Upgrades

Release images use verified image digests instead of mutable tags. Creating a stable Compose descriptor with runtime init means you do not need to re-register MCP clients after PAT replacement or image updates. Check compatibility first with upgrade --check, then run runtime update-image --verified-release. Schema and configuration migrations are applied automatically with version-specific migration files and do not overwrite your original configuration arbitrarily.

For detailed procedures, see the Migration Document and the Installation and Operations Document.

Development

To contribute, run the following in a Node.js 24 or later environment:

npm ci
npm run check

For test and evaluation commands and change rules, see the Testing and Evaluation Document and the System Architecture.

Further Reading

• Product Overview and Requirements

• Research Basis

• System Architecture

• MCP API Specification

• GitHub Storage and Concurrency

• Security and Privacy

The package license is Apache-2.0.