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.

👁 PyPI
👁 Descargas
👁 Licencia: MIT
👁 Python 3.11+

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.

Related MCP server: NervusDB MCP Server

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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• export_claude_mdB
• find_contradictionsC
• get_agents_md_constraintsB
• get_co_edit_suggestionsC
• get_compaction_auditA
• get_constraintsC
• get_context_for_actionB
• get_decision_logC