slivingdoc

Cobertura de pruebas: 83.7% 😍👌

Características

• Semántica tipo Git: slivingdoc usa terminología que todos (y los agentes) conocemos, diseñada para facilitar su uso

• Resolución automática de conflictos: haz commit sin miedo; confía en que todos los conflictos deben resolverse antes de ser aceptados

• Procesamiento de alta velocidad: la solución es bastante simple conceptualmente, lo que permite una escala y paralelismo muy altos

• Plug-and-play: configura el bucket, apunta a él y ¡empieza a sincronizar notas!

docs/slivingdoc-v1.md es el contrato completo aceptado que respalda estas garantías.

Related MCP server: Cellar

Primeros pasos

Agrégalo a tu entorno de agente:

{
  "mcpServers": {
    "slivingdoc": {
      "command": "npx",
      "args": [
        "-y",
        "slivingdoc",
        "serve",
        "--bucket",
        "my-notes",
        "--workspace-root",
        "/srv/notes"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your-access-key-id>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-access-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

El bucket debe existir, y las credenciales provienen de la cadena normal de AWS. ¿Aún no tienes una cuenta S3? examples/seaweedfs/ ejecuta un contenedor local de SeaweedFS con un tutorial paso a paso. También puedes descargar un binario nativo directamente desde el lanzamiento de GitHub (slivingdoc-v<semver>-<os>-<arch>) y ejecutarlo directamente.

Plataformas compatibles: Linux (amd64, ARMv7 de 32 bits, arm64), macOS (amd64, arm64) y Windows (amd64). El artefacto ARM de Linux de 32 bits es compatible con Raspberry Pi OS armhf.

Cómo funciona

El servidor expone dos herramientas MCP sobre stdio:

notes_pull escribe el cuaderno actual en tu directorio. notes_commit publica tus cambios e incorpora cambios concurrentes no conflictivos. Entre llamadas no hay ningún protocolo — los agentes editan los archivos con las herramientas que ya tienen, y los humanos pueden escribir en el mismo directorio con cualquier editor. El próximo commit también lleva sus cambios.

Los humanos también pueden ejecutar ambas operaciones directamente, sin un host MCP. Una ruta relativa se resuelve respecto al directorio de trabajo:

slivingdoc pull notes
# edit UTF-8 text files under notes/
slivingdoc commit notes -m "meeting summary"

El éxito imprime el informe de resultado unificado: el estado OK, la generación remota aceptada, los recuentos de inserciones y eliminaciones por archivo, y un resumen total. Un error de dominio sale con código distinto de cero e imprime un informe sincero: la categoría del error, el veredicto de reintentable, y cada archivo conflictivo con sus rangos de línea. El color aparece solo en una terminal real y se deshabilita con cualquier valor no vacío de NO_COLOR.

La parte de git

Dejar que todos los agentes escriban a la vez funcionaría, pero se verían superados por condiciones de carrera. Por lo tanto, slivingdoc tiene git integrado mediante libgit2 que efectivamente hace:

1. git pull

2. (posible resolución de conflictos local)

3. git add .

4. git commit -m "<mensaje del agente>"

5. git push

6. (posible resolución de conflictos local)

Todas estas operaciones de git se manejan localmente dentro de un espejo privado del directorio de notas, dejando una secuencia git "simplificada". Esto funciona gracias a dos compromisos: primero, el directorio local de notas es propenso a cambios en notes_pull, la precedencia la tiene el estado remoto, dejando marcadores de conflicto. Segundo, el sistema solo funciona para texto (UTF-8 limpio).

Configuración

serve, pull y commit leen las mismas banderas y variables de entorno. --bucket es obligatorio. Las banderas más comunes:

slivingdoc serve -h imprime la referencia completa, y docs/running.md cubre todo lo que un operador necesita: todas las banderas, los permisos exactos de S3, el registro (LOG_LEVEL en stderr), las reglas del cuaderno, la recuperación de conflictos y la retención de puntos de control. El módulo de Terraform en terraform/ aprovisiona un bucket y un usuario IAM con privilegios mínimos para un cuaderno.

Desarrollo

• AGENTS.md — la guía para desarrolladores y agentes: mapa de paquetes, flujos de operación, convenciones y las puertas de control de calidad.

• docs/slivingdoc-v1.md — el contrato de arquitectura aceptado.

• docs/build.md — la compilación nativa, desde la fuente de libgit2 fijada hasta la inspección de dependencias.

• docs/testing.md — los comandos de prueba, las capas de prueba y la regla de no usar AWS en vivo.

• docs/releasing.md — artefactos de lanzamiento, publicación confiable de npm y make release.

make qa #lint plus the full Go and npm test suites

Licencia

MIT — consulta LICENSE. Los avisos de terceros para libgit2 vinculado estáticamente están en NOTICE.

No afiliado con Paris Hilton.