ixr

ixr indexa frontmatter YAML de ficheros Markdown en SQLite + FTS5 para poder consultarlos por CLI o por MCP.

• Schemas YAML independientes
• Resolución en cascada: _schema > schema.yml de directorio > reglas de config
• Fallback a _untyped para documentos sin schema
• Indexación full e incremental con git
• Query con filtros exactos y full-text search
• MCP server sobre stdio para agentes

Estado

El proyecto ya es funcional, pero sigue en evolución. La especificación canónica está en specs/.

Requisitos

• Go 1.23+
• Git, si quieres indexación incremental

Instalación

Con go install

go install github.com/kdd/ixr@latest

Compilando localmente

go build -o ixr .

Quickstart

Inicializa el proyecto:

ixr init

Eso crea:

.ixr/
  config.yml
  index.db

Ejemplo de .ixr/config.yml:

version: "1"
db_path: .ixr/index.db

schemas:
  - schemas/specs.yml

rules:
  - glob: "specs/**/*.md"
    schema: specs

Ejemplo de schema schemas/specs.yml:

name: specs
fields:
  - name: kind
    type: enum
    values: [entity, event, business-rule, command, query]
    required: true
  - name: status
    type: enum
    values: [draft, review, approved, deprecated]
  - name: id
    type: string

Ejemplo de documento:

---
id: BR-001
kind: business-rule
status: draft
---

Regla de ejemplo.

Indexa el proyecto:

ixr index --full

Haz consultas:

ixr query specs kind=business-rule status=draft
ixr query specs --search="ejemplo" --format json
ixr query _untyped title=Loose

Valida documentos:

ixr validate
ixr validate --strict

Mira el inventario y el estado del índice:

ixr list-schemas
ixr stats

Comandos

ixr init

Crea .ixr/, inicializa SQLite y genera config.yml.

ixr index

Indexa Markdown en SQLite.

• --full: fuerza full scan
• sin --full: usa incremental con git cuando puede; si no, cae a full scan

ixr validate

Valida documentos contra el schema resuelto.

• detecta required, tipos y enums
• reporta documentos sin schema como warning
• --strict hace que los warnings fallen el comando

ixr list-schemas

Lista los schemas conocidos y sus campos.

ixr stats

Muestra conteos por tabla, último commit indexado, timestamp de indexación y tamaño de la DB.

ixr query

Consulta el índice.

Ejemplos:

ixr query specs kind=entity
ixr query specs kind=entity --fields _source_path,kind,status
ixr query specs --search="schema" --format json
ixr query _untyped title=Loose

Opciones principales:

• --format table|json|csv
• --fields a,b,c
• --filter field=value
• --search "texto"
• --limit N

MCP

ixr expone un servidor MCP sobre stdio:

ixr mcp

Tools disponibles:

• ixr_query
• ixr_list
• ixr_schemas
• ixr_stats
• ixr_validate

Ejemplo mínimo:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ixr_query","arguments":{"schema":"specs","filters":{"kind":"entity"}}}}

Tipos soportados

• string
• string[]
• date
• enum
• boolean
• number

Notas

• .ixr/ ya está en .gitignore en este repo; index.db es un artefacto derivado y no conviene comitearlo.
• Si actualizas a una versión que añade FTS o cambia estructuras internas, ejecuta ixr index --full para reconstruir el índice.
• La búsqueda actual soporta filtros exactos y FTS; no hay paginación ni operadores complejos todavía.

Desarrollo

go test ./...
go build ./...

Las decisiones y reglas del sistema están documentadas en specs/.