TrustFlow MCP データエージェント

自然言語の質問をSQL・ベクトル検索・ナレッジグラフの実行計画に変換し、内部のPolicyGraphが実行前に検証・補正した上で、根拠と監査記録まで返すオンプレミスMCPデータエージェントです。

現在のバージョン0.3.0は、corevalueチームがリウォンエース指定課題の公式Company-Xデータで検証した大会提出候補です。外部公開用のプロジェクトコードは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です。

公式データの取得

ロックファイルのまま依存関係をインストールし、ローカル秘密値を生成した上で公式データを取得します。

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

スクリプトはリウォンエース公式ZIPのみをダウンロードし、SHA-256を確認した上でdata/companyxに展開します。

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

すでにインストールされている場合は元のファイルを上書きせず、チェックサムと必須ファイルのみを確認します。

インストールと検証

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

オフラインモードは公式SQLシードをメモリSQLiteにロードし、ドキュメント検索は依存関係のない決定的ローカルベクトルベースラインを使用します。インターネット・Ollama・Dockerなしで、ポリシー、3種ツール、根拠、監査を再現するための開発モードです。

評価結果は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読み取り専用ロールの作成。DB権限は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ウィンドウで、npm run setup:localが生成した.envの管理者接続設定を使用してドキュメントをチャンキング・埋め込みします。実際のパスワードが含まれる接続文字列は、ドキュメントやリポジトリに記録しません。

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を通過する必要があります。各claimは1つの原子的根拠レコードのみを引用でき、その根拠にない識別子・正確な数値・単位を組み合わせたり、ドキュメント抜粋にない文を作成したりすると、決定的根拠フォーマッタに置き換えられます。ローカル検証には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

検証マシン(32GB RAM、Intel Core Ultra 5 225H、CPU推論)で、新しい表現3件の計画生成はそれぞれ約58.8秒、45.0秒、33.6秒でした。これは品質スコアではなく、当該ハードウェアでの単一実行の観測値です。最終セキュリティ強化後の新しいE2Eでは、モデルのProduct-C1回答がDOC-011ベースの厳格なclaim検証を通過し、モデルが作成したviewer給与SQLはPOL-SQL-005/004で実行前にブロックされました。claim検証に失敗するモデル出力は、決定的回答に安全に置き換えられます。

実際のパスワードは.envファイルまたはシークレットストアで管理し、リポジトリにコミットしないでください。Composeイメージは再現性のため、pgvectorバージョンとイメージdigestを一緒に固定します。

4. Webデモ

npm run dev:web

ブラウザで http://127.0.0.1:4173 を開くと、以下を1画面で確認できます。

• SQL・Vector・Graph公式質問30問

• Typed QueryPlan

• ALLOW / REPAIR / APPROVAL_REQUIRED / DENY判定

• 一致ポリシー、finding、repair

• 検証済み回答とevidence ledger

• 書き込み攻撃、機密フィールド、検索予算ストレスシナリオ

WebロールはPOLICYGRAPH_ACTOR_ROLEでサーバー側に固定され、リクエスト本文のロール値は無視されます。Web APIはloopback Host・same-origin・JSON・64 KiB本文・質問4,096バイト・リクエストレート・同時実行制限を適用します。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"
      }
    }
  }
}

サーバーが公開するロールはホスト環境で定められ、モデル入力で変更できません。nl2sqlの選択型approvalReceiptは管理者のみが発行できるHMAC署名値であり、ユーザー・ロール・正規化された計画に結合され、5分以内に一度だけ使用できます。

6. 評価結果

現在のローカル再現実行結果:

• 公式例の質問: 30問

• 自動テスト: 37/37

• ツールルーティング: 30/30

• 実行成功: 30/30

• 根拠接続回答: 30/30

• 内部攻撃・境界ケースポリシー判定: 8/8

• オフラインP95: 25.77ms

• 実PostgreSQL P95: 173.12ms

• pgvector公式ドキュメント10問: Hit@1 100%、Mean Recall@5 97.14%、MRR@10 1.0

• pgvector warm P95: 215.02ms

• Gemma 4代表言い換え30件: 計画スキーマ100%、rawツール93.3%、ポリシー正規化後のツール・実行・意味正解100%

• Gemma 4敵対的回帰: 8/8

詳細結果は評価サマリー、PostgreSQLサマリー、pgvectorサマリーで確認できます。

機密フィールドが含まれる公式問題は、評価用に名前が記録された承認を提供した上で実行します。表の「根拠接続回答」はclaimが実際のevidenceIdを参照するかを検査する基本指標であり、モデル回答パスはこれに原子的単一根拠・正確な数値と単位・ドキュメント抜粋一致検査を追加します。意味的正解率は別途公開fixtureの判定結果です。この数値は公開された公式例の質問と内部攻撃シナリオに対する開発ベースラインであり、大会非公開テストの性能や汎用自然言語の正確性を意味するものではありません。

7. セキュリティ境界

PolicyGraphは一層の文字列フィルタのみに依存しません。

1. 構造化されたQueryPlanのみを実行器に渡します。

2. PostgreSQL AST検査器が単一読み取りクエリ、8個の業務テーブル・許可列、非再帰CTE、関数・ロック・whole-row projectionを検査し、テーブル列エイリアスリスト、JOIN ... USING、cross joinと過度なリレーション結合をブロックします。

3. PlanGateが質問4,096バイト、機密フィールド・結果予算・グラフリレーションを検査し、SQL結果は外部ラッパーで最大100行を強制します。

4. PostgreSQL実行アカウントは8個の業務テーブルと内部document_chunksにのみSELECTを持ち、NL2SQLは内部ドキュメントテーブルにアクセスできません。実行にはREAD ONLYトランザクションと5秒のstatement timeoutを併用します。

5. 承認はユーザー・サーバーロール・正確な計画に結合した短期HMACレシートであり、再利用できません。

6. 回答claimは原子的根拠1つのみを引用し、その根拠が実際に支持する識別子・正確な数値と単位・ドキュメント抜粋のみを使用できます。

7. すべてのランタイムはHMAC署名ハッシュチェーンと別途署名チェックポイントを要求します。原文質問は保存せず、ドメイン分離SHA-256 digestのみを記録し、チェックポイントが現在の台帳headと正確に一致しない場合は検証に失敗します。

8. データ・提出ZIPは解凍前にパス、重複エントリ、シンボリックリンク、エントリ数・サイズ・圧縮率を検査します。

9. MCPとWebの失敗応答は相関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問は再現性のため決定的計画を使用し、自由表現はGemma 4フォールバックの構造化出力品質に依存します。

2. CPUベースのGemma 4は数十秒かかるため、リアルタイム運用にはGPU・より小さいモデル・計画キャッシュのいずれかが必要です。

3. Webはloopbackデモ境界であり、ユーザー認証システムではありません。外部公開にはOIDC/RBACとTLSリバースプロキシが必要です。

4. 監査台帳と署名チェックポイントの両方を消去し、署名キーまで奪取できる攻撃者はローカルファイル境界の外です。運用ではチェックポイントを独立ストレージやWORMに保管する必要があります。

5. グラフは133ノード規模のメモリ実装です。大規模適用時には永続グラフストレージと負荷テストが必要です。

10. 提出資料

ローカル提出候補の結果報告書DOCX・PDF、提出者チェックリストと完全性リストはartifacts/submission/にあり、個人情報・提出作業物の混入を防ぐため公開リポジトリでは除外します。公開リポジトリには再現可能なソース、評価原子データ、CycloneDX SBOM、モデル・データ・AI利用告知を含めます。

デモはdocs/DEMO_SCRIPT.md、モデル・データ・AI使用範囲はdocs/MODEL_CARD.md、docs/DATA_LICENSE.md、docs/AI_USAGE.mdに従います。

ライセンス

プロジェクトコードはApache License 2.0です。公式Company-Xデータセットはリウォンエースが明示した大会参加目的の範囲でのみ使用し、このリポジトリには含めません。