TrustFlow MCP-Datenagent

Er wandelt natürliche Sprachfragen in SQL-, Vektor-Such- und Wissensgraph-Ausführungspläne um. Der interne PolicyGraph validiert und korrigiert sie vor der Ausführung und liefert anschließend Begründungen und Audit-Protokolle zurück – als On-Premise-MCP-Datenagent.

Die aktuelle Version 0.3.0 ist ein Wettbewerbs-Einreichungskandidat, den das Team corevalue mit den offiziellen Company-X-Daten der Liwon Ace-Sonderaufgabe validiert hat. Der für die externe Veröffentlichung bestimmte Projektcode steht unter Apache-2.0; der offizielle Datensatz wird ausschließlich für die Wettbewerbsteilnahme verwendet und ist daher nicht im Repository enthalten.

Kernablauf

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

Das Unterscheidungsmerkmal des PolicyGraph besteht darin, dass „von der LLM erstellte Pläne nicht direkt ausgeführt werden“.

• ALLOW: Führt Pläne aus, die die Richtlinien erfüllen.

• REPAIR: Korrigiert SQL-LIMIT, Vektor-topK, Graph-Explorationstiefe usw. in den zulässigen Bereich und führt sie dann aus.

• APPROVAL_REQUIRED: Eingeschränkte Felder wie Gehalt oder Kontaktdaten werden erst nach Genehmigung ausgeführt.

• DENY: Schreib-SQL, Mehrfachanweisungen, nicht registrierte Tabellen/Beziehungen usw. werden nicht ausgeführt.

Related MCP server: TalkDB

Aktueller Implementierungsumfang

1. Schnellstart: Vollständig offline Baseline

Voraussetzung ist Node.js 24 oder höher und npm.

Offizielle Daten abrufen

Installieren Sie die Abhängigkeiten unverändert mit der Sperrdatei, erzeugen Sie lokale Geheimwerte und laden Sie dann die offiziellen Daten herunter.

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

Das Skript lädt ausschließlich das offizielle Liwon-Ace-ZIP herunter, prüft SHA-256 und entpackt es in data/companyx.

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

Bei bereits erfolgter Installation werden die Originale nicht überschrieben; es werden nur Prüfsumme und Pflichtdateien überprüft.

Installation und Validierung

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

Der Offline-Modus lädt den offiziellen SQL-Seed in ein In-Memory-SQLite und verwendet für die Dokumentsuche eine deterministische lokale Vektor-Baseline ohne Abhängigkeiten. Es ist ein Entwicklungsmodus, um Richtlinien, die 3 Tools, Begründung und Audit ohne Internet, Ollama oder Docker zu reproduzieren.

Die Evaluierungsergebnisse werden unter artifacts/evaluation erzeugt.

2. Realer PostgreSQL-Pfad

Führen Sie Folgendes aus, während Docker Desktop läuft.

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

Compose führt automatisch Folgendes aus:

• Start von PostgreSQL 16 + pgvector

• Erzeugung der offiziellen 8 relationalen Tabellen und von document_chunks

• Laden der offiziellen Seed-Daten

• Erzeugung der Read-only-Rolle policygraph_reader. Die DB-Berechtigungen werden für die 8 Geschäftstabellen und die interne document_chunks vergeben; NL2SQL fragt jedoch nur die 8 Geschäftstabellen ab, und document_chunks wird ausschließlich vom Vektorsuchadapter verwendet

• Erzeugung eines eindeutigen Index für Dokument-Chunks und eines HNSW-Vektorindex

Compose bindet nur an die Loopback-Schnittstelle des Hosts und verwendet die in .env erzeugten, unterschiedlichen zufälligen Admin- und Read-only-Passwörter. Der Smoke-Test verbindet sich mit policygraph_reader. Wenn Sie eine Datenbank aus einer separaten Umgebung verwenden, geben Sie DATABASE_URL explizit an.

3. Ollama + pgvector-Dokumentsuche und optionale lokale LLM

Dieser Schritt erfordert den Download eines Embedding-Modells und einen lokalen Ollama-Server.

ollama pull nomic-embed-text
ollama serve

Chunken und embedden Sie in einem anderen PowerShell-Fenster die Dokumente mit den Admin-Verbindungseinstellungen aus der von npm run setup:local erzeugten .env. Verbindungszeichenfolgen mit echten Passwörtern werden weder in Dokumenten noch im Repository festgehalten.

npm run ingest

Der operative MCP-Runtime startet ebenfalls mit der Read-only-Verbindung aus derselben .env.

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

Um Ausdrücke außerhalb der offiziellen Beispiele von der lokalen LLM als Planentwurf erstellen zu lassen und die begrenzte Antwort-Begründungssynthese zu verwenden, bereiten Sie Gemma 4 E2B separat vor und aktivieren dann den optionalen Modus.

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

Auch von der LLM erstellte Pläne müssen dieselbe PlanGate durchlaufen. Jeder Claim darf nur einen einzigen atomaren Begründungsdatensatz zitieren. Werden Bezeichner, exakte Zahlenwerte oder Einheiten kombiniert, die in dieser Begründung nicht enthalten sind, oder Sätze erzeugt, die nicht im Dokumentauszug stehen, werden sie durch den deterministischen Begründungsformatierer ersetzt. Für die lokale Validierung wurden gemma4:e2b 5.1B Q4_K_M und nomic-embed-text 137M F16 verwendet.

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

Auf der Validierungsmaschine (32 GB RAM, Intel Core Ultra 5 225H, CPU-Inferenz) dauerte die Planerstellung für 3 neue Ausdrücke etwa 58,8 s, 45,0 s bzw. 33,6 s. Dies ist kein Qualitätswert, sondern eine Einzelausführungsbeobachtung auf dieser Hardware. Nach der finalen Sicherheitshärtung bestand in der neuen E2E die Product-C1-Antwort des Modells die strenge Claim-Validierung auf Basis von DOC-011, und das vom Modell erstellte Viewer-Gehalts-SQL wurde vor der Ausführung durch POL-SQL-005/004 blockiert. Modellausgaben, die die Claim-Validierung nicht bestehen, werden sicher durch deterministische Antworten ersetzt.

Verwalten Sie echte Passwörter über die .env-Datei oder einen Geheimnisspeicher und committen Sie sie nicht in das Repository. Compose-Images fixieren für die Reproduzierbarkeit die pgvector-Version zusammen mit dem Image-Digest.

4. Web-Demo

npm run dev:web

Wenn Sie im Browser http://127.0.0.1:4173 öffnen, sehen Sie Folgendes auf einem Bildschirm:

• 30 offizielle SQL-, Vector- und Graph-Fragen

• Typed QueryPlan

• ALLOW / REPAIR / APPROVAL_REQUIRED / DENY-Entscheidung

• Übereinstimmende Richtlinie, Finding, Repair

• Validierte Antworten und Evidence Ledger

• Schreibangriffs-, Sensitivfeld- und Suchbudget-Stressszenarien

Die Webrolle wird serverseitig über POLICYGRAPH_ACTOR_ROLE festgelegt; Rollenwerte im Anforderungstext werden ignoriert. Die Web-API wendet Loopback-Host, Same-Origin, JSON, 64-KiB-Body, 4.096-Byte-Fragen, Anforderungsrate und Begrenzungen für gleichzeitige Ausführungen an. Dieselben Fragenbegrenzungen gelten für MCP und den Planer. Vor der externen Veröffentlichung sind eine separate Authentifizierung und ein TLS-Reverse-Proxy erforderlich.

5. MCP-Tools

Ein Beispiel für die MCP-Host-Konfiguration:

{
  "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"
      }
    }
  }
}

Die vom Server bereitgestellte Rolle wird in der Host-Umgebung festgelegt und kann nicht über Modelleingaben geändert werden. Das optionale approvalReceipt von nl2sql ist ein HMAC-signierter Wert, der nur von Administratoren ausgestellt werden kann; er ist an Benutzer, Rolle und den normalisierten Plan gebunden und kann innerhalb von 5 Minuten nur einmal verwendet werden.

6. Evaluierungsergebnisse

Aktuelle lokale Reproduktionsergebnisse:

• Offizielle Beispielfragen: 30

• Automatische Tests: 37/37

• Tool-Routing: 30/30

• Ausführungserfolg: 30/30

• Antworten mit Begründungsverknüpfung: 30/30

• Richtlinienentscheidung für interne Angriffs- und Grenzfälle: 8/8

• Offline-P95: 25,77 ms

• Realer PostgreSQL-P95: 173,12 ms

• pgvector, offizielle 10 Dokumentfragen: Hit@1 100 %, Mean Recall@5 97,14 %, MRR@10 1,0

• pgvector warm P95: 215,02 ms

• Gemma 4, 30 repräsentative Paraphrasen: Planschema 100 %, rohe Tools 93,3 %, nach Richtliniennormalisierung Tools, Ausführung und semantische Korrektheit 100 %

• Gemma 4, adversariale Regression: 8/8

Detaillierte Ergebnisse finden Sie in der Evaluierungsübersicht, der PostgreSQL-Übersicht und der pgvector-Übersicht.

Offizielle Fragen mit sensiblen Feldern werden ausgeführt, nachdem für die Evaluierung eine namentlich protokollierte Genehmigung erteilt wurde. „Antworten mit Begründungsverknüpfung“ in der Tabelle ist ein Basisindikator, der prüft, ob ein Claim tatsächlich auf eine evidenceId verweist; der Modellantwortpfad fügt hier zusätzlich atomare Einzelbegründung, exakte Zahlenwerte und Einheiten sowie Übereinstimmung mit Dokumentauszügen hinzu. Die semantische Korrektheitsrate ist das Ergebnis einer separaten, öffentlich zugänglichen Fixture-Entscheidung. Diese Werte sind eine Entwicklungsbaseline für die veröffentlichten offiziellen Beispielfragen und internen Angriffsszenarien; sie bedeuten keine Leistung auf den nicht öffentlichen Wettbewerbstests oder allgemeine Genauigkeit bei natürlicher Sprache.

7. Sicherheitsgrenzen

Der PolicyGraph verlässt sich nicht nur auf eine einzige Schicht von String-Filtern.

1. Nur strukturierte QueryPlans werden an die Ausführungskomponente übergeben.

2. Der PostgreSQL-AST-Prüfer prüft einzelne Leseabfragen, die 8 Geschäftstabellen und zulässige Spalten, nicht-rekursive CTEs, Funktionen, Sperren und Whole-Row-Projektionen und blockiert Tabellenspalten-Aliaslisten, JOIN ... USING, Cross Joins und übermäßige Beziehungsverknüpfungen.

3. Die PlanGate prüft Fragen auf 4.096 Byte, sensible Felder, Ergebnishaushalt und Graphbeziehungen; SQL-Ergebnisse werden über einen externen Wrapper auf maximal 100 Zeilen begrenzt.

4. Das PostgreSQL-Ausführungskonto hat SELECT nur auf den 8 Geschäftstabellen und der internen document_chunks; NL2SQL kann nicht auf die interne Dokumenttabelle zugreifen. Für die Ausführung werden READ ONLY-Transaktionen und ein Statement-Timeout von 5 Sekunden verwendet.

5. Die Genehmigung ist ein kurzlebiges HMAC-Zertifikat, das an Benutzer, Serverrolle und den exakten Plan gebunden ist und nicht wiederverwendet werden kann.

6. Antwort-Claims zitieren nur eine einzige atomare Begründung und dürfen nur Bezeichner, exakte Zahlenwerte und Einheiten sowie Dokumentauszüge verwenden, die diese Begründung tatsächlich stützt.

7. Alle Laufzeiten erfordern eine HMAC-signierte Hash-Kette und einen separat signierten Checkpoint. Die ursprüngliche Frage wird nicht gespeichert; es wird nur der domänengetrennte SHA-256-Digest protokolliert. Wenn der Checkpoint nicht exakt mit dem aktuellen Ledger-Head übereinstimmt, schlägt die Validierung fehl.

8. Daten- und Einreichungs-ZIPs werden vor dem Entpacken auf Pfade, doppelte Einträge, symbolische Links sowie Anzahl, Größe und Komprimierungsverhältnis der Einträge geprüft.

9. Fehlerantworten von MCP und Web liefern nur eine Korrelations-ID und legen keine internen Verbindungsinformationen offen.

8. Repository-Struktur

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. Bekannte Einschränkungen und nächste Schritte

1. Die offiziellen 30 Fragen verwenden für die Reproduzierbarkeit deterministische Pläne; freie Ausdrücke hängen von der Qualität der strukturierten Ausgabe des Gemma-4-Fallbacks ab.

2. CPU-basiertes Gemma 4 benötigt mehrere zehn Sekunden; für den Echtzeitbetrieb sind daher GPU, ein kleineres Modell oder ein Plancache erforderlich.

3. Das Web ist eine Loopback-Demogrenze und kein Benutzerauthentifizierungssystem. Für die externe Veröffentlichung sind OIDC/RBAC und ein TLS-Reverse-Proxy erforderlich.

4. Ein Angreifer, der sowohl das Audit-Ledger als auch den Signatur-Checkpoint löschen und zusätzlich den Signaturschlüssel erbeuten kann, liegt außerhalb der lokalen Dateigrenze. Im Betrieb müssen Checkpoints in einem unabhängigen Speicher oder WORM aufbewahrt werden.

5. Der Graph ist eine In-Memory-Implementierung im Maßstab von 133 Knoten. Für großflächige Anwendungen sind ein persistenter Graphspeicher und Lasttests erforderlich.

10. Einreichungsmaterialien

Der lokale Einreichungskandidaten-Bericht als DOCX und PDF, die Einreicher-Checkliste und die Integritätsliste befinden sich unter artifacts/submission/ und sind aus dem öffentlichen Repository ausgeschlossen, um die Vermischung mit personenbezogenen Daten und Einreichungs-Arbeitsergebnissen zu verhindern. Das öffentliche Repository enthält reproduzierbaren Quellcode, rohe Evaluierungsdaten, eine CycloneDX-SBOM sowie Hinweise zur Nutzung von Modellen, Daten und KI.

Die Demonstration folgt docs/DEMO_SCRIPT.md; der Umfang der Modell-, Daten- und KI-Nutzung folgt docs/MODEL_CARD.md, docs/DATA_LICENSE.md und docs/AI_USAGE.md.

Lizenz

Der Projektcode steht unter der Apache License 2.0. Der offizielle Company-X-Datensatz wird ausschließlich im von Liwon Ace festgelegten Umfang der Wettbewerbsteilnahme verwendet und ist nicht in diesem Repository enthalten.