FACTRAIL

FACTRAIL — Infraestructura de evidencia para agentes de IA. Evidencia estructurada del mundo real respaldada por fuentes, con procedencia, frescura, incertidumbre explícita y recibos reutilizables. La verificación de empresas francesas está disponible ahora; la evaluación comercial/de importación está en beta.

GitHubPrueba este MCPPatrocinado

Servidor MCP alojado

npx add-mcp 'https://mcp.factrail.online/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

FACTRAIL

Infraestructura de evidencia para agentes de IA.

FACTRAIL proporciona a los agentes evidencia estructurada del mundo real respaldada por fuentes, con procedencia, frescura, conflictos, niveles de soporte, cobertura, dependencias no resueltas y recibos reutilizables. Es una versión beta pública: las capacidades están definidas e inspeccionables, y el alcance no compatible o las fuentes fallidas se representan explícitamente.

FACTRAIL es un servidor de Python Model Context Protocol. Este repositorio contiene la versión 2.4.0 del paquete, el Contrato de Evidencia, pruebas, herramientas de operador y el sitio estático. Las implementaciones alojadas pueden ejecutar una versión diferente; inspeccione los resultados en vivo de tools/list y factrail_capabilities antes de confiar en las capacidades implementadas.

Conectar vía MCP

Endpoint: https://mcp.factrail.online/mcp (HTTP Streamable)

{
  "mcpServers": {
    "factrail": {
      "url": "https://mcp.factrail.online/mcp"
    }
  }
}

La configuración del cliente varía. Sitio web: factrail.online · Salud: healthz.

Por qué FACTRAIL

Los agentes no deberían tener que elegir entre confiar ciegamente en la salida del modelo y reconstruir la verificación de fuentes desde cero. FACTRAIL proporciona una capa de evidencia entre los agentes y las fuentes de datos del mundo real. En lugar de devolver solo una respuesta, puede devolver qué se estableció, de dónde provino, qué tan actual es, qué queda sin resolver y un recibo que otro agente puede inspeccionar más tarde.

El principio es simple: lo desconocido es mejor que lo inventado. La entrada del llamador no se verifica automáticamente. Los valores derivados heredan la calidad de sus dependencias. Los conflictos, los datos obsoletos y las fallas de fuente permanecen visibles. Una capacidad expone sus límites programáticamente.

Herramientas MCP principales

Las nuevas integraciones deben usar los primitivos genéricos:

Herramienta	Propósito
`factrail_capabilities`	Descubrir IDs de capacidad disponibles, operaciones, versiones, entradas, campos, fuentes, estado dinámico de fuentes y limitaciones. Llame a esto primero.
`factrail_verify`	Verificar hechos estructurados para un sujeto compatible. Actualmente admite `company_fr`.
`factrail_assess`	Evaluar una situación estructurada del mundo real. Actualmente admite `import` (Beta).
`factrail_get_receipt`	Recuperar un EvidenceEnvelope anterior por ID de recibo y verificar la integridad del contenido.

Las herramientas de compatibilidad siguen disponibles: verify_french_company, assess_import y analyze_company experimental/solo compatibilidad. Los nuevos clientes deben preferir las herramientas genéricas. analyze_company no sintetiza valores de finanzas, crédito, calificación, riesgo, recomendación, recuento ejecutivo o confianza no disponibles; los campos no disponibles permanecen nulos/no disponibles.

Disponible hoy: verificación de empresas francesas

La capacidad company_fr es el resolutor actual más sólido de FACTRAIL. Verifica información compatible de empresas y establecimientos franceses por SIREN o SIRET utilizando registros INSEE / Sirene y BODACC. Dependiendo de los registros de fuente, los campos pueden incluir identificadores, nombres legales y comerciales, estado, forma legal, código NAF/actividad, sede central, fechas de creación/cese, estado de difusión y eventos BODACC. Ningún campo está garantizado para existir en cada entidad.

Para el estado actual de la empresa y el nombre legal actual, los datos del registro actual INSEE/Sirene tienen prioridad sobre la evidencia de publicación BODACC. La evidencia de menor prioridad se conserva en lugar de descartarse silenciosamente. Esto puede respaldar la verificación de proveedores, la incorporación de vendedores, el aprovisionamiento, el enriquecimiento de CRM, la incorporación a mercados y los flujos de trabajo de soporte de empresas/KYB. FACTRAIL por sí solo no es un sistema de cumplimiento KYC/KYB legalmente suficiente.

Ejemplo de entrada para factrail_verify (reemplace el marcador de posición con un identificador que esté autorizado a verificar):

{
  "subject_type": "company_fr",
  "identifier": "<9-digit SIREN or 14-digit SIRET>",
  "fields": ["status", "legal_name", "head_office"]
}

La respuesta real de la fuente depende del identificador solicitado, la disponibilidad de la fuente y la cobertura del registro. FACTRAIL no fabrica un resultado de muestra aquí.

Beta: evaluación de comercio e importación

factrail_assess actualmente admite assessment_type="import". Acepta conceptos estructurados como origen, destino, descripción del producto, clasificación o código HS/aduanero conocido, valor de la mercancía, cantidad, referencias aduaneras/IVA, entradas de cumplimiento y valores de flete/seguro. El resultado separa la entrada del llamador, la evidencia de la fuente, los candidatos de clasificación y los cálculos deterministas. La cobertura puede ser parcial o provisional.

No hay integración autoritativa de IVA de los Estados miembros de la UE ni una cadena completa autoritativa de costo de entrega. Los valores de IVA y aranceles seleccionados permanecen marcados como seleccionados/provisionales; los cálculos derivados heredan la calidad de la dependencia (derived_provisional cuando sus entradas son provisionales). La evaluación comercial no es una resolución aduanera vinculante y los candidatos de clasificación no son una clasificación aduanera definitiva.

Estado oficial de TARIC de la UE

FACTRAIL tiene infraestructura para la ingesta validada de instantáneas oficiales de TARIC de la Comisión Europea: doctor de paquetes sin conexión, análisis estricto/compatible, informes de aceptación, hashes/huellas digitales, comprobaciones semánticas, índice SQLite normalizado, activación atómica y manejo de último bueno/obsoleto. Actualmente no hay ninguna instantánea TARIC genuina de la Comisión instalada (not_installed). FACTRAIL actualmente no ofrece cobertura arancelaria TARIC autoritativa en vivo.

Access2Markets es evidencia secundaria/de apoyo, nunca TARIC autoritativo. Las referencias arancelarias seleccionadas de FACTRAIL son provisionales. No se confirmó ningún endpoint oficial estable de descarga automática, por lo que la obtención automática no está disponible en este momento. Los archivos oficiales proporcionados por el operador se pueden diagnosticar e ingerir sin conexión; se admite la ingesta mensual de instantáneas, mientras que la aplicación de deltas diarios se difiere.

Para procedimientos de operador, consulte aceptación y operaciones de instantáneas TARIC y las notas de descubrimiento de distribución. El cálculo detallado de aranceles está fuera de la base actual de instantáneas TARIC.

Contrato de Evidencia

El EvidenceEnvelope canónico incluye schema_version, estado, sujeto, hechos, fuentes de evidencia, conflictos, cobertura, frescura, receipt_id y generated_at. El esquema actual es EvidenceEnvelope 1.2; es independiente de la versión del paquete.

Estado puede ser supported, contradicted, insufficient_evidence, stale o conflicting_sources; los resultados no se reducen a un booleano.
Niveles de soporte describen la calidad de la evidencia: authoritative, supported, derived_supported, derived_provisional, curated y caller_input. La entrada del llamador no se verifica externamente.
Cobertura distingue campos solicitados, resueltos y no resueltos. La entrada faltante, los campos no compatibles y las fuentes no disponibles son estados diferentes.
Frescura registra los tiempos de observación y el estado de obsolescencia.
Conflictos preservan afirmaciones de fuentes en competencia; la política de autoridad específica del campo puede resolver un conflicto sin eliminar su evidencia de menor prioridad.
Resultados de fuente distinguen éxito, respuesta parcial, error de fuente/no disponible, fuente no integrada, búsqueda deshabilitada y no requerida.

Un cálculo determinista no se vuelve autoritativo simplemente porque su aritmética sea determinista. Las entradas autoritativas pueden respaldar un resultado derived_supported; las entradas provisionales producen resultados derived_provisional.

Recibos

Un ID de recibo (fr_…) se direcciona por contenido mediante hash canónico determinista. Al recuperarlo, FACTRAIL recalcula el hash y rechaza el contenido alterado con un error de integridad. La canonicalización histórica compatible sigue disponible. Los recibos hacen que una observación de evidencia sea reutilizable y trazable; proporcionan integridad de contenido, no una firma digital, registro de blockchain, entrada de libro mayor global inmutable o prueba de que una declaración es universalmente verdadera. El state_fingerprint identifica el estado sustantivo entre observaciones. Consulte diseño de Evidence Core.

Fuentes y principios de confianza

La jerarquía de fuentes de FACTRAIL es explícita: los registros oficiales pueden ser autoritativos para campos definidos, las fuentes secundarias permanecen secundarias, las referencias seleccionadas permanecen seleccionadas y la entrada del llamador permanece como entrada. La identidad de la fuente, el tiempo de recuperación, los hashes de contenido cuando estén disponibles, el nivel de soporte y el estado de la fuente acompañan a la evidencia. La evidencia de publicación histórica no determina automáticamente el estado actual.

FACTRAIL sigue estos principios:

Nunca fabricar evidencia; lo desconocido es mejor que lo inventado.
La entrada del llamador no se verifica automáticamente.
Los valores derivados heredan la calidad de soporte de sus dependencias.
Las fuentes en conflicto permanecen visibles.
Las fallas de fuente y la evidencia obsoleta son explícitas.
La evidencia secundaria no se promueve silenciosamente a autoritativa.
Los recibos protegen la integridad del contenido, no la verdad filosófica.
Los límites de capacidad se exponen programáticamente.

Inicio rápido: descubrir, verificar, recuperar

Use factrail_capabilities primero con {}. El resultado en vivo identifica los IDs de capacidad actualmente compatibles y el estado dinámico de las fuentes. Luego, una llamada de verificación de empresa usa:

{
  "subject_type": "company_fr",
  "identifier": "<SIREN or SIRET>",
  "fields": ["status", "legal_name"]
}

Para recuperar el resultado más tarde, pase su receipt_id real:

{"receipt_id":"<receipt_id returned by FACTRAIL>"}

Las llamadas a herramientas MCP envuelven estos objetos de argumento en su protocolo de cliente normal. Consulte ejemplos de solicitud para entradas genéricas de verificación, recibo e importación. Los ejemplos usan marcadores de posición y no afirman salida fabricada.

Ejecutar localmente

Requiere Python 3.11 o superior.

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
cp .env.example .env
# Set INSEE_API_KEY in .env for live French company lookups.
python3 -m factrail.mcp_http_server

HTTP usa por defecto el puerto 8765. Use FACTRAIL_HOST y FACTRAIL_PORT para cambiar la dirección de enlace y el puerto. Endpoint MCP local: POST http://localhost:8765/mcp; endpoint de salud: /healthz. Para clientes stdio, ejecute python3 -m factrail.mcp_server.

Obtenga una clave INSEE a través del portal de API INSEE. La caché SQLite predeterminada es /tmp/factrail_cache.db; establezca FACTRAIL_CACHE_PATH en una ruta persistente para recibos duraderos. El servidor incluye limitación de velocidad por cliente y respaldo de caché obsoleta para búsquedas de empresas.

Limitaciones actuales

FACTRAIL actualmente no proporciona verificación arbitraria de hechos en lenguaje natural, búsqueda web general o recuperación de URL, verificación de noticias, verificación amplia de empresas globales, resolutores dedicados de beneficiarios finales/sanciones/EORI, datos TARIC autoritativos de la UE instalados, integración autoritativa de IVA de la UE, resultados completos autoritativos de costo de entrega, verificación regulatoria arbitraria, recibos firmados, recibos de blockchain, libros mayores de evidencia globales inmutables, monitoreo continuo de evidencia o razonamiento LLM de propósito general sobre afirmaciones desconocidas.

Implementación y desarrollo

Para operadores, consulte la lista de verificación de implementación, la guía de aceptación TARIC y las notas de distribución. Historial de versiones: CHANGELOG. El sitio estático está en site/ y no necesita paso de compilación.

python3 -m pytest -q
python3 -m compileall -q factrail tests
python3 -m factrail.evidence.demand --days 7

El conjunto sin conexión usa mocks y fixtures; las pruebas en vivo siguen la convención --live del proyecto y requieren acceso externo. La telemetría de demanda almacena categorías normalizadas y vinculación, no direcciones IP sin procesar, cadenas completas de User-Agent, argumentos de solicitud, encabezados de autorización o envelopes de evidencia completos. Ayuda a identificar capacidades solicitadas y brechas de evidencia.

El envoltorio Apify Actor es un canal delgado de distribución/pago para el servicio MCP canónico; no cambia los adaptadores de fuente ni el comportamiento de evidencia de FACTRAIL.

Superficies de descubrimiento público

Licencia

El código y la documentación están bajo Licencia Apache 2.0. Los datos de origen siguen sujetos a los términos del editor, incluidas las licencias de datos abiertos de INSEE y BODACC.