World Model MCP

El reloj de eventos para agentes de programación. Un servidor MCP que construye un grafo de conocimiento temporal para tu base de código: captura trazas de decisiones de sesiones de Claude Code, las vincula a resultados de pruebas, aprende trayectorias y aplica restricciones en el límite de edición.

Estado: Alfa (v0.6.0) -- El reloj de eventos para agentes de programación. 22 herramientas MCP, 186 pruebas, aplicación de PreToolUse, trazas de decisiones, capa de predicción. Las contribuciones son bienvenidas.

Qué hace

World Model MCP crea un grafo de conocimiento temporal de tu base de código que aprende de cada sesión de Claude Code para:

• Prevenir alucinaciones - Valida referencias de API/funciones contra entidades conocidas antes de su uso

• Detener errores repetidos - Aprende restricciones de las correcciones y las aplica en sesiones futuras

• Reducir regresiones - Rastrea correcciones de errores y advierte cuando los cambios afectan regiones críticas

Piensa en ello como darle a Claude una memoria a largo plazo de tu proyecto.

Inicio rápido

Instalación

# 1. Install the package
pip install world-model-mcp

# 2. Setup in your project (auto-seeds the knowledge graph from existing code)
cd /path/to/your/project
python -m world_model_server.cli setup

# 3. Restart Claude Code
# Done! The world model is pre-populated and active

También puedes volver a sembrar o sembrar manualmente en cualquier momento:

# Seed from existing codebase
world-model seed

# Re-seed with force (re-processes already seeded files)
world-model seed --force

Qué se instala

your-project/
├── .mcp.json                    # MCP server configuration
├── .claude/
│   ├── settings.json           # Hook configuration
│   ├── hooks/                  # Compiled TypeScript hooks
│   └── world-model/            # SQLite databases (~155 KB)

Características

1. Prevención de alucinaciones

Antes:

// Claude invents an API that doesn't exist
const user = await User.findByEmail(email); // This method doesn't exist

Después:

// Claude checks the world model first
const user = await User.findOne({ email }); // Verified to exist

Objetivo: Reducir las referencias a APIs inexistentes validando contra el grafo de conocimiento

2. Aprendizaje a partir de correcciones

Sesión 1: El usuario corrige a Claude

// Claude writes:
console.log('debug info');

// User corrects to:
logger.debug('debug info');

// World model learns: "Use logger.debug() not console.log()"

Sesión 2: Claude utiliza el patrón aprendido

// Claude automatically writes:
logger.debug('debug info'); // No correction needed

Objetivo: Los patrones aprendidos persisten entre sesiones y evitan violaciones repetidas

3. Prevención de regresiones

// Week 1: Bug fixed (null check added)
if (user && user.email) { ... }

// Week 2: Refactoring
// World model warns: "This line preserves a critical bug fix"
// Claude preserves the null check

// Result: Bug not re-introduced

Objetivo: Detectar posibles regresiones antes de la ejecución del código

Cómo funciona

Arquitectura

┌──────────────────────────────────────────────────────────┐
│ Claude Code + Hooks                                      │
│ Captures: file edits, tool calls, user corrections       │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ MCP Server (Python)                                      │
│ - 22 MCP tools for querying/recording/predicting          │
│ - LLM-powered entity extraction (Claude Haiku)           │
│ - External linter integration (ESLint, Pylint, Ruff)     │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ Knowledge Graph (SQLite + FTS5)                          │
│ - entities.db: APIs, functions, classes                  │
│ - facts.db: Temporal assertions with evidence            │
│ - relationships.db: Entity dependency graph              │
│ - constraints.db: Learned rules from corrections         │
│ - sessions.db: Session history and outcomes              │
│ - events.db: Activity log with reasoning chains          │
└──────────────────────────────────────────────────────────┘

Conceptos clave

1. Hechos temporales: Cada hecho tiene marcas de tiempo validAt y invalidAt

   • "La función X existió desde el 15-01-2024 hasta el 20-03-2024"

   • Consulta: "¿Qué era cierto el 1 de marzo?"

2. Cadenas de evidencia: Cada afirmación se remonta a su origen

   • Hecho -> Sesión -> Evento -> Ubicación del código fuente

3. Aprendizaje de restricciones: Reconocimiento de patrones a partir de correcciones del usuario

   • Inferencia automática de tipos de reglas (linting, arquitectura, pruebas)

   • Detección de gravedad (error, advertencia, información)

   • Generación de ejemplos para referencia futura

4. Validación dual: Combina dos fuentes de validación

   • Restricciones del modelo mundial (aprendidas del usuario)

   • Linters externos (ESLint, Pylint, Ruff)

Herramientas MCP

Veintidós herramientas MCP disponibles para Claude Code:

1. query_fact

Comprueba si las APIs/funciones existen antes de usarlas

result = query_fact(
    query="Does User.findByEmail exist?",
    entity_type="function"
)
# Returns: {exists: bool, confidence: float, facts: [...]}

2. record_event

Captura la actividad de desarrollo con cadenas de razonamiento

record_event(
    event_type="file_edit",
    file_path="src/api/auth.ts",
    reasoning="Added JWT authentication middleware"
)

3. validate_change

Validación previa a la ejecución contra restricciones y linters

result = validate_change(
    file_path="src/api/auth.ts",
    proposed_content="..."
)
# Returns: {safe: bool, violations: [...], suggestions: [...]}

4. get_constraints

Recupera reglas específicas del proyecto para un archivo

constraints = get_constraints(
    file_path="src/**/*.ts",
    constraint_types=["linting", "architecture"]
)

5. record_correction

Aprende de las ediciones del usuario (ALTA PRIORIDAD)

record_correction(
    claude_action={...},
    user_correction={...},
    reasoning="Use logger.debug instead of console.log"
)

6. get_related_bugs

Evaluación de riesgo de regresión

result = get_related_bugs(
    file_path="src/api/auth.ts",
    change_description="refactoring authentication logic"
)
# Returns: {bugs: [...], risk_score: float, critical_regions: [...]}

7. seed_project

Escanea la base de código y completa el grafo de conocimiento con entidades y relaciones

result = seed_project(
    project_dir=".",
    force=False
)
# Returns: {files_seeded: int, entities_created: int, relationships_created: int}

8. ingest_pr_reviews

Extrae comentarios de revisión de PR de GitHub y convierte los comentarios del equipo en restricciones

result = ingest_pr_reviews(
    repo="owner/repo",  # Auto-detected from git remote if omitted
    count=10
)
# Returns: {prs_scanned: int, constraints_created: int, constraints_updated: int}

Documentación

• QUICKSTART.md - Guía de configuración de 5 minutos

• CONTRIBUTING.md - Directrices de contribución

• RELEASE_NOTES.md - Historial de versiones y características

Pruebas

# Run tests
pytest

# With coverage
pytest --cov=world_model_server --cov-report=html

186 pruebas que cubren CRUD del grafo de conocimiento, búsqueda FTS5, gestión de restricciones, seguimiento de errores, auto-siembra, ingesta de revisiones de PR, trazas de decisiones, vinculación de resultados, aprendizaje de trayectorias, capa de predicción, salud de la memoria, detección de contradicciones, punteros de transcripción, identidad del proyecto y aplicación de PreToolUse. Consulta tests/ para más detalles.

Configuración

Variables de entorno

# Database location (default: ./.claude/world-model/)
export WORLD_MODEL_DB_PATH="/custom/path"

# Anthropic API key (optional - enables LLM extraction)
# IMPORTANT: Never commit this! Use .env file (see .env.example)
export ANTHROPIC_API_KEY="your-api-key-here"

# Model selection
export WORLD_MODEL_EXTRACTION_MODEL="claude-3-haiku-20240307"  # Fast
export WORLD_MODEL_REASONING_MODEL="claude-3-5-sonnet-20241022"  # Accurate

# Debug mode
export WORLD_MODEL_DEBUG=1

Nota: Crea un archivo .env en la raíz de tu proyecto (consulta .env.example) - git lo ignora automáticamente.

Personalización de hooks

Edita .claude/settings.json para personalizar qué herramientas activan los hooks del modelo mundial:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|Bash",
      "hooks": [...]
    }]
  }
}

Soporte de idiomas

Actualmente soportado:

• TypeScript / JavaScript

• Python

Próximamente:

• Go, Rust, Java, C++

Arquitectura extensible: Fácil de añadir nuevos analizadores de lenguaje (consulta CONTRIBUTING.md)

Privacidad y seguridad

• Local-First: Todos los datos permanecen en tu máquina

• Sin telemetría: Cero seguimiento o transmisión de datos externos

• LLM opcional: Funciona sin clave API (usa patrones regex como alternativa)

• Almacenamiento cifrado: Las bases de datos SQLite son archivos locales (cifra tu disco para mayor seguridad)

Uso de clave API (solo si proporcionas ANTHROPIC_API_KEY):

• Extracción de entidades de cambios de código

• Inferencia de restricciones a partir de correcciones

• Nunca envía: Credenciales, secretos, PII

Mejores prácticas de seguridad:

• Nunca subas archivos .env al repositorio

• Usa .env.example como plantilla

• Almacena las claves API solo en variables de entorno o archivos .env

• El .gitignore excluye automáticamente los archivos sensibles

Hoja de ruta

v0.2.x

• [x] Auto-siembra: el grafo de conocimiento se completa desde la base de código existente en la configuración

• [x] Inteligencia de revisión de PR: ingesta comentarios de revisión de GitHub como restricciones

• [x] Seguimiento de relaciones: grafo de importación y dependencias entre entidades

• [x] Soporte multilingüe: Python, TypeScript/JavaScript, Solidity, Go, Rust

• [x] Comando de consulta CLI para búsquedas en el grafo de conocimiento

• [x] 40 pruebas, 8 herramientas MCP

v0.3.0

• [x] Coincidencia a nivel de módulo: la consulta por nombre de módulo encuentra el archivo y su contenido

• [x] Re-siembra incremental: solo reprocesa los archivos cambiados desde la última siembra

• [x] Coincidencia difusa de entidades: búsqueda aproximada de nombres para errores tipográficos y abreviaturas

• [x] Caché de consultas: caché en memoria con TTL para búsquedas repetidas

• [x] Soporte para Java: cobertura multilingüe completa

• [x] Validación de la canalización del servidor MCP en proyectos reales

v0.4.0

• [x] Vinculación de resultados: fallos de pruebas vinculados a cambios de código con hechos

• [x] Aprendizaje de trayectorias: patrones de co-edición rastreados entre sesiones

• [x] Captura de trazas de decisiones: registro estructurado de propuestas del agente y correcciones humanas

• [x] Búsqueda de entidades entre proyectos con registro de proyectos

• [x] 5 nuevas herramientas MCP (13 en total), 104 pruebas

v0.5.0

• [x] Predicción de regresión, simulación "qué pasaría si", predicción de fallos de pruebas

• [x] Transferencia de conocimiento entre proyectos, salud de la memoria, TTL/decadencia de hechos

• [x] Paquete de pre-edición get_context_for_action, seguimiento de violación de restricciones, find_contradictions

• [x] 20 herramientas MCP, 151 pruebas

v0.6.0 (Actual) — Aplicación, procedencia, identidad

• [x] Hook de aplicación de restricciones PreToolUse: denegar violaciones graves en el límite de edición

• [x] Punteros de transcripción indexados: hidratar cualquier hecho de vuelta a la conversación de origen

• [x] Desacoplamiento de la identidad del proyecto: UUID estable a través de cambios de nombre de directorio

• [x] Deduplicación por hash de contenido para hechos y restricciones

• [x] Generación automática de CLAUDE.md desde el grafo de conocimiento

• [x] Subclase BetaAbstractMemoryTool para la integración del SDK de Anthropic

• [x] Empaquetado de extensión de escritorio (.mcpb) para Claude Desktop

• [x] 22 herramientas MCP, 13 subcomandos CLI, 186 pruebas

v0.7.0 (Siguiente)

• [ ] Extracción basada en AST mediante tree-sitter

• [ ] Programador de decadencia de hechos en segundo plano (opcional)

• [ ] Contradicciones ponderadas por confianza con resolución automática

• [ ] Federación de restricciones a nivel de organización

Contribución

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para:

• Configuración de desarrollo

• Estándares de codificación

• Añadir soporte de idiomas

• Escribir pruebas

• Enviar PRs

Áreas donde se necesita ayuda:

• Analizadores de lenguaje (Go, Rust, Java, C++)

• Optimización del rendimiento

• Mejoras en la documentación

• Comentarios sobre pruebas en el mundo real

Estadísticas

Tamaño del proyecto:

• ~4,800 líneas de código

• 13 módulos de Python

• 3 implementaciones de hook de TypeScript

Eficiencia de almacenamiento:

• Base de datos vacía: ~155 KB

• Por entidad: ~500 bytes

• Por hecho: ~800 bytes

Licencia

Licencia MIT - Gratuita para uso comercial y personal

Soporte

• Problemas: GitHub Issues

• Discusiones: GitHub Discussions