Auto Knowledge Sync MCP

Es un servidor MCP local que organiza el conocimiento técnico obtenido en sesiones de desarrollo con LLM en documentos completos y lo acumula como fuente de conocimiento personal o de equipo. El MCP se ejecuta como contenedor Docker en el ordenador del usuario, y la única fuente de verdad (SSOT) del conocimiento se guarda en un repositorio privado de GitHub designado por el usuario.

¿Por qué es necesario?

Las explicaciones, decisiones y advertencias intercambiadas con el LLM durante el desarrollo son útiles, pero desaparecen fácilmente al terminar la sesión. Este proyecto conecta el siguiente flujo con la forma habitual de usar MCP.

1. El LLM propone conocimiento técnico con valor de reutilización durante la sesión.

2. El MCP comprueba la completitud del documento, la información personal y confidencial de la empresa, y si incluye código original.

3. Solo las propuestas aprobadas se confirman (commit) en el repositorio de GitHub.

4. Después, el conocimiento se sigue actualizando mediante búsqueda, verificación, challenge y reestructuración.

Los documentos guardados no son simples listas de palabras clave, sino entradas de conocimiento (knowledge entry) independientes que explican el concepto, el modo de funcionamiento, la relevancia técnica, el problema que resuelven, y las condiciones y limitaciones de aplicación. Si se necesita un ejemplo de código, solo se permiten ejemplos nuevos, no copias o variaciones del código de trabajo existente.

Related MCP server: MCP Enhanced Data Retrieval System

Características principales

• SSOT remoto: El conocimiento y el historial de cambios quedan registrados como commits de GitHub. En local solo se guardan el índice de búsqueda regenerable y datos temporales.

• Bloqueo de información sensible: Aplica comprobaciones integradas de secretos y PII, y reglas de denegación opcionales por organización, con una política fail-closed que no guarda nada si la comprobación falla.

• Aprobación explícita: El modo de aprobación predeterminado es always. Solo cuando sea necesario se puede configurar como on_risk o never; el hard gate de seguridad y los cambios de alto riesgo siempre se verifican.

• Ciclo de vida del conocimiento: Además de la búsqueda, admite el envío de contraejemplos, la comprobación de contenido obsoleto (stale) y duplicados, la organización de relaciones, y propuestas de merge/split/reclassify/deprecate.

• Operación sin servidor: No hay un servidor central en ejecución continua ni una base de datos operativa. El MCP se ejecuta localmente cuando un cliente MCP como Codex o Claude Code lo necesita.

• Mínimos privilegios: El PAT se concede solo a un repositorio privado designado, y el MCP no solicita permisos de organización, Actions ni pull requests de GitHub.

Requisitos

• Docker Desktop o Docker Engine

• Un repositorio privado de GitHub para usar como almacén de conocimiento

• Un PAT de grano fino (fine-grained) que seleccione únicamente ese repositorio

  • Metadata: Read-only

  • Contents: Read and write

  • No conceder permisos de Pull requests, Actions ni Administration

• Node.js 24 o superior y Git si se compila desde el código fuente

Antes de guardar material de la empresa, consulte la política de la organización sobre el uso externo de GitHub. En la primera ejecución se recomienda verificar la conexión con contenido técnico sintético, no con material de trabajo real.

Inicio rápido

1. Preparación del código fuente y la imagen local

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. Creación del archivo PAT y la configuración

No ponga el PAT directamente en la línea de comandos del shell ni en YAML; adminístrelo en un archivo de solo propietario (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 crea el archivo de configuración predeterminado y arranca (bootstrap) el manifest de conocimiento en el repositorio. Si usa la configuración predeterminada, no necesita editar el YAML manualmente. Las rutas predeterminadas generadas son las siguientes:

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

3. Diagnóstico de conexión y registro del cliente MCP

doctor comprueba el repositorio, los permisos del PAT, la compatibilidad del schema, y el estado de la rama (branch) y la caché, y muestra los comandos de registro para Codex y 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"

Ejecute una vez el comando client_commands.codex o client_commands.claude mostrado en el cliente correspondiente. Tras el registro, puede verificar la conexión con lo siguiente:

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

Si necesita un comando de cliente que ejecute directamente el resultado de la compilación del host en lugar de la imagen, omita --image-ref y las opciones de montaje del host en doctor --client-commands. Consulte el documento de instalación y operación para la imagen de release estable y el runtime Compose con digest fijado.

Uso básico

Tras la conexión, el LLM lo usa en el siguiente orden:

1. Compruebe el estado del repositorio remoto y del schema con repository_status.

2. Lea el conocimiento existente con search_knowledge o get_knowledge.

3. Proponga nuevo conocimiento técnico con capture_knowledge.

4. Tras revisar las comprobaciones de privacidad y completitud del resultado, confírmelo (commit) con apply_proposal.

5. Si encuentra conocimiento obsoleto o contraejemplos, use challenge_knowledge o maintain_knowledge.

Las herramientas MCP disponibles son las siguientes:

Todos los cambios usan una clave de idempotencia (idempotency key) y la comprobación del HEAD remoto. Si se produce un conflicto, se indica que vuelva a buscar el estado actual y cree una nueva propuesta.

Configuración

Los valores predeterminados están configurados de forma conservadora.

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

La mayoría de los usuarios solo necesitan la configuración generada por init. Use init --advanced o --privacy-rules-file únicamente cuando necesite el modo de aprobación o reglas de bloqueo por organización. Hay un ejemplo en examples/privacy-rules.yaml.

Consulte las opciones detalladas y las reglas de compatibilidad en el documento de configuración y operación, y el schema en spec/schemas.

Datos y principios de seguridad

• El repositorio privado de GitHub es el único SSOT del conocimiento; el índice SQLite local se puede eliminar y volver a crear.

• No incluya textos originales de trabajo, identificadores internos, credenciales ni código fuente privado en las entradas de conocimiento.

• Si necesita explicar código, escriba ejemplos nuevos e independientes del original.

• El PAT no se copia en la configuración; se pasa al contenedor mediante un bind mount de solo lectura.

• Asegúrese de que la configuración, el PAT, los Markdown privados y el código de trabajo no entren en el árbol de trabajo de Git ni en el contexto de compilación de Docker.

• No se registran en los logs el cuerpo del conocimiento ni los secretos.

Consulte el modelo de amenazas y el pipeline de privacidad en el documento de seguridad y privacidad, y el procedimiento de notificación de vulnerabilidades en SECURITY.md.

Formato del almacén de conocimiento

En el repositorio de GitHub se guardan entradas de conocimiento (knowledge entry), tarjetas de evidencia (evidence card), revisiones de challenge (challenge review), casos de regresión (regression case) y el INDEX.md generado, según el schema canónico. Las reglas de directorios, frontmatter y relaciones se describen en la especificación del almacén de conocimiento, y las políticas de búsqueda y actualización en búsqueda y ciclo de vida del conocimiento.

Actualización

La imagen de release usa un digest de imagen verificado en lugar de una etiqueta mutable (mutable tag). Si crea un descriptor Compose estable con runtime init, no necesitará volver a registrar el cliente MCP tras sustituir el PAT o actualizar la imagen. Compruebe primero la compatibilidad con upgrade --check y luego ejecute runtime update-image --verified-release. Las migraciones de schema y configuración se aplican automáticamente con los archivos de migración por versión, sin sobrescribir arbitrariamente la configuración original.

Consulte el procedimiento detallado en el documento de migraciones y en el documento de instalación y operación.

Desarrollo

Para contribuir, ejecute lo siguiente en un entorno con Node.js 24 o superior:

npm ci
npm run check

Consulte los comandos de prueba y evaluación y las reglas de cambios en el documento de pruebas y evaluación y en arquitectura del sistema.

Lecturas adicionales

• Visión general del producto y requisitos

• Fundamento de la investigación

• Arquitectura del sistema

• Especificación de la API MCP

• Almacenamiento y concurrencia en GitHub

• Seguridad y privacidad

La licencia del paquete es Apache-2.0.