codicil

Codicil

Documentación duradera y buscable para asistentes de codificación compatibles con MCP.

Codicil indexa la documentación ya presente en un repositorio y expone dos herramientas MCP: query_docs para recuperación y reindex_docs para actualizaciones. Utiliza un endpoint de embeddings compatible con Ollama cuando está disponible. Si el endpoint no está disponible, la búsqueda continúa con un respaldo por palabras clave que lee los archivos actuales del disco.

Estado: software temprano, para un solo usuario. El índice central y las rutas de respaldo están probados, pero la interfaz de línea de comandos y el formato de almacenamiento pueden cambiar antes de una versión estable.

Qué Hace

• Indexa archivos .md, .mdx, .rst, .txt, .yaml, .yml y .toml.
• Divide Markdown en encabezados H1 y H2; otros archivos usan fragmentos de caracteres superpuestos.
• Almacena un índice Chroma local en .codicil/ de forma predeterminada.
• Devuelve coincidencias semánticas cuando hay embeddings disponibles, o coincidencias por palabras clave cuando no las hay.
• Reindexa de forma incremental usando marcas de tiempo de modificación de archivos.

Directorios como .git, .venv, node_modules, dist, build y .codicil están excluidos. Los archivos sin contenido indexable se registran como vacíos y eliminan cualquier fragmento anterior.

Inicio Rápido

Requisitos: Python 3.11+ y un host tipo Unix. Codicil usa un bloqueo de archivo de carácter consultivo para proteger su almacenamiento local.

python3.11 -m venv .venv
./.venv/bin/pip install -e ".[dev]"

# Optional: works without an embedding server, using keyword fallback.
./.venv/bin/codicil index .
./.venv/bin/codicil serve .

serve inicia el servidor MCP stdio. Si su índice seleccionado está vacío, intenta un índice inicial automáticamente. Sin un endpoint de embeddings accesible, ese índice inicial omite los embeddings semánticos y query_docs aún busca los archivos directamente.

Ejecuta la suite de pruebas sin conexión con:

./.venv/bin/python -m pytest -q

Conectar un Cliente MCP

El repositorio incluye esta configuración local de Claude Code:

{
  "mcpServers": {
    "codicil": {
      "command": ".venv/bin/codicil",
      "args": ["serve", "."]
    }
  }
}

Coloca una configuración equivalente en el repositorio que quieras buscar, ajustando command a la ruta absoluta del ejecutable codicil instalado cuando sea necesario. La ruta pasada a serve es el repositorio que Codicil indexa.

Tu cliente puede entonces llamar:

query_docs(query="How is the reverse proxy configured?", n_results=5)
reindex_docs(force=false)

Ilustrativo: la interfaz de chat de Claude Code no es algo que una grabación de terminal pueda reproducir.

El GIF anterior es salida real y sin editar: la misma función query_docs llamada directamente en una terminal en lugar de a través de MCP. No había ningún host de embeddings local ejecutándose cuando se grabó, por lo que responde mediante el respaldo por palabras clave, no mediante búsqueda semántica: una demostración en vivo del comportamiento de degradar en lugar de fallar que este proyecto realmente busca.

n_results debe estar entre 1 y 10. reindex_docs() es la forma compatible de actualizar un índice mientras el servidor MCP posee el almacenamiento.

Embeddings y Respaldo

De forma predeterminada, Codicil llama a http://localhost:11434/api/embeddings con el modelo nomic-embed-text. Inicia un servicio local compatible para habilitar la búsqueda semántica y luego indexa el repositorio:

export CODICIL_EMBED_URL=http://localhost:11434
export CODICIL_EMBED_MODEL=nomic-embed-text
./.venv/bin/codicil index .

Para modelos nomic, Codicil usa automáticamente los prefijos recomendados de tarea de documento y consulta. Otros nombres de modelo se envían sin prefijos.

Si no se puede alcanzar el host de embeddings, o el índice seleccionado no tiene fragmentos, query_docs usa búsqueda por palabras clave sobre el repositorio. Los resultados por palabras clave clasifican los archivos según los términos de consulta coincidentes e incluyen líneas cercanas; son útiles pero no comprenden sinónimos ni similitud semántica.

Usar un endpoint de embeddings remoto envía texto indexado y consultas de búsqueda a ese endpoint. Mantén la URL predeterminada de localhost o usa un endpoint en el que confíes. No confirmes nombres de host ni credenciales privados en .mcp.json.

Configuración

La configuración se lee cuando se inicia el módulo del servidor, así que establece las variables de entorno antes de ejecutar codicil o lanzar tu cliente MCP.

Variable	Predeterminado	Significado
CODICIL_REPO	.	Repositorio a indexar. La CLI lo establece desde su argumento de ruta.
CODICIL_STORE	<repo>/.codicil	Datos locales de Chroma, estado del índice y archivo de bloqueo.
CODICIL_EMBED_URL	http://localhost:11434	URL base del host de embeddings compatible con Ollama.
CODICIL_EMBED_MODEL	nomic-embed-text	Modelo de embeddings solicitado al host.
CODICIL_EMBED_WORKERS	3	Solicitudes de embeddings concurrentes durante la indexación.
CODICIL_MIN_SCORE	0.5	Puntuación mínima de similitud semántica devuelta por query_docs.

Cambiar CODICIL_EMBED_MODEL selecciona una colección y un archivo de estado separados, evitando dimensiones de vectores incompatibles. Ejecuta codicil index después de cambiar de modelo; las colecciones existentes permanecen en el almacenamiento hasta que elimines deliberadamente el almacenamiento mientras ningún proceso de Codicil esté en ejecución.

Operaciones y Limitaciones

codicil index [path] indexa un repositorio y sale. Añade --force para ignorar las marcas de tiempo registradas y re-embedir cada archivo indexable. codicil serve [path] ejecuta el servidor MCP.

Solo un proceso de Codicil puede usar un almacenamiento a la vez. Iniciar codicil index mientras codicil serve owns the same store fails intentionally. Use reindex_docs desde el servidor MCP en ejecución, o detén el servidor antes de ejecutar el indexador CLI.

Codicil está diseñado actualmente para un repositorio local y un usuario. No proporciona vigilancia de archivos, ganchos de git, acceso multiusuario ni recuperación entre repositorios.

Solución de Problemas

• "el almacenamiento ya está en uso": otro proceso de Codicil posee CODICIL_STORE. Detenlo, o llama a reindex_docs a través de ese servidor MCP en ejecución.
• Resultados por palabras clave en lugar de puntuaciones: el endpoint de embeddings no está disponible o el modelo seleccionado aún no se ha indexado. Comprueba CODICIL_EMBED_URL y luego ejecuta codicil index.
• No hay archivos coincidentes: confirma que la extensión de archivo es compatible y que no está en un directorio excluido. Las consultas con solo palabras de dos caracteres o menos no tienen términos de búsqueda de respaldo.
• Necesitas una reconstrucción limpia: detén todos los procesos de Codicil, luego elimina el almacenamiento local y ejecuta codicil index. Esto elimina permanentemente todas las colecciones locales de ese almacenamiento.

Para detalles de desarrollo e invariantes de fiabilidad, consulta CLAUDE.md. Para una guía de instalación más detallada, consulta docs/SETUP.md.

Licencia

Publicado bajo la Licencia MIT.