World Model MCP

Событийные часы для агентов кодирования. MCP-сервер, который строит темпоральный граф знаний для вашей кодовой базы — фиксирует цепочки решений из сессий Claude Code, связывает их с результатами тестов, изучает траектории и обеспечивает соблюдение ограничений на границе редактирования.

Статус: Alpha (v0.6.0) — Событийные часы для агентов кодирования. 22 MCP-инструмента, 186 тестов, принудительное применение PreToolUse, цепочки решений, уровень прогнозирования. Приветствуется участие в разработке.

PyPI Downloads License: MIT Python 3.11+

Что он делает

World Model MCP создает темпоральный граф знаний вашей кодовой базы, который учится на каждой сессии Claude Code, чтобы:

Предотвращать галлюцинации — проверяет ссылки на API/функции по известным сущностям перед использованием
Останавливать повторяющиеся ошибки — изучает ограничения на основе исправлений и применяет их в будущих сессиях
Снижать количество регрессий — отслеживает исправления ошибок и предупреждает, когда изменения затрагивают критические области

Думайте об этом как о предоставлении Claude долговременной памяти о вашем проекте.

Быстрый старт

Установка

# 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

Вы также можете выполнить повторное или ручное заполнение (seed) в любое время:

# Seed from existing codebase
world-model seed

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

Что устанавливается

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

Функции

1. Предотвращение галлюцинаций

До:

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

После:

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

Цель: Сократить количество несуществующих ссылок на API путем проверки по графу знаний

2. Обучение на исправлениях

Сессия 1: Пользователь исправляет Claude

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

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

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

Сессия 2: Claude использует изученный шаблон

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

Цель: Изученные шаблоны сохраняются между сессиями и предотвращают повторные нарушения

3. Предотвращение регрессий

// 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

Цель: Обнаружение потенциальных регрессий до выполнения кода

Как это работает

Архитектура

┌──────────────────────────────────────────────────────────┐
│ 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          │
└──────────────────────────────────────────────────────────┘

Ключевые концепции

Темпоральные факты: Каждый факт имеет временные метки validAt и invalidAt
- "Функция X существовала с 2024-01-15 по 2024-03-20"
- Запрос: "Что было истинным на 1 марта?"
Цепочки доказательств: Каждое утверждение восходит к источнику
- Факт -> Сессия -> Событие -> Расположение исходного кода
Обучение ограничениям: Распознавание шаблонов на основе исправлений пользователя
- Автоматический вывод типа правила (линтеры, архитектура, тестирование)
- Обнаружение серьезности (ошибка, предупреждение, информация)
- Генерация примеров для будущих ссылок
Двойная проверка: Объединяет два источника проверки
- Ограничения модели мира (изученные от пользователя)
- Внешние линтеры (ESLint, Pylint, Ruff)

MCP-инструменты

Двадцать два MCP-инструмента, доступных для Claude Code:

1. `query_fact`

Проверка существования API/функций перед их использованием

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

2. `record_event`

Фиксация активности разработки с цепочками рассуждений

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

3. `validate_change`

Предварительная проверка изменений на соответствие ограничениям и линтерам

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

4. `get_constraints`

Получение специфичных для проекта правил для файла

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

5. `record_correction`

Обучение на правках пользователя (ВЫСОКИЙ ПРИОРИТЕТ)

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

6. `get_related_bugs`

Оценка риска регрессии

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`

Сканирование кодовой базы и заполнение графа знаний сущностями и связями

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

8. `ingest_pr_reviews`

Получение комментариев к PR из GitHub и преобразование отзывов команды в ограничения

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}

Документация

QUICKSTART.md — 5-минутное руководство по настройке
CONTRIBUTING.md — Руководство по участию в разработке
RELEASE_NOTES.md — История версий и функции

Тестирование

# Run tests
pytest

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

186 тестов, охватывающих CRUD графа знаний, поиск FTS5, управление ограничениями, отслеживание ошибок, автозаполнение, получение отзывов PR, цепочки решений, связь результатов, обучение траекториям, уровень прогнозирования, состояние памяти, обнаружение противоречий, указатели на транскрипты, идентификацию проекта и принудительное применение PreToolUse. Подробности см. в tests/.

Конфигурация

Переменные окружения

# 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

Примечание: Создайте файл .env в корне вашего проекта (см. .env.example) — он автоматически игнорируется git.

Настройка хуков

Отредактируйте .claude/settings.json, чтобы настроить, какие инструменты запускают хуки модели мира:

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

Поддержка языков

В настоящее время поддерживаются:

TypeScript / JavaScript
Python

Скоро появятся:

Go, Rust, Java, C++

Расширяемая архитектура: Легко добавить новые парсеры языков (см. CONTRIBUTING.md)

Конфиденциальность и безопасность

Локально-ориентированность: Все данные остаются на вашей машине
Без телеметрии: Нулевое отслеживание или передача внешних данных
Опциональный LLM: Работает без API-ключа (в качестве резервного варианта используются регулярные выражения)
Зашифрованное хранилище: Базы данных SQLite являются локальными файлами (шифруйте свой диск для безопасности)

Использование API-ключа (только если вы предоставите ANTHROPIC_API_KEY):

Извлечение сущностей из изменений кода
Вывод ограничений из исправлений
Никогда не отправляет: учетные данные, секреты, PII

Рекомендации по безопасности:

Никогда не коммитьте файлы .env
Используйте .env.example в качестве шаблона
Храните API-ключи только в переменных окружения или файлах .env
.gitignore автоматически исключает конфиденциальные файлы

Дорожная карта

v0.2.x

[x] Автозаполнение: граф знаний заполняется из существующей кодовой базы при настройке
[x] Интеллект отзывов PR: получение комментариев к обзорам GitHub в качестве ограничений
[x] Отслеживание связей: граф импорта и зависимостей между сущностями
[x] Поддержка нескольких языков: Python, TypeScript/JavaScript, Solidity, Go, Rust
[x] Команда CLI для запросов к графу знаний
[x] 40 тестов, 8 MCP-инструментов

v0.3.0

[x] Сопоставление на уровне модулей: запрос по имени модуля находит файл и его содержимое
[x] Инкрементальное повторное заполнение: повторная обработка только файлов, измененных с момента последнего заполнения
[x] Нечеткое сопоставление сущностей: приблизительный поиск имен для опечаток и сокращений
[x] Кэширование запросов: кэш в памяти с TTL для повторных запросов
[x] Поддержка Java: полное покрытие нескольких языков
[x] Проверка конвейера MCP-сервера на реальных проектах

v0.4.0

[x] Связь результатов: сбои тестов связаны с изменениями кода с помощью фактов
[x] Обучение траекториям: шаблоны совместного редактирования отслеживаются между сессиями
[x] Фиксация цепочки решений: структурированный журнал предложений агента и исправлений человека
[x] Поиск сущностей между проектами с реестром проектов
[x] 5 новых MCP-инструментов (всего 13), 104 теста

v0.5.0

[x] Прогнозирование регрессии, симуляция "что, если", прогнозирование сбоев тестов
[x] Перенос знаний между проектами, состояние памяти, TTL/затухание фактов
[x] Пакет get_context_for_action перед редактированием, отслеживание нарушений ограничений, find_contradictions
[x] 20 MCP-инструментов, 151 тест

v0.6.0 (Текущая) — Принудительное применение, происхождение, идентификация

[x] Хук принудительного применения ограничений PreToolUse: отклонение жестких нарушений на границе редактирования
[x] Индексированные указатели транскриптов: восстановление любого факта до исходного разговора
[x] Развязка идентификации проекта: стабильный UUID при переименовании каталогов
[x] Дедупликация по хэшу содержимого для фактов и ограничений
[x] Автогенерация CLAUDE.md из графа знаний
[x] Подкласс BetaAbstractMemoryTool для интеграции с Anthropic SDK
[x] Упаковка расширения для рабочего стола (.mcpb) для Claude Desktop
[x] 22 MCP-инструмента, 13 подкоманд CLI, 186 тестов

v0.7.0 (Следующая)

[ ] Извлечение на основе AST через tree-sitter
[ ] Планировщик фонового затухания фактов (по выбору)
[ ] Противоречия с весовыми коэффициентами достоверности с авторазрешением
[ ] Федерация ограничений в масштабах организации

Участие в разработке

Приветствуется участие в разработке. См. CONTRIBUTING.md для:

Настройки разработки
Стандартов кодирования
Добавления поддержки языков
Написания тестов
Отправки PR

Области, где нужна помощь:

Парсеры языков (Go, Rust, Java, C++)
Оптимизация производительности
Улучшение документации
Отзывы о тестировании в реальных условиях

Статистика

Размер проекта:

~4 800 строк кода
13 модулей Python
3 реализации хуков TypeScript

Эффективность хранения:

Пустая база данных: ~155 КБ
На сущность: ~500 байт
На факт: ~800 байт

Лицензия

Лицензия MIT — Бесплатно для коммерческого и личного использования

Поддержка

Проблемы: GitHub Issues
Обсуждения: GitHub Discussions