TrustFlow MCP Data Agent

An on-premises MCP data agent that converts natural language questions into SQL, vector search, and knowledge graph execution plans, with an internal PolicyGraph that validates and repairs them before execution, then returns evidence and audit records.

Version 0.3.0 is currently a competition submission candidate validated by the corevalue team against the official Company-X data for the Liwon Ace designated task. The externally published project code is Apache-2.0, and the official dataset is used solely for competition participation, so it is not included in the repository.

Core Flow

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

The differentiator of PolicyGraph is that it "does not execute LLM-generated plans directly."

• ALLOW: Executes plans that satisfy policy.

• REPAIR: Repairs SQL LIMIT, vector topK, graph traversal depth, etc. to allowed ranges before execution.

• APPROVAL_REQUIRED: Restricted fields such as salary and contact information are not executed until approved.

• DENY: Write SQL, multi-statement queries, unregistered tables/relationships, etc. are not executed.

Related MCP server: TalkDB

Current Implementation Scope

1. Quick Start: Fully Offline Baseline

Requirements are Node.js 24 or later and npm.

Getting the Official Data

Install dependencies exactly as locked, generate local secrets, then fetch the official data.

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

The script downloads only the official Liwon Ace ZIP, verifies SHA-256, and extracts it to data/companyx.

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

If already installed, it does not overwrite the original and only verifies the checksum and required files.

Installation and Verification

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

Offline mode loads the official SQL seed into in-memory SQLite, and document search uses a dependency-free deterministic local vector baseline. It is a development mode for reproducing policy, the three tools, evidence, and audit without internet, Ollama, or Docker.

Evaluation results are generated in artifacts/evaluation.

2. Real PostgreSQL Path

With Docker Desktop running, execute the following.

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

Compose automatically performs the following:

• Starts PostgreSQL 16 + pgvector

• Creates the official 8 relational tables and document_chunks

• Loads the official seed data

• Creates the policygraph_reader read-only role. DB permissions are granted on the 8 business tables and the internal document_chunks, but NL2SQL only queries the 8 business tables, and document_chunks is used only by the vector search adapter

• Creates unique indexes on document chunks and HNSW vector indexes

Compose binds only to the host loopback and uses distinct random admin/read-only passwords generated in .env. The smoke test connects as policygraph_reader. When using a database from a separate environment, specify DATABASE_URL explicitly.

3. Ollama + pgvector Document Search and Optional Local LLM

This step requires downloading an embedding model and a local Ollama server.

ollama pull nomic-embed-text
ollama serve

In another PowerShell window, use the admin connection settings from .env generated by npm run setup:local to chunk and embed documents. Connection strings containing real passwords are not written to documents or the repository.

npm run ingest

The production MCP runtime also starts with the read-only connection from the same .env.

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

To have the local LLM create plan drafts for expressions outside the official examples and use evidence-limited answer synthesis, prepare Gemma 4 E2B separately and enable the optional mode.

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

LLM-generated plans must also pass the same PlanGate. Each claim may cite only one atomic evidence record, and combining identifiers, exact figures, or units not present in that evidence, or fabricating sentences not in the document excerpt, results in replacement with the deterministic evidence formatter. Local validation used gemma4:e2b 5.1B Q4_K_M and nomic-embed-text 137M F16.

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

On the validation machine (32GB RAM, Intel Core Ultra 5 225H, CPU inference), plan generation for 3 new expressions took approximately 58.8s, 45.0s, and 33.6s respectively. These are not quality scores but single-run observations on that hardware. After final security hardening, in the new E2E the model's Product-C1 answer passed strict claim validation based on DOC-011, and the model-generated viewer salary SQL was blocked before execution by POL-SQL-005/004. Model outputs that fail claim validation are safely replaced with deterministic answers.

Manage real passwords via the .env file or a secret store, and never commit them to the repository. Compose images pin both the pgvector version and image digest for reproducibility.

4. Web Demo

npm run dev:web

Opening http://127.0.0.1:4173 in a browser shows the following on a single screen:

• 30 official SQL, Vector, and Graph questions

• Typed QueryPlan

• ALLOW / REPAIR / APPROVAL_REQUIRED / DENY determinations

• Matching policy, findings, repairs

• Verified answers and evidence ledger

• Write attack, sensitive field, and search budget stress scenarios

The web role is fixed server-side via POLICYGRAPH_ACTOR_ROLE, and role values in the request body are ignored. The web API enforces loopback Host, same-origin, JSON, 64 KiB body, 4,096-byte questions, request rate, and concurrency limits. The same question limits apply to MCP and the planner. External publication requires a separate authentication and TLS reverse proxy.

5. MCP Tools

An example MCP host configuration is as follows.

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

The role exposed by the server is determined by the host environment and cannot be changed via model input. The optional approvalReceipt in nl2sql is an HMAC-signed value that only admins can issue, bound to the user, role, and normalized plan, and usable only once within 5 minutes.

6. Evaluation Results

Current local reproduction run results:

• Official example questions: 30

• Automated tests: 37/37

• Tool routing: 30/30

• Execution success: 30/30

• Evidence-linked answers: 30/30

• Internal attack/boundary case policy determinations: 8/8

• Offline P95: 25.77ms

• Real PostgreSQL P95: 173.12ms

• pgvector official document 10 questions: Hit@1 100%, Mean Recall@5 97.14%, MRR@10 1.0

• pgvector warm P95: 215.02ms

• Gemma 4 representative paraphrases 30 cases: plan schema 100%, raw tools 93.3%, tools/execution/semantic correctness after policy normalization 100%

• Gemma 4 adversarial regression: 8/8

Detailed results are available in the evaluation summary, PostgreSQL summary, and pgvector summary.

Official questions containing sensitive fields are executed after providing named approval for evaluation purposes. "Evidence-linked answers" in the table is a basic metric checking whether claims reference actual evidenceId values, and the model answer path adds atomic single-evidence, exact figure and unit, and document excerpt matching checks on top. Semantic correctness rates are results from separate public fixture determinations. These figures are development baselines for the published official example questions and internal attack scenarios, and do not represent competition private test performance or general-purpose natural language accuracy.

7. Security Boundary

PolicyGraph does not rely on a single layer of string filtering.

1. Only structured QueryPlans are passed to executors.

2. The PostgreSQL AST checker validates single read queries, the 8 business tables and allowed columns, non-recursive CTEs, and blocks functions, locks, whole-row projections, table column alias lists, JOIN ... USING, cross joins, and excessive relationship joins.

3. PlanGate checks 4,096-byte questions, sensitive fields, result budgets, and graph relationships, and SQL results are capped at 100 rows by an external wrapper.

4. The PostgreSQL execution account has SELECT only on the 8 business tables and the internal document_chunks, and NL2SQL cannot access internal document tables. Execution uses READ ONLY transactions with a 5-second statement timeout.

5. Approvals are short-lived HMAC receipts bound to the user, server role, and exact plan, and cannot be reused.

6. Answer claims cite only one atomic evidence record and may use only identifiers, exact figures and units, and document excerpts that the evidence actually supports.

7. All runtimes require an HMAC-signed hash chain and a separate signature checkpoint. Original questions are not stored; only domain-separated SHA-256 digests are recorded, and validation fails if the checkpoint does not exactly match the current ledger head.

8. Data and submission ZIPs are checked for paths, duplicate entries, symbolic links, and entry count/size/compression ratio before extraction.

9. MCP and web failure responses provide only correlation IDs and do not expose internal connection information.

8. Repository Structure

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. Known Limitations and Next Steps

1. The official 30 questions use deterministic plans for reproducibility, and free-form expressions depend on the structured output quality of the Gemma 4 fallback.

2. CPU-based Gemma 4 takes tens of seconds, so real-time operation requires a GPU, a smaller model, or a plan cache.

3. The web is a loopback demo boundary, not a user authentication system. External publication requires OIDC/RBAC and a TLS reverse proxy.

4. An attacker who can clear both the audit ledger and signature checkpoint and steal the signing key is outside the local file boundary. In production, checkpoints must be stored in independent storage or WORM.

5. The graph is an in-memory implementation at the 133-node scale. Large-scale deployment requires a persistent graph store and load testing.

10. Submission Materials

The local submission candidate report DOCX/PDF, submitter checklist, and integrity manifest are in artifacts/submission/ and are excluded from the public repository to prevent mixing personal information and submission work products. The public repository includes reproducible source, raw evaluation data, CycloneDX SBOM, and model/data/AI usage notices.

The demo follows docs/DEMO_SCRIPT.md, and model/data/AI usage scope follows docs/MODEL_CARD.md, docs/DATA_LICENSE.md, and docs/AI_USAGE.md.

License

Project code is licensed under Apache License 2.0. The official Company-X dataset is used only within the competition participation scope specified by Liwon Ace and is not included in this repository.