Slipbox MCP Server

Dale a tu asistente de IA un papel activo en la gestión de tu conocimiento. Slipbox es un servidor MCP que convierte a cualquier agente compatible con MCP en un compañero Zettelkasten -- crea notas atómicas, forma enlaces semánticos, detecta clústeres emergentes y sintetiza ideas a partir de tu conocimiento existente.

Tus ideas entran, conocimiento estructurado sale. El agente se encarga del formato, los enlaces y la integración.

¿Nuevo en el método? Empieza con Introducción al método Zettelkasten para conocer el porqué de las notas atómicas y el pensamiento enlazado. Para ver cómo Slipbox prepara a tu agente con ese método, lee las instrucciones del servidor que envía automáticamente al conectarse.

Construido y probado con Claude. Funciona con cualquier cliente MCP (Claude Desktop, Claude Code, OpenCode, Copilot o cualquier cosa que hable MCP).

Archivos simples, cero dependencia. Las notas son markdown con frontmatter YAML -- legibles en Obsidian, Foam, Logseq o cualquier editor. La base de datos SQLite es un índice, no la fuente de verdad. Bórrala y reconstruye desde los archivos cuando quieras.

• 19 herramientas MCP para notas, enlaces, búsqueda, análisis de grafos y gestión de clústeres

• 6 indicaciones de flujo de trabajo (más las habilidades correspondientes) que codifican el método Zettelkasten para que no lo reaprendas en cada sesión

• Búsqueda de texto completo BM25 en títulos y contenido mediante SQLite FTS5

• Detección de clústeres que detecta grupos de temas emergentes y genera notas de estructura

• Siete tipos de enlaces (referencia, extiende, refina, contradice, cuestiona, apoya, relacionado)

Python 3.10+ | macOS o Linux

Recorrido

Related MCP server: vault-master-mcp

Inicio rápido

1. Instalación

pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcp

Esto coloca un lanzador slipbox-mcp en tu PATH (en ~/.local/bin). Ese único comando es todo el servidor MCP: sin clonar, sin PYTHONPATH, sin ruta de Python de venv fija. Todo lo que sigue lo utiliza. Para probarlo sin instalar nada, uvx slipbox-mcp ejecuta el servidor en un entorno desechable.

(¿Trabajas en el propio Slipbox? Consulta Desarrollo para la configuración de clonado e instalación editable.)

2. Elige un directorio de datos

Una variable, SLIPBOX_BASE_DIR, lo configura todo: las notas se guardan en <base>/data/notes y el índice SQLite en <base>/data/db/zettelkasten.db. El servidor los crea en la primera ejecución con permisos solo para el propietario (0700).

Apunta SLIPBOX_BASE_DIR (o las rutas individuales SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH que aparecen abajo) a un directorio de datos dedicado que controles, no a una ubicación compartida o del sistema. Estas rutas se usan tal cual: el servidor gestiona el árbol de notas y el índice dentro de ellas, y trata el directorio de notas como la fuente de verdad cuando reconstruye el índice.

# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipbox

Usa una ruta absoluta completa. Una ~ inicial no se expande dentro de los archivos de configuración del cliente MCP y crearía un directorio ~ literal.

3. Conéctalo a tu cliente MCP

Claude Code (un comando, sin editar archivos):

claude mcp add slipbox \
  --env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
  -- slipbox-mcp

Claude Desktop (edita el archivo de configuración):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "slipbox": {
      "command": "slipbox-mcp",
      "env": {
        "SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
      }
    }
  }
}

Advertencia sobre el PATH en Desktop: la aplicación de escritorio de macOS no siempre hereda ~/.local/bin en su PATH, por lo que el simple "slipbox-mcp" puede no resolverse. Si el servidor no se inicia, reemplaza "command": "slipbox-mcp" por la ruta absoluta que imprime which slipbox-mcp (normalmente /Users/yourname/.local/bin/slipbox-mcp).

Otros clientes MCP: registra slipbox-mcp como comando del servidor con SLIPBOX_BASE_DIR en su entorno. El comando y el entorno son los mismos en todas partes.

En lugar de SLIPBOX_BASE_DIR, establece rutas absolutas individualmente. El SLIPBOX_LOG_LEVEL opcional es uno de DEBUG, INFO, WARNING, ERROR.

"env": {
  "SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
  "SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
  "SLIPBOX_LOG_LEVEL": "INFO"
}

4. Reinicia y verifica

Reinicia tu cliente (Claude Code se recarga en el próximo lanzamiento; cierra y vuelve a abrir Claude Desktop).

Pregúntale a tu agente:

• "Crea una nota de prueba sobre algo"

• "Busca test en mi slipbox"

• "Encuentra notas huérfanas"

En acción

Lo que ves arriba es el bucle central. Esto es el resto de lo que hace el agente.

Mantenimiento proactivo

El agente lee el recurso slipbox://maintenance-status al inicio de la sesión y muestra los clústeres que necesitan organización.

Búsqueda de texto completo

Búsqueda clasificada por BM25 en todas las notas mediante slipbox_search_notes.

Grafo de conocimiento: notas centrales

slipbox_find_central_notes revela los anclajes estructurales del grafo -- las notas alrededor de las cuales orbita todo lo demás.

Análisis de notas

La indicación analyze_note evalúa la atomicidad, encuentra conexiones reales en el grafo existente, sugiere etiquetas y reescribe para mayor claridad.

Descomposición de fuentes

La indicación knowledge_creation divide un artículo en notas de literatura atómicas con la cita y los enlaces adecuados.

Detección de clústeres

slipbox_get_cluster_report encuentra grupos de etiquetas que coaparecen y que carecen de una nota de estructura. Se puntúan por tamaño, proporción de huérfanas, densidad de enlaces y actualidad.

Creación de notas de estructura

slipbox_create_structure_from_cluster crea el andamiaje de una nota de estructura, enlaza todas las notas miembros y descarta el clúster.

Notas huérfanas

slipbox_find_orphaned_notes saca a la luz conocimiento no integrado -- candidatas para conectar o eliminar.

Notas similares

slipbox_find_similar_notes calcula la similitud a partir de etiquetas compartidas, enlaces comunes y solapamiento de contenido.

Recorrido del grafo

slipbox_get_linked_notes muestra los enlaces tipados de una nota central, agrupados por tipo de enlace.

Síntesis de conocimiento

La indicación knowledge_synthesis encuentra puentes entre áreas no conectadas y propone notas de síntesis a partir de tu conocimiento existente.

Cero dependencia: archivos simples en Obsidian

Las notas son markdown simple. Abre la bóveda en Obsidian y todo funciona -- contenido renderizado, enlaces inversos y el grafo de conocimiento.

Para un grafo que represente los enlaces tipados en color (apoya, extiende, refina, ...) en lugar del grafo integrado no tipado de Obsidian, instala el plugin complementario Slipbox Semantic Graph -- una vista de grafo dirigido por fuerzas con títulos legibles y tipos de enlaces semánticos codificados por colores. Instálalo manualmente desde el lanzamiento 0.1.0: copia main.js, manifest.json y styles.css en <vault>/.obsidian/plugins/slipbox-graph/ y luego actívalo en Configuración → Plugins de la comunidad. (Una vez que se acepte en el directorio oficial, también podrás instalarlo mediante Configuración → Plugins de la comunidad → Explorar → buscar "Slipbox Semantic Graph".) Lee la misma sección id del frontmatter y ## Links que escribe el servidor, por lo que no se necesita configuración adicional. Abre la vista con el comando Abrir grafo semántico (Paleta de comandos) o con el icono de la cinta git-fork.

La leyenda de la parte superior asigna cada color a un tipo de enlace (extiende, refina, apoya, contradice, cuestiona, relacionado). Enfoca una nota de estructura y su constelación aparece. Aquí, Contract Testing Knowledge Map con sus notas miembros orbitando a su alrededor:

Opcional: detección automática de clústeres

El análisis de clústeres escanea todas las notas y calcula puntuaciones de similitud. Ejecutarlo a diario (6 a. m.) precalcula los resultados para que slipbox_get_cluster_report() responda al instante. Sin programación, la detección de clústeres se ejecuta bajo demanda, lo que resulta más lento para colecciones grandes.

Ejecútalo manualmente después de importaciones masivas, reorganizaciones importantes o cuando quieras resultados inmediatos.

Instalar la detección de clústeres (macOS)

chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.sh

El instalador detecta tu ruta de Python/venv, genera el plist de LaunchAgent y lo carga.

Prueba manual (vigilante de archivos)

source .venv/bin/activate
python scripts/detect_clusters.py

La salida se guarda en ~/.local/share/mcp/slipbox/cluster-analysis.json.

Desinstalar la detección de clústeres

./scripts/install-cluster-detection.sh --uninstall

Opcional: vigilante de archivos de macOS para la indexación automática

El servidor MCP mantiene un índice de base de datos para búsquedas rápidas. Editar notas en Obsidian (o en cualquier editor) deja la base de datos desactualizada hasta que ejecutes slipbox_rebuild_index.

El vigilante de archivos se ejecuta como demonio en segundo plano, supervisa tu directorio de notas y reconstruye automáticamente el índice cuando cambian los archivos .md.

Úsalo si editas notas con frecuencia en Obsidian mientras usas Claude.

Instalar el vigilante de archivos (macOS)

chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.sh

El instalador detecta tu ruta de Python/venv, instala watchdog si es necesario y carga el LaunchAgent. Se inicia al iniciar sesión y se reinicia si falla.

Prueba manual

source .venv/bin/activate
python scripts/watch_notes.py

Edita un archivo de nota. Deberías ver "reconstruyendo índice..." en la salida del vigilante.

Comprobar el estado

launchctl list | grep slipbox.watcher

# View logs

tail -f ~/.local/share/mcp/slipbox/watcher.log

Desinstalar el vigilante de archivos

./scripts/install-file-watcher.sh --uninstall

Indicación del sistema recomendada

Slipbox incluye una línea base automáticamente: cada cliente recibe las instrucciones del servidor al conectarse, que cubren cómo usar bien las herramientas -- tipos de notas, semántica de enlaces, estándares de calidad y flujos de trabajo básicos como buscar antes de crear. No tienes que añadirlas tú.

docs/SYSTEM_PROMPT.md es la capa de activación voluntaria que se añade encima: las directivas de autonomía e iniciativa que un servidor no debería imponer por su cuenta. Añádela a las preferencias de tu agente o a tu indicación del sistema para activar:

• Captura automática de conocimiento durante las conversaciones

• Detección de clústeres emergentes al inicio de la conversación

Referencia de herramientas

Operaciones básicas con notas

Enlaces

Búsqueda y descubrimiento

Análisis de clústeres

Mantenimiento

Referencia de prompts

Los prompts MCP son plantillas de flujo de trabajo reutilizables que codifican el método Zettelkasten para que no tengas que volver a explicarlo en cada sesión.

Cómo invocar: comandos slash y skills

Cada flujo de trabajo incluye dos formas:

• Prompts MCP: servidos por el servidor en ejecución.

• Skills: paquetes independientes (skills/<name>/) que ejecutan el mismo flujo de trabajo y añaden activación por lenguaje natural.

Cinco de las seis skills se generan a partir de las mismas plantillas PROMPT_* que usa el servidor (src/slipbox_mcp/server/descriptions.py), y el CI falla si las skills/ confirmadas se desvían de esas plantillas. La sexta, cluster-maintenance, se crea directamente en scripts/build_skills.py porque su prompt MCP es un mensaje de estado renderizado en tiempo de ejecución en lugar de un flujo de trabajo reutilizable.

Los comandos slash son la vía fiable. Claude Code muestra los prompts MCP como /mcp__<server>__<prompt>; escribe /mcp__slipbox-mcp__ para abrir el selector:

/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance

(Las skills instaladas también exponen sus propios comandos slash por nombre de directorio, p. ej. /slipbox-analyze-note).

El lenguaje natural funciona una vez instalada la skill correspondiente. Solo describe lo que quieres:

Analyze this note for my slipbox: [paste note]

Add this to my slipbox: [paste article]

Synthesize my notes on attention and memory.

La activación por prosa depende de que la skill esté instalada y de que tu redacción coincida con su descripción; recurre al comando slash si no se activa. Pedir al modelo que «use el prompt analyze_note» por su nombre no funciona. El modelo no puede invocar un prompt MCP por nombre. Usa un comando slash o deja que una skill se active mediante lenguaje natural.

Instalación de skills

Claude Code descubre las skills desde .claude/skills/ (por proyecto) o ~/.claude/skills/ (global), no desde un skills/ de nivel superior sin más. Crea enlaces simbólicos o copia las que quieras en una ruta de descubrimiento (p. ej., para este proyecto):

mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all six

Claude Desktop necesita cada skill como un paquete .skill. Constrúyelos y luego súbelos:

python scripts/build_skills.py     # writes dist/*.skill

Ve a Configuración → Skills → Upload skill y selecciona los paquetes de dist/ que quieras. Cada uno se instala como comando slash y como activador de lenguaje natural.

Después de editar una plantilla de prompt en descriptions.py, vuelve a ejecutar la compilación para regenerar las skills.

Tipos de enlaces

Tipos de notas

Estructura vs. Hub: Una nota de estructura organiza un clúster de notas permanentes en torno a un único tema. Es un mapa curado un nivel por encima de las propias notas. Una nota hub opera un nivel aún más alto: enlaza con notas de estructura (y ocasionalmente con notas permanentes clave) en todo un dominio de conocimiento. Mientras que una nota de estructura responde a «¿qué sé sobre X?», una nota hub responde a «¿cómo está organizado mi conocimiento de todo este dominio?». La mayoría de los Zettelkasten solo necesitan unas pocas notas hub.

Formato de archivo

Las notas se almacenan como archivos Markdown con frontmatter YAML:

---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
  - poetry
  - revision
  - craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---

# Poetry Revision Principles

Content here...

## Links

- reference [[20250728T125429845760000]] Member of structure

Puedes editar estos archivos directamente en cualquier editor de texto u Obsidian. Ejecuta slipbox_rebuild_index después de ediciones externas.

Actualización

Después de obtener nuevas versiones, reinicia Claude Desktop. Si las notas de la versión mencionan cambios en la base de datos, ejecuta slipbox_rebuild_index una vez para poner tu base de datos existente al día.

Actualización a la búsqueda FTS5 (cualquier versión posterior al lanzamiento de FTS5): El índice de búsqueda de texto completo se crea automáticamente cuando el servidor se inicia con una base de datos nueva. Para bases de datos existentes, la tabla FTS5 se creará en el primer arranque, pero estará vacía hasta que ejecutes:

slipbox_rebuild_index

Esto rellena el índice BM25 a partir de tus notas existentes. Los resultados de búsqueda no se clasificarán por relevancia hasta que se haga esto.

Solución de problemas

El servidor no se carga en Claude Desktop

1. Confirma que el lanzador se resuelve: which slipbox-mcp debería imprimir una ruta (normalmente ~/.local/bin/slipbox-mcp).

2. Si se resuelve en tu terminal pero Desktop aún no puede iniciarlo, la aplicación GUI no está viendo ~/.local/bin en su PATH. Reemplaza "command": "slipbox-mcp" con la ruta absoluta del paso 1.

3. Revisa los registros de Claude Desktop para ver errores.

slipbox-mcp: command not found

El script de consola no se instaló o no está en el PATH. Reinstala con pipx install --editable . --force y luego verifica con which slipbox-mcp. Si el directorio bin de pipx falta en el PATH, ejecuta pipx ensurepath y reinicia tu shell.

El directorio de notas apunta a ~/... literalmente

Si tu directorio de notas termina en ./~/... relativo al directorio de trabajo actual (CWD), usaste ~ en la configuración JSON. Claude Desktop no expande ~. Reemplázalo con la ruta absoluta completa.

La búsqueda no devuelve resultados

1. El índice FTS5 puede no estar poblado. Ejecuta slipbox_rebuild_index una vez para indexar las notas existentes.

2. Si editaste notas recientemente fuera de Claude, el índice puede estar desactualizado. Ejecuta slipbox_rebuild_index.

slipbox_list_notes_by_date devuelve resultados vacíos

Si start_date es posterior a end_date, no coincide ninguna nota y se devuelve un resultado vacío. Este es el comportamiento esperado, no un error.

Base de datos desincronizada

Si las notas se editaron fuera del servidor MCP:

slipbox_rebuild_index

La detección de clústeres no se está ejecutando

launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection

# Check logs

cat /tmp/slipbox-clusters.log

# Reinstall if needed

./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.sh

El observador de archivos no se está ejecutando

launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher

# Check logs

cat ~/.local/share/mcp/slipbox/watcher.log

# Reinstall if needed

./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.sh

Actualización desde variables de entorno ZETTELKASTEN_*

Si antes usabas ZETTELKASTEN_NOTES_DIR, ZETTELKASTEN_DATABASE_PATH u otras variables ZETTELKASTEN_*, ya no se leen. Renómbralas a sus equivalentes SLIPBOX_*:

El servidor registra una advertencia si detecta los nombres antiguos, pero no los migra automáticamente.

La ruta del informe de clústeres no es configurable

El informe de análisis de clústeres siempre se escribe en ~/.local/share/mcp/slipbox/cluster-analysis.json, independientemente de SLIPBOX_BASE_DIR o SLIPBOX_NOTES_DIR. Si usas rutas no predeterminadas, el informe de clústeres seguirá estando en la ubicación predeterminada.

Los scripts de instalación son solo para macOS

Los scripts scripts/install-cluster-detection.sh y scripts/install-file-watcher.sh usan launchctl y ~/Library/LaunchAgents/, que solo existen en macOS. En Linux, tendrás que crear unidades systemd o trabajos cron equivalentes manualmente. Consulta los comandos de prueba manuales en las secciones correspondientes del README para verificar que los scripts Python subyacentes funcionan en tu plataforma.

Las rutas predeterminadas son relativas al directorio de trabajo

Si SLIPBOX_NOTES_DIR y SLIPBOX_DATABASE_PATH no están configurados, el servidor usa por defecto data/notes y data/db/zettelkasten.db relativos al directorio de trabajo actual. Cuando se ejecuta mediante Claude Desktop, el CWD puede no ser el que esperas. Configura siempre rutas absolutas en claude_desktop_config.json para evitarlo.

Desarrollo

Configuración

git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"

Pruebas

El proyecto tiene tres niveles de pruebas:

# Default: runs unit + contract tests (CI runs this)

pytest

# Run everything except LLM evals

pytest tests/ evals/tool_contracts/

# Run LLM evals (requires claude CLI authenticated)

pytest evals/llm/ -v

# Run LLM evals with a specific model

EVAL_MODEL=sonnet pytest evals/llm/ -v

# Lint

ruff check src/ evals/

Las pruebas unitarias cubren la lógica interna: servicios, repositorio, modelos, análisis sintáctico.

Las pruebas de contrato de herramientas verifican el formato de salida de las herramientas MCP que ve el LLM: estructura analizable, encadenamiento (create -> search -> get) y mensajes de error útiles. Son deterministas y no llaman a ningún LLM.

Las evaluaciones LLM envían prompts a un LLM mediante la CLI claude con el servidor MCP conectado y luego califican los resultados inspeccionando el estado de la base de datos (notas creadas, enlaces hechos, etiquetas aplicadas). Prueban si el LLM usa realmente las herramientas correctamente dadas las descripciones de las herramientas.

CI/CD

Protección de ramas: Los envíos directos a main están bloqueados. Todos los cambios pasan por PR.

La suite de evaluación de LLM es costosa (~$3-5, ~10 min) y se ejecuta en un runner autoalojado, por lo que nunca se ejecuta automáticamente. Un disparador basado en rutas no puede distinguir un cambio real de prompt de un reformateo cosmético. Ejecútala deliberadamente cuando cambies la semántica de un prompt o de una descripción de herramienta:

• Añade la etiqueta run-llm-evals al PR. Se ejecuta y se vuelve a ejecutar en cada push mientras la etiqueta esté presente.

• O actívala manualmente desde la pestaña Actions (workflow_dispatch).

• O ejecútala localmente sin el runner: pytest evals/llm/ -v.

Sin etiqueta ni ejecución manual, el trabajo se omite (no se asigna runner, sin coste).

Personalización de la configuración de evaluación

Si no quieres un runner autoalojado: elimina .github/workflows/llm-evals.yml y ejecuta pytest evals/llm/ -v localmente antes de fusionar cambios de prompt.

Si quieres evaluaciones de LLM en cada PR automáticamente: añade un disparador pull_request con el filtro paths: relevante y elimina la condición de etiqueta en el if: del trabajo. Pero espera disparadores incidentales por ediciones solo de formato.

Para cambiar el modelo de evaluación predeterminado: establece EVAL_MODEL en tu entorno o en el archivo de workflow. El valor predeterminado es haiku por velocidad/coste.

Para configurar un runner autoalojado:

# Get a registration token

gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'

# Download and configure

mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &

Publicación en PyPI

Las releases están automatizadas. El workflow Release (.github/workflows/release.yml) ejecuta release-please en cada push a main y publica mediante Trusted Publishing de PyPI (OIDC, por lo que no se almacena ningún token de API en los secretos del repositorio).

El flujo (nunca editas una versión a mano ni haces push de una etiqueta):

1. Lleva los cambios a main con mensajes de Conventional Commit (feat: → incremento menor, fix: → parche, feat!:/BREAKING CHANGE: → mayor). Los hooks de commit del repositorio ya imponen esta forma.

2. release-please mantiene abierto de forma permanente un "release PR", acumulando el próximo incremento de versión (en src/slipbox_mcp/__init__.py) y las entradas de CHANGELOG.md derivadas de esos commits.

3. Cuando estés listo para publicar, fusiona el release PR. Eso etiqueta la release (v<version>) y, en la misma ejecución del workflow, compila el sdist + wheel, ejecuta twine check y publica en PyPI.

Así que publicar una release es un clic: fusiona el PR del bot. Nada más.

Los tipos de commit deciden la versión. Así que indica el tipo con precisión. El incremento se calcula mecánicamente a partir de los prefijos de Conventional Commit desde la última release, no del tamaño del cambio. Reserva feat:/fix: para cambios en el paquete publicado; usa los tipos sin release para todo lo demás:

Un lote de solo commits sin release no produce ningún release PR en absoluto. El título del squash-merge es el commit que lee release-please, así que el prefijo del título del PR es lo que cuenta. Etiquétalo por lo que gana el paquete, no por el esfuerzo invertido.

Configuración única (ya hecha para este repositorio, documentada para forks):

1. En PyPI, registra un publicador de confianza pendiente para el proyecto slipbox-mcp: Owner: jamesfishwick · Repository: slipbox-mcp · Workflow: release.yml · Environment: release. Los cuatro deben coincidir exactamente.

2. En GitHub, crea un entorno llamado release (Settings → Environments). Si restringes sus refs de despliegue, añade una regla de etiqueta v* (una regla de rama con el mismo nombre no coincidirá con la etiqueta).

La versión se define una sola vez, en src/slipbox_mcp/__init__.py (release-please la incrementa; el marcador # x-release-please-version le indica qué línea). pyproject.toml (dynamic = ["version"]) y el server_version del servidor leen de ahí, así que no hay nada que mantener sincronizado; la etiqueta que release-please crea siempre coincide con la versión del paquete por construcción.

Para ensayar una compilación sin publicar, ejecútala a mano: python -m build && twine check dist/* (y twine upload --repository testpypi dist/* con un token de TestPyPI para simular la subida).

Constantes compartidas de prompts

Todas las descripciones de herramientas y las plantillas de prompts están en src/slipbox_mcp/server/descriptions.py. Tanto el servidor MCP como las pruebas de evaluación importan desde esta única fuente de verdad. Si cambias un prompt, las evaluaciones comprueban si el LLM sigue comportándose correctamente con la nueva redacción.

Registro de depuración

SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"

Herramienta CLI

El comando slipbox proporciona acceso desde la terminal para operaciones mecánicas:

slipbox status          # Overview of notes, tags, orphans, pending clusters
slipbox search <query>  # Find notes by text
slipbox clusters        # Show pending structure note candidates
slipbox orphans         # List unconnected notes
slipbox rebuild         # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id>     # Export note markdown to stdout
slipbox tags            # List all tags with usage counts

Instalación: pipx install --editable . (añade slipbox a tu PATH)

Experimental: Slipbox como memoria del agente

Una hipótesis no probada, no una configuración recomendada. Todo lo anterior ayuda a un agente a gestionar tu conocimiento. Esto lo invierte: el agente usa un slipbox como su propia memoria persistente entre sesiones, en lugar de la memoria nativa o un archivo de reglas.

El modelo no tiene memoria entre sesiones, así que el slipbox es el único canal que una sesión deja para la siguiente. Escribe informes para un sucesor en frío (un fallo y por qué, una restricción recurrente, una corrección, un dato ganado con esfuerzo), los etiqueta con agent-memory, y busca esa etiqueta antes de actuar. La apuesta es que una memoria conectada supera a un archivo de reglas plano, porque la recuperas mediante recorrido.

Tres cosas que debes saber primero: el aislamiento de espacios de nombres es una convención de etiquetas, no un mecanismo impuesto, así que ejecútalo contra una instancia de slipbox separada; "memoria" es un nombre inapropiado, ya que no persiste nada excepto las propias notas; y la disciplina de crecimiento es la parte no probada, así que espera un crecimiento desordenado en la primera ejecución. Explicación completa y advertencias: Slipbox as Agent Self-Memory.

Documentación

Contribución

Consulta CONTRIBUTING.md para las instrucciones de configuración, los estándares de codificación y cómo enviar cambios.

Hoja de ruta

Consulta ROADMAP.md para las funciones planificadas y la dirección futura.

Patrocinio

Si slipbox-mcp te resulta útil, considera patrocinar el proyecto.

Licencia

MIT