@ypolosov/sdlc-state-rag

Единый MCP-сервер для бэкенда плагина ai-driven-sdlc-plugin. Объединяет 5 доменов в одной БД: alpha state machine (OMG Essence 1.2), RAG (PostgreSQL+pgvector), decisions, audit, sync.

Установка

npx -y @ypolosov/sdlc-state-rag

Cold-start через npx поднимет MCP-сервер. После первого вызова — кешировано локально.

Backend

| Уровень | Backend | Запуск | |---|---|---| | pet (truly-solo) | embedded @electric-sql/pglite v0.4+ | без DSN — БД в <target>/.sdlc-db/ | | mid (5–7 человек) | shared PostgreSQL+pgvector | DSN на shared instance | | enterprise | managed cloud (Supabase/Neon/RDS) | DSN на managed |

Connection-string из переменной окружения SDLC_STATE_RAG_DSN. Если не задан — используется встроенный pglite.

Регистрация в .mcp.json

{
  "mcpServers": {
    "sdlc-state-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ypolosov/sdlc-state-rag"],
      "env": {
        "SDLC_STATE_RAG_DSN": "${SDLC_STATE_RAG_DSN}"
      }
    }
  }
}

Контракт MCP tools

Alpha state machine (OMG Essence 1.2)

• state_get_alpha — текущее состояние альфы.
• state_advance_alpha — продвижение альфы (валидируется state chart).
• state_regress_alpha — откат альфы.
• state_list_transitions — журнал переходов.
• state_validate_consistency — проверка консистентности всех альф.
• state_describe_alpha — определение альфы из OMG Essence 1.2.
• state_get_state_chart — полный state chart альфы.

RAG (pgvector similarity search)

• rag_upsert_documents — индексация документов.
• rag_query_chunks — top-K similarity search.
• rag_purge_by_ttl — удаление устаревших чанков.
• rag_stats — статистика индекса.

Decisions journal

• decisions_record — запись альтернатив + выбора + обоснования.
• decisions_list_relevant — релевантные решения по фазе/альфе.

Audit log

• audit_emit — запись audit-события.
• audit_query — выборка событий.

Sync events

• sync_emit — запись sync-события (webhook/cron).
• sync_query — выборка событий.

Композитные (атомарные транзакции)

• state_advance_with_decision — продвижение альфы + запись решения в одной транзакции.
• state_regress_with_audit — откат альфы + audit-запись в одной транзакции.
• rag_upsert_with_sync_event — upsert + sync-event в одной транзакции.

Concurrent-safety

Все mutating операции через PostgreSQL транзакции. Альфы продвигаются с SELECT … FOR UPDATE на записи альфы. Изоляция: SERIALIZABLE для критических переходов, READ COMMITTED для read.

Миграции

Версионированные SQL-миграции в migrations/. CLI sdlc-state-rag-migrate применяет миграции идемпотентно.

npx -y @ypolosov/sdlc-state-rag-migrate up

Лицензия

MIT