ACG Mcp

Servidor MCP independente para o Protocolo de Geração de Contexto Auditado (ACG) — verificação de fatos auditável e RAG fundamentado via MongoDB.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP ACG

Servidor MCP autônomo para o Protocolo de Geração de Contexto Auditado (ACG) — verificação factual verificável e RAG fundamentado via MongoDB.

O ACG fornece um padrão de dupla camada para garantia de veracidade:

UGVP (Camada 1): Fundamentação atômica de fatos com Marcadores de Reivindicação e Identidade de Hash de Fonte (SHI)
RSVP (Camada 2): Verificação de síntese lógica com Marcadores de Relacionamento

Por que ACG — o que você pode fazer com ele

LLMs afirmam com confiança coisas que estão erradas, e geralmente não há como verificar — a resposta é uma caixa preta sem proveniência. O ACG resolve isso tornando cada resposta auditável por construção:

Fundamente cada fato à sua fonte. Indexe uma URL uma vez e toda resposta posterior construída a partir dela carrega Marcadores de Reivindicação inline como [C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0] — o prefixo SHI baseado em SHA-256 identifica o documento de origem exato, e o seletor CSS aponta para o trecho preciso dentro dele.
Verifique em vez de confiar. acg_verify_claims re-busca cada fonte e faz correspondência difusa de cada reivindicação contra o texto real, então a verificação não é uma opinião de LLM auto-relatada — é uma verificação independente e repetível. Uma reivindicação ou existe na fonte citada ou falha.
Saiba quando a base de conhecimento é suficiente. acg_check_indexed retorna um score de confiança (ALTO / MÉDIO / BAIXO) antes de você acessar a rede, então você só busca novas páginas quando o índice genuinamente não consegue responder.
Obtenha uma trilha de auditoria legível por máquina. acg_build_var emite um Registro de Auditoria de Veracidade (entradas SSR + RAR) — um registro JSON de cada reivindicação, sua impressão digital de fonte e cada relacionamento lógico entre reivindicações, pronto para ser consumido por sistemas downstream ou humanos.
Use em dois modos. Execute o fluxo de trabalho forçado (acg_run_workflow) e obtenha uma resposta completa, verificada e auditada em uma única chamada — ou componha as ferramentas individuais da maneira que seu próprio fluxo de trabalho exigir (veja Duas maneiras de usar ACG).

Em resumo: o ACG transforma "confie em mim, o modelo disse" em "aqui está a reivindicação, aqui está a localização exata da fonte, aqui está o resultado da verificação, e aqui está o registro de auditoria."

Recursos

Fluxo de trabalho forçado → Uma chamada executa todo o pipeline: busca, auto-indexação, fundamentação, verificação, auditoria (veja Duas maneiras de usar ACG)
Indexar URLs → Extrai texto, divide em frases, gera embeddings, armazena no MongoDB
Buscar Fontes → Busca semântica (vetorial) + por palavras-chave no conteúdo indexado
Verificar Indexado → Consulta com score de confiança para evitar chamadas web_fetch desnecessárias
Gerar Texto Fundamentado → Cria saída verificável com Marcadores de Reivindicação inline
Verificar Reivindicações → Re-busca fontes, faz correspondência difusa de reivindicações contra o texto da fonte
Construir VAR → Gera Registro de Auditoria de Veracidade legível por máquina (SSR + RAR)
Rastrear e Indexar → Descoberta de URL BFS + pipeline automático de indexação ACG
Redefinir Banco de Dados → Remove todas as coleções ACG (com proteção de confirmação)

Requisitos

Python 3.11+
Instância MongoDB (local ou Atlas)
- Atlas Vector Search é opcional — usa busca por palavras-chave como fallback se não houver modelo de embedding

Instalação

Requer Python 3.11+. Um ambiente virtual é fortemente recomendado — em Debian/Ubuntu recentes (23.04+) e outras distros PEP 668, pip install puro se recusa a escrever no Python do sistema, então a Opção A é o caminho confiável lá.

Opção A: Ambiente virtual + instalação editável (recomendado)

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -e .

Isso instala o pacote e suas dependências no venv e coloca o comando acg-mcp no PATH enquanto o venv estiver ativo. O modo editável significa que mudanças locais no código se aplicam imediatamente — sem necessidade de reinstalação.

Clientes MCP não carregam seu shell, então aponte-os para o binário do venv por caminho absoluto em vez de depender do PATH (veja Conectar de um cliente MCP).

Opção B: Instalação em todo o sistema (agentes / ferramentas CLI)

Se você quiser acg-mcp disponível no PATH de qualquer diretório sem venv:

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
pip install -e .

Se o pip falhar com externally-managed-environment (PEP 668), use um venv (Opção A) ou adicione --break-system-packages.

Opção C: Executar a partir do código-fonte (sem instalação)

git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
pip install -r requirements.txt
# Must be run from the project root:
python -m src.server

Configuração

Copie .env.sample para .env e configure:

# MongoDB connection string (required)
MONGO_URI=mongodb://localhost:27017

# MongoDB database name (optional, default: acg_protocol)
MONGO_DB=acg_protocol

# Embedding model cache directory (optional)
EMBEDDING_CACHE_DIR=

# Vector search candidate cap (optional, default: 10000).
# Number of embedded chunks scanned per query. Raise it if your index
# exceeds this and you see false "LOW confidence" results.
ACG_VECTOR_MAX_CANDIDATES=10000

Para MongoDB Atlas:

MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/acg_protocol?retryWrites=true&w=majority

Uso

Executar o servidor MCP (transporte stdio)

Após instalar com a Opção A ou B:

# venv (Option A): works while the venv is active
# system-wide (Option B): works from any directory
acg-mcp

Sem instalar o CLI (apenas diretório de origem):

cd /path/to/acg_mcp
python -m src.server

Executar o fluxo de trabalho forçado a partir do CLI

O CLI de uma chamada executa todo o pipeline auditado sem um cliente MCP:

# Query the index, print the grounded answer + audit footer
acg-mcp --workflow "What does the README say about MONGO_URI?"

# Same, but auto-index a URL first when confidence is LOW
acg-mcp --workflow "How do I configure MongoDB Atlas?" https://example.com/docs/setup

Conectar de um cliente MCP

O servidor se comunica via stdio. Claude Desktop e Opencode usam formatos de configuração diferentes, então os exemplos abaixo são divididos por cliente: Claude Desktop usa a chave mcpServers; Opencode usa uma chave de nível superior mcp onde cada servidor precisa de "type" e command é um array.

Claude Desktop

Claude Desktop lê claude_desktop_config.json e usa a chave mcpServers. Se você instalou com a Opção A (venv), aponte para o binário do venv — clientes não carregam seu shell:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "/absolute/path/to/acg_mcp/venv/bin/acg-mcp",
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Com uma instalação em todo o sistema (Opção B), o comando puro funciona diretamente:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "acg-mcp",
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Opencode

Opencode lê opencode.json (ou opencode.jsonc) e usa uma chave de nível superior mcp. Servidores locais exigem "type": "local", command como um array do binário + argumentos, e variáveis de ambiente sob "environment" (não "env"):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["/absolute/path/to/acg_mcp/venv/bin/acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Com uma instalação em todo o sistema (Opção B), use o comando puro:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Executando a partir do diretório de origem

Se você não instalou o CLI, use o caminho completo. Claude Desktop:

{
  "mcpServers": {
    "acg-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Opencode — observe cwd para que src.server resolva relativo ao projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["python", "-m", "src.server"],
      "cwd": "/path/to/acg_mcp",
      "environment": {
        "MONGO_URI": "mongodb+srv://..."
      }
    }
  }
}

Importante: Ao usar python -m src.server, execute o cliente MCP a partir do diretório raiz do projeto (/path/to/acg_mcp) ou defina cwd na configuração MCP.

Locais de configuração

Ferramenta	Arquivo de Configuração	Escopo
Claude Desktop	`claude_desktop_config.json`	Usuário
Opencode	`~/.config/opencode/opencode.json`	Usuário (global)
Opencode	`opencode.json` / `opencode.jsonc` (raiz do projeto)	Por projeto (local)

Duas maneiras de usar ACG

O ACG inclui tanto um fluxo de trabalho forçado de ponta a ponta quanto as ferramentas individuais das quais ele é construído. Use o que se adequar à sua tarefa.

1. Fluxo de trabalho forçado — o protocolo completo em uma chamada

Chame acg_run_workflow(query, url="") e o servidor executa o pipeline completo para você, nesta ordem:

busca — busca nas fontes indexadas pela consulta
indexação — se a confiança for BAIXA e um url foi fornecido, indexe-o primeiro, depois re-busque (auto-busca)
fundamentação — compõe uma resposta fundamentada com Marcadores de Reivindicação UGVP inline
verificação — re-busca cada fonte citada e faz correspondência difusa de cada reivindicação
auditoria — constrói o Registro de Auditoria de Veracidade (SSR + RAR)

O relatório único retornado contém tudo: a resposta fundamentada, resultados de verificação por reivindicação, uma Tabela de Assinaturas de Trechos e o rodapé de auditoria — [Claims Verified: x/y], [ACG Accuracy: N%], [ACG Signed: ACG Protocol]. Você obtém uma resposta verificável sem orquestrar nenhuma das etapas você mesmo.

// acg_run_workflow("What is the pricing of the flash model?")
{
  "query": "What is the pricing of the flash model?",
  "workflow": ["search", "ground", "verify", "audit"],
  "confidence_tier": "HIGH",
  "grounded_answer": "Flash input tokens cost $0.14 per 1M [C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0].",
  "claims_verified": "1/1",
  "acg_accuracy": 100.0,
  "acg_signed": "ACG Protocol",
  "var": { "protocol": "ACG/1.0", "ssr_entries": [ /* ... */ ], "rar_entries": [] }
}

2. Ferramentas individuais — adapte o ACG ao seu próprio fluxo de trabalho

Cada etapa também está disponível como uma ferramenta autônoma, então você pode compor exatamente o pipeline que seu fluxo de trabalho precisa — divisão diferente, limiares de verificação personalizados, sua própria estratégia de recuperação, ou ACG usado puramente como uma camada de auditoria pós-geração.

Ferramenta	Quando usar
`acg_index_url`	Você tem uma URL e quer ela na base de conhecimento
`acg_check_indexed`	Você quer saber se o índice pode responder antes de buscar qualquer coisa
`acg_search_sources`	Você quer trechos correspondentes brutos com scores, para construir sua própria resposta
`acg_generate_grounded_text`	Você tem uma resposta e quer anexar Marcadores de Reivindicação a ela
`acg_verify_claims`	Você tem texto marcado e quer uma passagem de verificação independente
`acg_build_var`	Você quer o registro de auditoria legível por máquina (SSR + RAR)
`acg_crawl_and_index`	Você tem um site de documentação e quer indexá-lo como um todo

Por exemplo, um fluxo de trabalho "somente verificação" que audita texto gerado em outro lugar:

acg_generate_grounded_text(claim, shi_prefix, css_selector)
    -> acg_verify_claims(grounded_text)
    -> acg_build_var(grounded_text)

Uso de outras ferramentas e agentes

Uma vez instalado com a Opção A (venv) ou Opção B (todo o sistema), qualquer ferramenta ou agente na máquina pode usar acg-mcp referenciando-o em sua configuração MCP. Adicione-o à configuração global do Opencode do agente (~/.config/opencode/opencode.json) usando a sintaxe mcp do Opencode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "acg-mcp": {
      "type": "local",
      "command": ["acg-mcp"],
      "enabled": true,
      "environment": {
        "MONGO_URI": "mongodb://localhost:27017"
      }
    }
  }
}

O agente pode então chamar as ferramentas ACG diretamente:

acg_run_workflow() — Uma chamada: resposta completa verificada e auditada
acg_check_indexed() — Verifica se respostas existem nas fontes indexadas
acg_index_url() — Indexa novas URLs
acg_verify_claims() — Verifica reivindicações de texto fundamentado
acg_search_sources() — Busca na base de conhecimento indexada

Passando variáveis de ambiente

Passe MONGO_URI e outras configurações via o campo env (Claude Desktop) ou campo environment (Opencode) na configuração MCP. O servidor também carrega .env do diretório do projeto (via python-dotenv) quando instalado editável (pip install -e .) ou executado a partir da raiz do projeto.

Ferramentas Disponíveis

Ferramenta	Descrição
`acg_run_workflow`	Pipeline forçado — busca, auto-indexação, fundamentação, verificação, auditoria em uma chamada
`acg_index_url`	Indexa uma URL para ACG — busca, divide, incorpora, armazena
`acg_check_indexed`	Verifica se uma consulta tem resultados nas fontes indexadas
`acg_search_sources`	Busca nas fontes indexadas por palavra-chave
`acg_list_sources`	Lista todas as fontes indexadas
`acg_count_sources`	Conta o total de fontes indexadas
`acg_generate_grounded_text`	Cria texto com Marcadores de Reivindicação (UGVP)
`acg_verify_claims`	Verifica reivindicações contra suas fontes (correspondência difusa)
`acg_build_var`	Constrói Registro de Auditoria de Veracidade (SSR + RAR)
`acg_crawl_and_index`	Rastreia + indexa múltiplas URLs (suporte em segundo plano)
`acg_crawl_status`	Verifica o status da tarefa de rastreamento em segundo plano
`acg_crawl_list_tasks`	Lista todas as tarefas de rastreamento em segundo plano
`acg_reset_database`	⚠️ Exclui todos os dados indexados (requer confirm=true)

Coleções do Banco de Dados

O servidor usa uma estrutura padrão de coleções MongoDB:

Coleção	Propósito
`sources`	Metadados da fonte (url, shi_prefix, url_hash, total_chunks)
`data`	Trechos com embeddings (source_id, text, sentences, embedding)
`claims`	Reivindicações verificadas (claim_id, shi_prefix, claim_text, verified)
`relationships`	Registros de relacionamento RSVP (rel_id, rel_type, claim_ids)
`var_entries`	Entradas do Registro de Auditoria de Veracidade

Índices são criados automaticamente na primeira conexão.

Licença

MIT