Agente de datos MCP TrustFlow

Es un agente de datos MCP on-premise que convierte preguntas en lenguaje natural en planes de ejecución de SQL, búsqueda vectorial y grafo de conocimiento, y cuyo PolicyGraph interno valida y corrige antes de la ejecución, devolviendo además las evidencias y el registro de auditoría.

La versión actual 0.3.0 es candidata a presentación al concurso, validada por el equipo corevalue con los datos oficiales de Company-X de la tarea designada por Liwon Ace. El código del proyecto de divulgación externa tiene licencia Apache-2.0, y el conjunto de datos oficial se utiliza únicamente con fines de participación en el concurso, por lo que no se incluye en el repositorio.

Flujo principal

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

La diferencia de PolicyGraph es que "no ejecuta directamente el plan creado por el LLM".

• ALLOW: ejecuta los planes que cumplen la política.

• REPAIR: corrige el LIMIT de SQL, el topK de vectores, la profundidad de exploración del grafo, etc., dentro del rango permitido y luego ejecuta.

• APPROVAL_REQUIRED: los campos restringidos como salario o datos de contacto no se ejecutan hasta que se aprueben.

• DENY: no ejecuta SQL de escritura, sentencias múltiples, tablas o relaciones no registradas, etc.

Related MCP server: TalkDB

Alcance de implementación actual

1. Inicio rápido: línea base totalmente offline

El entorno requerido es Node.js 24 o superior y npm.

Obtener los datos oficiales

Instale las dependencias tal como están en el archivo de bloqueo, genere los secretos locales y luego descargue los datos oficiales.

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

El script solo descarga el ZIP oficial de Liwon Ace, verifica el SHA-256 y lo descomprime en data/companyx.

3008476738D992857D738337B4882772E88288F7B314DA235D6A5D120827D772

Si ya está instalado, no sobrescribe el original y solo verifica el checksum y los archivos obligatorios.

Instalación y verificación

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

El modo offline carga la semilla SQL oficial en SQLite en memoria, y la búsqueda de documentos utiliza una línea base vectorial local determinista sin dependencias. Es un modo de desarrollo para reproducir la política, las 3 herramientas, las evidencias y la auditoría sin Internet, Ollama ni Docker.

Los resultados de la evaluación se generan en artifacts/evaluation.

2. Ruta real de PostgreSQL

Con Docker Desktop en ejecución, ejecute lo siguiente.

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

Compose realiza automáticamente lo siguiente:

• Inicia PostgreSQL 16 + pgvector

• Crea las 8 tablas relacionales oficiales y document_chunks

• Carga los datos de la semilla oficial

• Crea el rol de solo lectura policygraph_reader. Los permisos de la base de datos se otorgan a las 8 tablas de trabajo y a la document_chunks interna, pero NL2SQL solo consulta las 8 tablas de trabajo y document_chunks se usa únicamente en el adaptador de búsqueda vectorial

• Crea el índice único de los fragmentos de documento y el índice vectorial HNSW

Compose solo se vincula al loopback del host y utiliza contraseñas aleatorias diferentes de administrador y de solo lectura generadas en .env. La prueba de humo se conecta con policygraph_reader. Si se utiliza una base de datos de otro entorno, especifique DATABASE_URL.

3. Búsqueda de documentos con Ollama + pgvector y LLM local opcional

Este paso requiere la descarga del modelo de embeddings y un servidor Ollama local.

ollama pull nomic-embed-text
ollama serve

En otra ventana de PowerShell, use la configuración de conexión de administrador del .env generado por npm run setup:local para fragmentar y generar embeddings de los documentos. No registre en documentos ni en el repositorio las cadenas de conexión que contengan contraseñas reales.

npm run ingest

El runtime MCP operativo también se inicia con la conexión de solo lectura del mismo .env.

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

Para que el LLM local cree borradores de plan para expresiones fuera de los ejemplos oficiales y para usar la síntesis de respuestas con evidencia limitada, prepare Gemma 4 E2B por separado y active el modo opcional.

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

Los planes creados por el LLM también deben pasar por el mismo PlanGate. Cada afirmación solo puede citar un registro de evidencia atómico, y si se combinan identificadores, cifras exactas o unidades que no están en esa evidencia, o se crean frases que no aparecen en el extracto del documento, se sustituyen por el formateador de evidencias determinista. Para la validación local se usaron gemma4:e2b 5.1B Q4_K_M y nomic-embed-text 137M F16.

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

En la máquina de validación (32GB de RAM, Intel Core Ultra 5 225H, inferencia por CPU), la generación de planes para 3 expresiones nuevas tardó aproximadamente 58,8 s, 45,0 s y 33,6 s respectivamente. No es una puntuación de calidad, sino una observación de una única ejecución en ese hardware. Tras el endurecimiento de seguridad final, en el nuevo E2E la respuesta Product-C1 del modelo superó la verificación estricta de afirmaciones basada en DOC-011, y el SQL de salario de viewer creado por el modelo se bloqueó antes de la ejecución con POL-SQL-005/004. Las salidas del modelo que no superan la verificación de afirmaciones se sustituyen de forma segura por respuestas deterministas.

Gestione las contraseñas reales mediante el archivo .env o un almacén de secretos y no las confíe al repositorio. Las imágenes de Compose fijan la versión de pgvector y el digest de la imagen para garantizar la reproducibilidad.

4. Demo web

npm run dev:web

Al abrir http://127.0.0.1:4173 en el navegador, podrá ver en una sola pantalla:

• Las 30 preguntas oficiales de SQL, Vector y Graph

• Typed QueryPlan

• Decisión ALLOW / REPAIR / APPROVAL_REQUIRED / DENY

• Política coincidente, finding y repair

• Respuestas verificadas y el libro de evidencias

• Escenarios de estrés de ataque de escritura, campos sensibles y presupuesto de búsqueda

El rol web se fija en el servidor mediante POLICYGRAPH_ACTOR_ROLE y se ignoran los valores de rol del cuerpo de la solicitud. La API web aplica límites de host loopback, mismo origen, JSON, cuerpo de 64 KiB, pregunta de 4.096 bytes, tasa de solicitudes y ejecución concurrente. Los mismos límites de pregunta se aplican a MCP y al planificador. Antes de la divulgación externa se necesita un proxy inverso de autenticación y TLS independiente.

5. Herramientas MCP

Un ejemplo de configuración del host MCP es el siguiente.

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

El rol que expone el servidor se define en el entorno del host y no puede cambiarse mediante la entrada del modelo. El approvalReceipt opcional de nl2sql es un valor firmado con HMAC que solo puede emitir el administrador; está vinculado al usuario, al rol y al plan normalizado, y solo puede usarse una vez en 5 minutos.

6. Resultados de la evaluación

Resultados de la ejecución de reproducción local actual:

• Preguntas de ejemplo oficiales: 30

• Pruebas automáticas: 37/37

• Enrutamiento de herramientas: 30/30

• Ejecución correcta: 30/30

• Respuestas con evidencia conectada: 30/30

• Decisión de política en ataques internos y casos límite: 8/8

• P95 offline: 25,77 ms

• P95 de PostgreSQL real: 173,12 ms

• 10 preguntas de documentos oficiales de pgvector: Hit@1 100%, Mean Recall@5 97,14%, MRR@10 1,0

• P95 de pgvector en caliente: 215,02 ms

• 30 paráfrasis representativas de Gemma 4: esquema de plan 100%, herramienta bruta 93,3%, herramienta, ejecución y respuesta semántica tras normalización de política 100%

• Regresión adversaria de Gemma 4: 8/8

Los resultados detallados están disponibles en el resumen de evaluación, el resumen de PostgreSQL y el resumen de pgvector.

Las preguntas oficiales que contienen campos sensibles se ejecutan tras proporcionar una aprobación registrada por nombre para la evaluación. La "respuesta con evidencia conectada" de la tabla es una métrica básica que comprueba si la afirmación hace referencia a un evidenceId real; la ruta de respuesta del modelo añade aquí la comprobación de evidencia atómica única, cifras y unidades exactas y coincidencia con el extracto del documento. La tasa de respuesta semántica es el resultado de la decisión de un fixture público independiente. Estas cifras son la línea base de desarrollo para las preguntas de ejemplo oficiales publicadas y los escenarios de ataque internos; no implican el rendimiento de las pruebas privadas del concurso ni la precisión general del lenguaje natural.

7. Límites de seguridad

PolicyGraph no depende únicamente de una capa de filtro de cadenas.

1. Solo se pasa un QueryPlan estructurado al ejecutor.

2. El verificador AST de PostgreSQL comprueba una única consulta de lectura, las 8 tablas de trabajo y las columnas permitidas, CTE no recursivos, funciones, bloqueos y proyecciones de fila completa, y bloquea la lista de alias de columnas de tabla, JOIN ... USING, cross join y las combinaciones de relaciones excesivas.

3. PlanGate comprueba la pregunta de 4.096 bytes, los campos sensibles, el presupuesto de resultados y las relaciones del grafo, y los resultados SQL se limitan a un máximo de 100 filas mediante un envoltorio externo.

4. La cuenta de ejecución de PostgreSQL solo tiene SELECT sobre las 8 tablas de trabajo y la document_chunks interna, y NL2SQL no puede acceder a la tabla de documentos interna. La ejecución utiliza una transacción READ ONLY y un timeout de sentencia de 5 segundos.

5. La aprobación es un recibo HMAC de corta duración vinculado al usuario, al rol del servidor y al plan exacto, y no es reutilizable.

6. La afirmación de la respuesta cita una única evidencia atómica y solo puede usar identificadores, cifras exactas, unidades y extractos de documento que esa evidencia respalde realmente.

7. Todos los runtimes exigen una cadena de hash con firma HMAC y un punto de control de firma independiente. No se almacena la pregunta original; solo se registra el digest SHA-256 con separación de dominios, y si el punto de control no coincide exactamente con la cabeza actual del libro, la verificación falla.

8. Los datos y el ZIP de presentación se comprueban antes de descomprimir: rutas, entradas duplicadas, enlaces simbólicos, número de entradas, tamaño y tasa de compresión.

9. Las respuestas de error de MCP y web solo proporcionan un ID de correlación y no exponen información de conexión interna.

8. Estructura del repositorio

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. Limitaciones conocidas y siguientes pasos

1. Las 30 preguntas oficiales usan planes deterministas para la reproducibilidad; las expresiones libres dependen de la calidad de la salida estructurada del respaldo de Gemma 4.

2. Gemma 4 basado en CPU tarda decenas de segundos, por lo que para operación en tiempo real se necesita GPU, un modelo más pequeño o una caché de planes.

3. La web es un límite de demo de loopback, no un sistema de autenticación de usuarios. Para la divulgación externa se necesitan OIDC/RBAC y un proxy inverso TLS.

4. Un atacante que pueda borrar tanto el libro de auditoría como el punto de control de firma y además robar la clave de firma queda fuera del límite de archivos local. En operación, el punto de control debe guardarse en un almacenamiento independiente o WORM.

5. El grafo es una implementación en memoria a escala de 133 nodos. Para aplicaciones a gran escala se necesitan un almacén de grafos persistente y pruebas de carga.

10. Materiales de presentación

El informe de resultados candidato local en DOCX y PDF, la lista de verificación del presentador y la lista de integridad están en artifacts/submission/ y se excluyen del repositorio público para evitar la mezcla de información personal y material de trabajo de la presentación. El repositorio público incluye el código fuente reproducible, los datos brutos de evaluación, el SBOM CycloneDX y el aviso de uso de modelos, datos e IA.

La demostración sigue docs/DEMO_SCRIPT.md, y el alcance del uso de modelos, datos e IA se describe en docs/MODEL_CARD.md, docs/DATA_LICENSE.md y docs/AI_USAGE.md.

Licencia

El código del proyecto tiene licencia Apache License 2.0. El conjunto de datos oficial de Company-X se utiliza únicamente dentro del alcance de participación en el concurso especificado por Liwon Ace y no se incluye en este repositorio.