Агент данных TrustFlow MCP

Это локальный MCP-агент данных, который преобразует вопросы на естественном языке в планы выполнения SQL, векторного поиска и графа знаний, а внутренний PolicyGraph проверяет и корректирует их перед выполнением, после чего возвращает обоснование и журнал аудита.

Текущая версия 0.3.0 — кандидат на подачу от команды corevalue, проверенный на официальных данных Company-X для задания, назначенного RiwnAce. Код проекта, открытый для внешнего использования, распространяется по лицензии Apache-2.0; официальный набор данных используется только в целях участия в соревновании и не включается в репозиторий.

Основной поток

flowchart LR
    Q[자연어 질문] --> P[구조화 QueryPlan]
    P --> G{PolicyGraph PlanGate}
    G -->|ALLOW| X[실행]
    G -->|REPAIR| R[안전한 계획으로 보정]
    R --> X
    G -->|APPROVAL_REQUIRED| A[승인 대기]
    G -->|DENY| D[실행 차단]
    X --> S[NL2SQL]
    X --> V[Vector Search]
    X --> K[Knowledge Graph]
    S --> E[근거 연결 답변]
    V --> E
    K --> E
    E --> L[해시 체인 감사 원장]
    A --> L
    D --> L

Отличительная особенность PolicyGraph заключается в том, что «план, созданный LLM, не выполняется напрямую».

• ALLOW: выполняет план, удовлетворяющий политике.

• REPAIR: корректирует SQL LIMIT, векторный topK, глубину обхода графа и т. п. до допустимых значений, после чего выполняет.

• APPROVAL_REQUIRED: ограниченные поля, такие как зарплата и контактные данные, не выполняются до получения одобрения.

• DENY: не выполняет записывающие SQL, многосоставные операторы, незарегистрированные таблицы и связи.

Related MCP server: TalkDB

Текущий объём реализации

1. Быстрое начало: полностью автономный базовый уровень

Требования к среде: Node.js 24 или новее и npm.

Получение официальных данных

Установите зависимости точно по lock-файлу, создайте локальные секреты и получите официальные данные.

npm ci
npm run setup:local
npm run fetch:data

Скрипт загружает только официальный ZIP от RiwnAce, проверяет SHA-256 и распаковывает его в data/companyx.

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

Если данные уже установлены, оригинал не перезаписывается — проверяются только контрольная сумма и обязательные файлы.

Установка и проверка

npm run typecheck
npm test
npm run demo
npm run evaluate
npm run compliance

Автономный режим загружает официальный SQL-сид в SQLite в памяти, а для поиска по документам использует детерминированный локальный векторный базовый уровень без зависимостей. Это режим разработки для воспроизведения политики, трёх инструментов, обоснования и аудита без интернета, Ollama и Docker.

Результаты оценки создаются в artifacts/evaluation.

2. Путь с реальным PostgreSQL

При запущенном Docker Desktop выполните следующее.

npm run setup:local
docker compose up -d --wait
docker compose ps
npm run smoke:postgres

Compose автоматически выполняет следующее:

• Запуск PostgreSQL 16 + pgvector

• Создание официальных 8 реляционных таблиц и document_chunks

• Загрузка официальных сид-данных

• Создание роли только для чтения policygraph_reader. Права БД выдаются на 8 рабочих таблиц и внутреннюю document_chunks, но NL2SQL обращается только к 8 рабочим таблицам, а document_chunks используется исключительно адаптером векторного поиска

• Создание уникального индекса чанков документов и векторного индекса HNSW

Compose привязывается только к loopback хоста, а в .env создаются различные случайные пароли администратора и роли только для чтения. Смоук-тест подключается под policygraph_reader. При использовании базы данных из другого окружения укажите DATABASE_URL.

3. Ollama + pgvector поиск по документам и опциональный локальный LLM

Этот шаг требует загрузки модели эмбеддингов и локального сервера Ollama.

ollama pull nomic-embed-text
ollama serve

В другом окне PowerShell используйте настройки подключения администратора из .env, созданного командой npm run setup:local, чтобы разбить документы на чанки и создать эмбеддинги. Строки подключения с реальными паролями не записываются в документацию и репозиторий.

npm run ingest

Операционный MCP-рантайм также запускается с подключением только для чтения из того же .env.

$env:POLICYGRAPH_RUNTIME = "postgres"
$env:VECTOR_MODE = "pgvector"
npm run dev:mcp

Чтобы локальный LLM создавал черновики планов для выражений за пределами официальных примеров и использовал синтез ответов с ограниченным обоснованием, подготовьте Gemma 4 E2B отдельно и включите опциональный режим.

ollama pull gemma4:e2b
$env:POLICYGRAPH_LLM_MODE = "assist"
$env:OLLAMA_CHAT_MODEL = "gemma4:e2b"
npm run dev:mcp

Планы, созданные LLM, также должны проходить через тот же PlanGate. Каждое утверждение может ссылаться только на одну атомарную запись обоснования; комбинирование идентификаторов, точных чисел и единиц, отсутствующих в этом обосновании, или создание предложений, которых нет в выдержке из документа, заменяется детерминированным форматтером обоснования. Для локальной проверки использовались gemma4:e2b 5.1B Q4_K_M и nomic-embed-text 137M F16.

npm run smoke:ollama
npm run smoke:ollama:e2e
npm run evaluate:pgvector

На проверочной машине (32 ГБ ОЗУ, Intel Core Ultra 5 225H, вывод на CPU) генерация планов для трёх новых выражений заняла примерно 58,8 с, 45,0 с и 33,6 с соответственно. Это не оценка качества, а единичные наблюдения на данном оборудовании. После финального усиления безопасности в новом E2E ответ модели Product-C1 прошёл строгую проверку утверждений на основе DOC-011, а созданный моделью SQL с зарплатой зрителя был заблокирован до выполнения политикой POL-SQL-005/004. Выводы модели, не прошедшие проверку утверждений, безопасно заменяются детерминированным ответом.

Реальные пароли храните в файле .env или в хранилище секретов и не коммитьте их в репозиторий. Образы Compose фиксируют версию pgvector и digest образа вместе для воспроизводимости.

4. Веб-демо

npm run dev:web

Открыв в браузере http://127.0.0.1:4173, вы увидите на одном экране следующее:

• 30 официальных вопросов SQL·Vector·Graph

• Типизированный QueryPlan

• Определение ALLOW / REPAIR / APPROVAL_REQUIRED / DENY

• Совпадающие политики, findings, repair

• Проверенные ответы и реестр доказательств

• Сценарии стресса: атаки записи, чувствительные поля, бюджет поиска

Веб-роль фиксируется на сервере через POLICYGRAPH_ACTOR_ROLE, а значение роли в теле запроса игнорируется. Веб-API применяет ограничения: loopback Host, same-origin, JSON, тело 64 КиБ, вопрос 4096 байт, частота запросов и параллельное выполнение. Те же ограничения на вопросы применяются к MCP и планировщику. Перед внешней публикацией требуется отдельная аутентификация и TLS-обратный прокси.

5. Инструменты MCP

Пример настройки MCP-хоста:

{
  "mcpServers": {
    "trustflow-companyx": {
      "command": "node",
      "args": ["C:/absolute/path/to/trustflow-mcp-data-agent/src/mcp/server.ts"],
      "env": {
        "COMPANYX_DATA_DIR": "C:/absolute/path/to/trustflow-mcp-data-agent/data/companyx",
        "POLICYGRAPH_RUNTIME": "offline",
        "POLICYGRAPH_ACTOR_ROLE": "analyst"
      }
    }
  }
}

Роль, которую предоставляет сервер, определяется в среде хоста и не может быть изменена через входные данные модели. Опциональный approvalReceipt в nl2sql — это HMAC-подпись, которую может выдать только администратор; она привязана к пользователю, роли и нормализованному плану и может быть использована только один раз в течение 5 минут.

6. Результаты оценки

Текущие результаты локального воспроизведения:

• Официальные примеры вопросов: 30

• Автоматические тесты: 37/37

• Маршрутизация инструментов: 30/30

• Успешность выполнения: 30/30

• Ответы со связанным обоснованием: 30/30

• Определение политики для внутренних атак и граничных случаев: 8/8

• Автономный P95: 25,77 мс

• Реальный PostgreSQL P95: 173,12 мс

• 10 официальных вопросов по документам pgvector: Hit@1 100%, Mean Recall@5 97,14%, MRR@10 1,0

• pgvector warm P95: 215,02 мс

• 30 репрезентативных перефразировок Gemma 4: схема плана 100%, сырые инструменты 93,3%, после нормализации политики инструменты·выполнение·семантическая правильность 100%

• Адверсариальная регрессия Gemma 4: 8/8

Подробные результаты см. в Сводке оценки, Сводке PostgreSQL и Сводке pgvector.

Официальные вопросы, содержащие чувствительные поля, выполняются после предоставления одобрения с записанным именем для целей оценки. «Ответы со связанным обоснованием» в таблице — это базовый показатель, проверяющий, ссылается ли утверждение на фактический evidenceId; путь ответов модели дополнительно добавляет проверки атомарного единичного обоснования, точных чисел и единиц и соответствия выдержкам из документов. Семантическая точность — это результат определения по отдельным публичным фикстурам. Эти цифры являются базовым уровнем разработки для опубликованных официальных примеров вопросов и внутренних сценариев атак и не означают производительность на закрытых тестах соревнования или общую точность обработки естественного языка.

7. Границы безопасности

PolicyGraph не полагается только на один слой строковых фильтров.

1. Исполнителю передаётся только структурированный QueryPlan.

2. Проверщик AST PostgreSQL проверяет одиночный запрос на чтение, 8 рабочих таблиц и разрешённые столбцы, нерекурсивные CTE, функции, блокировки и whole-row projection, а также блокирует списки псевдонимов столбцов таблиц, JOIN ... USING, cross join и чрезмерные объединения связей.

3. PlanGate проверяет вопрос на 4096 байт, чувствительные поля, бюджет результатов и связи графа, а результаты SQL принудительно ограничиваются максимум 100 строками через внешнюю обёртку.

4. Учётная запись выполнения PostgreSQL имеет SELECT только на 8 рабочих таблицах и внутренней document_chunks; NL2SQL не может обращаться к внутренней таблице документов. При выполнении используются транзакция READ ONLY и таймаут оператора 5 секунд.

5. Одобрение — это краткосрочный HMAC-квиток, привязанный к пользователю, роли сервера и точному плану; его нельзя использовать повторно.

6. Утверждение ответа ссылается только на одно атомарное обоснование и может использовать только идентификаторы, точные числа и единицы, а также выдержки из документов, которые это обоснование действительно поддерживает.

7. Все рантаймы требуют HMAC-подписанную хеш-цепочку и отдельную контрольную точку подписи. Исходный вопрос не сохраняется — записывается только доменно-раздельный SHA-256 digest; если контрольная точка не совпадает в точности с текущей головой реестра, проверка завершается неудачей.

8. Данные и ZIP для подачи проверяются на пути, дублирующиеся записи, символические ссылки, количество и размер записей и степень сжатия до распаковки.

9. Ответы об ошибках MCP и веб-интерфейса содержат только корреляционный ID и не раскрывают внутреннюю информацию о подключении.

8. Структура репозитория

src/
  adapters/        PostgreSQL, pgvector, Ollama 연결
  core/            QueryPlan, 정책 판정, 근거 계약
  evidence/        답변 구성과 해시 체인 감사 원장
  mcp/             air MCP 서버와 3개 공식 도구
  planner/         공식 질문용 결정적 계획기
  policy/          PlanGate와 정책 카탈로그
  tools/           SQL·벡터·그래프 실행기
  web/             로컬 evidence console
db/init/           읽기 전용 역할과 벡터 인덱스
policy/            RDF/SHACL 형태 정책 그래프
scripts/           데이터 설치, 데모, 평가, 적재, 스모크 검사
test/              단위·통합·공식 30문항 테스트
docs/              아키텍처와 개발 명세

9. Известные ограничения и следующие шаги

1. Официальные 30 вопросов используют детерминированные планы для воспроизводимости; свободные выражения зависят от качества структурированного вывода fallback Gemma 4.

2. CPU-версия Gemma 4 занимает десятки секунд, поэтому для реального времени требуется GPU, модель меньшего размера или кэш планов.

3. Веб-интерфейс — это демонстрационная граница на loopback, а не система аутентификации пользователей. Для внешней публикации требуются OIDC/RBAC и TLS-обратный прокси.

4. Атакующий, способный стереть и реестр аудита, и контрольную точку подписи, а также похитить ключ подписи, находится за пределами локальных файловых границ. В эксплуатации контрольную точку следует хранить в независимом хранилище или WORM.

5. Граф — это реализация в памяти масштаба 133 узлов. Для крупномасштабного применения требуются персистентное хранилище графа и нагрузочное тестирование.

10. Материалы для подачи

Локальный отчёт-кандидат на подачу в форматах DOCX и PDF, чек-лист подающего и список целостности находятся в artifacts/submission/ и исключены из публичного репозитория, чтобы предотвратить смешивание личных данных и рабочих материалов подачи. Публичный репозиторий включает воспроизводимый исходный код, исходные данные оценки, CycloneDX SBOM и уведомления об использовании моделей, данных и ИИ.

Демонстрация выполняется по docs/DEMO_SCRIPT.md, а область использования моделей, данных и ИИ — по docs/MODEL_CARD.md, docs/DATA_LICENSE.md и docs/AI_USAGE.md.

Лицензия

Код проекта распространяется по Apache License 2.0. Официальный набор данных Company-X используется только в пределах целей участия в соревновании, указанных RiwnAce, и не включается в этот репозиторий.