FACTRAIL

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

FACTRAIL

Infraestrutura de evidências para agentes de IA.

FACTRAIL fornece aos agentes evidências estruturadas do mundo real com origem, atualidade, conflitos, níveis de suporte, cobertura, dependências não resolvidas e recibos reutilizáveis. É um beta público: as capacidades são definidas e inspecionáveis, e escopo não suportado ou fontes com falha são representados explicitamente.

FACTRAIL é um servidor Python Model Context Protocol. Este repositório contém a versão 2.4.0 do pacote, o Contrato de Evidências, testes, ferramentas de operação e o site estático. Implantações hospedadas podem executar uma versão diferente; inspecione os resultados ao vivo de tools/list e factrail_capabilities antes de depender das capacidades implantadas.

Conecte-se via MCP

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

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

A configuração do cliente varia. Site: factrail.online · Saúde: healthz.

Por que FACTRAIL

Os agentes não deveriam ter que escolher entre confiar cegamente na saída do modelo e reconstruir a verificação de fontes do zero. FACTRAIL fornece uma camada de evidências entre agentes e fontes de dados do mundo real. Em vez de retornar apenas uma resposta, ele pode retornar o que foi estabelecido, de onde veio, quão atual é, o que permanece não resolvido e um recibo que outro agente pode inspecionar posteriormente.

O princípio é simples: desconhecido é melhor do que inventado. A entrada do chamador não é verificada automaticamente. Valores derivados herdam a qualidade de suas dependências. Conflitos, dados desatualizados e falhas de fonte permanecem visíveis. Uma capacidade expõe seus limites programaticamente.

Ferramentas MCP principais

Novas integrações devem usar os primitivos genéricos:

Ferramenta	Propósito
factrail_capabilities	Descubra IDs de capacidade disponíveis, operações, versões, entradas, campos, fontes, estado dinâmico de fontes e limitações. Chame isto primeiro.
factrail_verify	Verifique fatos estruturados para um assunto suportado. Atualmente suporta company_fr.
factrail_assess	Avalie uma situação estruturada do mundo real. Atualmente suporta import (Beta).
factrail_get_receipt	Recupere um EvidenceEnvelope anterior pelo ID do recibo e verifique a integridade do conteúdo.

Ferramentas de compatibilidade permanecem disponíveis: verify_french_company, assess_import e analyze_company experimental/somente compatibilidade. Novos clientes devem preferir as ferramentas genéricas. analyze_company não sintetiza valores indisponíveis de finanças, crédito, rating, risco, recomendação, contagem de executivos ou confiança; campos indisponíveis permanecem nulos/indisponíveis.

Disponível hoje: verificação de empresas francesas

A capacidade company_fr é o resolvedor atual mais forte da FACTRAIL. Ela verifica informações suportadas de empresas e estabelecimentos franceses por SIREN ou SIRET usando registros INSEE / Sirene e BODACC. Dependendo dos registros de origem, os campos podem incluir identificadores, nomes legais e comerciais, status, forma jurídica, código NAF/atividade, sede, datas de criação/cessação, status de difusão e eventos BODACC. Nenhum campo é garantido para existir em todas as entidades.

Para status atual da empresa e nome legal atual, os dados do registro atual INSEE/Sirene têm precedência sobre as evidências de publicação BODACC. Evidências de prioridade mais baixa são retidas em vez de descartadas silenciosamente. Isso pode apoiar verificação de fornecedores, integração de fornecedores, procurement, enriquecimento de CRM, integração de marketplace e fluxos de suporte a empresas/KYB. FACTRAIL sozinho não é um sistema de conformidade KYC/KYB legalmente suficiente.

Exemplo de entrada para factrail_verify (substitua o espaço reservado por um identificador que você está autorizado a verificar):

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

A resposta real da fonte depende do identificador solicitado, disponibilidade da fonte e cobertura do registro. FACTRAIL não fabrica um resultado de exemplo aqui.

Beta: avaliação de comércio e importação

factrail_assess atualmente suporta assessment_type="import". Aceita conceitos estruturados como origem, destino, descrição do produto, classificação ou código HS/alfandegário conhecido, valor da mercadoria, quantidade, referências alfandegárias/IVA, entradas de conformidade e valores de frete/seguro. O resultado separa entrada do chamador, evidência de fonte, candidatos de classificação e cálculos determinísticos. A cobertura pode ser parcial ou provisória.

Não há integração autoritativa de IVA de Estado-Membro da UE ou cadeia completa autoritativa de custo de desembarque. Valores curados de IVA e tarifas permanecem marcados como curados/provisórios; cálculos derivados herdam a qualidade das dependências (derived_provisional quando suas entradas são provisórias). A avaliação de comércio não é uma decisão alfandegária vinculante e os candidatos de classificação não são classificação alfandegária definitiva.

Status oficial do TARIC da UE

FACTRAIL tem infraestrutura para ingestão validada de snapshots oficiais do TARIC da Comissão Europeia: doctor de pacote offline, parsing estrito/compatível, relatórios de aceitação, hashes/impressões digitais, verificações semânticas, índice SQLite normalizado, ativação atômica e tratamento de última boa/desatualizada. Nenhum snapshot TARIC genuíno da Comissão está atualmente instalado (not_installed). FACTRAIL não serve atualmente cobertura tarifária TARIC autoritativa ao vivo.

Access2Markets é evidência secundária/de suporte, nunca TARIC autoritativo. Referências tarifárias curadas da FACTRAIL são provisórias. Nenhum endpoint oficial estável de download automático foi confirmado, então a busca automática está indisponível neste momento. Arquivos oficiais fornecidos pelo operador podem ser diagnosticados e ingeridos offline; a ingestão mensal de snapshots é suportada, enquanto a aplicação de deltas diários é adiada.

Para procedimentos de operador, veja aceitação e operações de snapshot TARIC e as notas de descoberta de distribuição. Cálculo tarifário detalhado está fora da fundação atual de snapshot TARIC.

Contrato de Evidências

O EvidenceEnvelope canônico inclui schema_version, status, assunto, fatos, fontes de evidência, conflitos, cobertura, atualidade, receipt_id e generated_at. O esquema atual é EvidenceEnvelope 1.2; é independente da versão do pacote.

• Status pode ser supported, contradicted, insufficient_evidence, stale ou conflicting_sources; os resultados não são reduzidos a um booleano.
• Níveis de suporte descrevem a qualidade da evidência: authoritative, supported, derived_supported, derived_provisional, curated e caller_input. A entrada do chamador não é verificada externamente.
• Cobertura distingue campos solicitados, resolvidos e não resolvidos. Entrada ausente, campos não suportados e fontes indisponíveis são estados diferentes.
• Atualidade registra tempos de observação e status de desatualização.
• Conflitos preservam afirmações concorrentes de fontes; política de autoridade específica de campo pode resolver um conflito sem excluir sua evidência de prioridade mais baixa.
• Resultados de fonte distinguem sucesso, resposta parcial, erro/indisponibilidade de fonte, fonte não integrada, busca desabilitada e não necessário.

Um cálculo determinístico não se torna autoritativo apenas porque sua aritmética é determinística. Entradas autoritativas podem suportar um resultado derived_supported; entradas provisórias produzem resultados derived_provisional.

Recibos

Um ID de recibo (fr_…) é endereçado por conteúdo usando hashing canônico determinístico. Na recuperação, FACTRAIL recalcula o hash e rejeita conteúdo alterado com um erro de integridade. Canonicalização histórica suportada permanece disponível. Recibos tornam uma observação de evidência reutilizável e rastreável; eles fornecem integridade de conteúdo, não uma assinatura digital, registro em blockchain, entrada de livro-razão global imutável ou prova de que uma afirmação é universalmente verdadeira. O state_fingerprint identifica estado substantivo entre observações. Veja design do Evidence Core.

Fontes e princípios de confiança

A hierarquia de fontes da FACTRAIL é explícita: registros oficiais podem ser autoritativos para campos definidos, fontes secundárias permanecem secundárias, referências curadas permanecem curadas e entrada do chamador permanece entrada. Identidade da fonte, tempo de recuperação, hashes de conteúdo quando disponíveis, nível de suporte e status da fonte acompanham a evidência. Evidência histórica de publicação não determina automaticamente o estado atual.

FACTRAIL segue estes princípios:

1. Nunca fabrique evidências; desconhecido é melhor do que inventado.
2. A entrada do chamador não é verificada automaticamente.
3. Valores derivados herdam a qualidade de suporte de suas dependências.
4. Fontes conflitantes permanecem visíveis.
5. Falhas de fonte e evidência desatualizada são explícitas.
6. Evidência secundária não é silenciosamente promovida a autoritativa.
7. Recibos protegem a integridade do conteúdo, não a verdade filosófica.
8. Limites de capacidade são expostos programaticamente.

Início rápido: descubra, verifique, recupere

Use factrail_capabilities primeiro com {}. O resultado ao vivo identifica IDs de capacidade atualmente suportados e estado dinâmico de fontes. Então uma chamada de verificação de empresa usa:

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

Para recuperar o resultado posteriormente, passe seu receipt_id real:

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

Chamadas de ferramentas MCP envolvem esses objetos de argumento em seu protocolo de cliente normal. Veja exemplos de solicitação para entradas genéricas de verificação, recibo e importação. Exemplos usam espaços reservados e não afirmam saída fabricada.

Execute localmente

Requer Python 3.11 ou mais recente.

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 a porta 8765 por padrão. Use FACTRAIL_HOST e FACTRAIL_PORT para alterar o endereço de bind e a porta. Endpoint MCP local: POST http://localhost:8765/mcp; endpoint de saúde: /healthz. Para clientes stdio, execute python3 -m factrail.mcp_server.

Obtenha uma chave INSEE através do portal de API INSEE. O cache SQLite padrão é /tmp/factrail_cache.db; defina FACTRAIL_CACHE_PATH para um caminho persistente para recibos duráveis. O servidor inclui limitação de taxa por cliente e fallback de cache desatualizado para consultas de empresas.

Limitações atuais

FACTRAIL não fornece atualmente verificação arbitrária de fatos em linguagem natural, busca web geral ou busca de URLs, verificação de notícias, verificação ampla de empresas globais, resolvedores dedicados de beneficiário final/sanções/EORI, dados TARIC autoritativos da UE instalados, integração autoritativa de IVA da UE, resultados completos autoritativos de custo de desembarque, verificação regulatória arbitrária, recibos assinados, recibos em blockchain, livros-razão globais imutáveis de evidências, monitoramento contínuo de evidências ou raciocínio LLM de propósito geral sobre afirmações desconhecidas.

Implantação e desenvolvimento

Para operadores, veja o checklist de implantação, o guia de aceitação TARIC e as notas de distribuição. Histórico de versões: CHANGELOG. O site estático está em site/ e não precisa de etapa de build.

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

A suíte offline usa mocks e fixtures; testes ao vivo seguem a convenção --live do projeto e exigem acesso externo. A telemetria de demanda armazena categorias normalizadas e vinculação, não endereços IP brutos, strings completas de User-Agent, argumentos de solicitação, cabeçalhos de autorização ou envelopes completos de Evidence. Ela ajuda a identificar capacidades solicitadas e lacunas de evidência.

O wrapper Apify Actor é um canal fino de distribuição/pagamento para o serviço MCP canônico; ele não altera os adaptadores de fonte ou o comportamento de evidência da FACTRAIL.

Superfícies públicas de descoberta

• Site
• Orientação para agentes
• Texto da listagem Apify
• Texto da listagem Glama
• Texto da listagem Smithery
• Metadados GitHub

Licença

Código e documentação são licenciados sob Apache License 2.0. Dados de origem permanecem sujeitos aos termos do editor, incluindo licenças de dados abertos INSEE e BODACC.