Ackrite
Um servidor MCP que faz agentes de IA comprovarem suas suposições antes de agir com base nelas.
Documentação
Ackrite
ACKRITE. PROVE IT.
Um servidor MCP que faz agentes de IA provarem suas suposições antes de agir com base nelas.
Ackrite é um utilitário de verificação focado para agentes de IA. Ele não tenta resolver todos os problemas, buscar respostas convenientes ou inventar corroboração. Em vez disso, ele desafia a afirmação técnica de um agente usando apenas as evidências fornecidas a ele, distingue fatos de hipóteses, identifica provas ausentes e recomenda a menor próxima verificação que possa resolver a questão.
Seu propósito é prevenir um modo de falha familiar: um agente vê um erro, assume a causa, reescreve com confiança metade do sistema e só então descobre que a suposição estava errada. Ackrite empurra o agente em direção a evidências, experimentos direcionados, mudanças de escopo e incerteza explícita.
| Ackrite faz | Ackrite não faz |
|---|---|
| Classifica afirmações a partir de evidências fornecidas | Inventa, busca ou implica evidências que não recebeu |
| Detecta contradições e suposições sem suporte | Apresenta uma inferência como fato |
| Desafia reescritas e aumento de escopo antes da implementação | Aplica alterações de código ou chama sistemas externos |
| Rastreia um histórico de verificação limitado em processo | Persiste um grande sistema de memória ou depende de L-Dopa |
| Remove segredos comuns da saída de diagnóstico | Garante detecção perfeita de segredos para todo formato de credencial personalizado |
Por que existe
A confiança de um agente não é evidência. Uma afirmação como "a API removeu a autenticação nativa" é frequentemente uma hipótese útil, mas torna-se perigosa quando tratada como fato estabelecido e usada para justificar uma reescrita. Ackrite faz quatro perguntas objetivas:
- O que a evidência fornecida realmente estabelece?
- O que contradiz a afirmação, se houver algo?
- Qual suposição está fazendo o trabalho pesado?
- Qual é a menor verificação empírica a executar em seguida?
O resultado é deliberadamente conciso o suficiente para ser colocado diretamente de volta no contexto do agente.
Status de afirmações
Ackrite usa um modelo de classificação deliberadamente conservador.
| Status | Significado | Limiar de evidência |
|---|---|---|
KNOWN | Evidência direta e de alta confiabilidade fornecida apoia a afirmação. | Pelo menos um item direto de alta confiabilidade, como um resultado de teste focado, resposta HTTP, comportamento observado ou fato fornecido pelo usuário. |
SUPPORTED | Evidência direta fornecida apoia a afirmação, mas permanece limitada em escopo ou confiabilidade. | Evidência direta de apoio sem um item de alta confiabilidade qualificador. |
PLAUSIBLE | A afirmação pode ser verdadeira, mas o material é indireto, neutro ou inferido. | Apenas evidência neutra ou inferência. |
UNVERIFIED | Nenhuma evidência de apoio fornecida estabelece a afirmação. | Nenhuma evidência relevante. |
CONTRADICTED | Pelo menos um item de evidência fornecido contradiz a afirmação. | A contradição tem precedência até ser reconciliada. |
Regra fundamental: Ackrite nunca eleva uma inferência a fato. Ele rotula a fronteira entre observação e conclusão.
Arquitetura
Ackrite é intencionalmente pequeno. A fronteira MCP, análise de domínio, manipulação de evidências e estado limitado são separados para que as regras de verificação possam ser testadas sem um cliente MCP em execução.
| Camada | Localização | Responsabilidade |
|---|---|---|
| Transporte e esquemas MCP | src/mcp/server.ts, src/index.ts | Registra cinco ferramentas e as serve via entrada/saída padrão. |
| Orquestração de ferramentas | src/tools/verification-tools.ts | Produz respostas de desafio, verificação, auditoria, plano de prova e verificação de realidade prontas para agentes. |
| Modelo de evidência | src/core/evidence.ts | Normaliza proveniência, confiabilidade, polaridade, trechos e remoção de segredos. |
| Análise de afirmações | src/core/claim-analysis.ts | Determina status, confiança, suposições, provas ausentes e próxima ação. |
| Histórico de sessão | src/core/state.ts | Mantém um registro limitado em processo de afirmações, evidências, tentativas, conclusões e suposições não resolvidas. |
| Testes | test/ackrite.test.mjs | Exercita a lógica de domínio e o comportamento real do cliente/servidor stdio MCP. |
Ackrite é implementado em TypeScript usando os pacotes oficiais de servidor e cliente MCP TypeScript. Ele expõe um servidor stdio: um cliente inicia Ackrite como um subprocesso e troca mensagens JSON-RPC através da entrada e saída padrão, que é um transporte MCP padrão. [1] [2]
Instalação
Ackrite requer Node.js 20 ou posterior.
git clone https://github.com/mshanghai570/Ackrite.git
cd Ackrite
npm install
npm run build
Inicie o servidor diretamente após a compilação:
npm start
O processo se comunica via entrada/saída padrão, então pode parecer ocioso quando executado em um terminal. Isso é esperado: seu cliente MCP fornece as solicitações. Mantenha logs normais fora da saída padrão; MCP stdio a reserva para mensagens de protocolo. [1]
Configuração do cliente MCP
Compile o projeto primeiro e depois adicione uma entrada como a seguinte à configuração do seu cliente MCP. Substitua /absolute/path/to/Ackrite pelo diretório que contém este repositório.
{
"mcpServers": {
"ackrite": {
"command": "node",
"args": ["/absolute/path/to/Ackrite/dist/index.js"]
}
}
}
Se o seu cliente suporta executar scripts de pacote, o comando equivalente é node dist/index.js com o repositório como diretório de trabalho. Ackrite não aceita credenciais e não faz chamadas de rede na v0.1.
Ferramentas disponíveis
Todas as cinco ferramentas são declaradas somente leitura e retornam tanto texto JSON legível quanto conteúdo estruturado. Elas aceitam um sessionId opcional; use o mesmo valor durante uma investigação relacionada para reter histórico limitado dentro do processo em execução.
| Ferramenta | Use quando | Resultado principal |
|---|---|---|
ackrite | Um agente faz uma afirmação técnica e precisa ser desafiado. | Status, confiança, evidências de apoio e contraditórias, suposições, provas ausentes e próxima ação. |
verify | Você precisa de um registro de evidências estruturado para uma afirmação. | O que é conhecido, assumido, contradito, ausente e o experimento decisivo. |
audit | Uma alteração de código ou plano de implementação é proposto. | Descobertas concisas sobre reescritas desnecessárias, escopo, suposições de contrato de API, trabalho sensível à segurança, detalhes de tratamento de erros e testes. |
prove_it | Você quer a evidência mínima necessária para estabelecer uma afirmação. | Uma lista de verificação de prova específica do domínio da afirmação e um experimento falseável. |
reality_check | Um agente pode estar travado, repetindo-se ou reivindicando sucesso cedo demais. | A falha de raciocínio mais importante primeiro, além de riscos adicionais observados. |
Entrada de evidência compartilhada
Passe evidências explicitamente em vez de incorporá-las em contexto não estruturado. context pode fornecer contexto, mas não é contado como prova.
{
"type": "http_response",
"source": "staging request, 2026-08-27",
"content": "POST /v1/session returned 401 with code AUTH_REQUIRED.",
"polarity": "contradicts",
"reliability": 0.9
}
| Campo | Obrigatório | Descrição |
|---|---|---|
type | Não | Um de code, log, http_request, http_response, test_result, documentation, observed_behavior, user_fact, inference ou other. |
source | Não | Um rótulo de proveniência conciso, como um nome de teste, fonte de log ou localização de código. |
content | Sim | A observação, trecho, resultado ou inferência fornecida. |
polarity | Não | supports, contradicts ou neutral; o padrão é neutral para evitar suposições. |
reliability | Não | Número avaliado pelo chamador de 0 a 1; o padrão é 0.7. |
Exemplos de interação
Desafiar uma afirmação de API sem suporte
Afirmação: "A API não suporta mais autenticação nativa."
{
"claim": "The API no longer supports native authentication.",
"evidence": [
{
"type": "code",
"source": "current client",
"content": "The current client implementation does not obtain credentials.",
"polarity": "supports"
},
{
"type": "observed_behavior",
"source": "older working application",
"content": "The older application successfully signs in.",
"polarity": "contradicts",
"reliability": 0.9
}
]
}
Ackrite responde com CONTRADICTED, preserva ambas as proveniências e recomenda inspecionar o fluxo de autenticação mais antigo antes de substituir o cliente. Ele não conclui que a autenticação nativa existe ou que o fluxo antigo é aplicável; isso excederia a evidência fornecida.
Auditar uma proposta de reescrita
{
"reportedProblem": "Login returns an unexpected response.",
"proposal": "Rewrite the authentication client to replace the API endpoint integration.",
"proposedChanges": [
{
"path": "src/auth.ts",
"description": "Rewrite authentication client and route handling."
},
{
"path": "src/theme.ts",
"description": "Change unrelated color palette."
}
]
}
A auditoria destaca o limiar de evidência mais alto da reescrita, a suposição de contrato de API sem suporte, o plano de teste ausente e a mudança de tema aparentemente não relacionada. Ela não afirma ter inspecionado src/auth.ts ou src/theme.ts a menos que seus conteúdos sejam fornecidos como evidência.
Quebrar um loop de falha repetida
{
"sessionId": "auth-investigation",
"reasoning": "The rewrite will work and the issue is fixed.",
"attempts": [
{ "approach": "Replace the auth client", "outcome": "Failed with timeout." },
{ "approach": "Replace the auth client", "outcome": "Failed with timeout again." },
{ "approach": "Replace the auth client", "outcome": "Failed with the same timeout." }
]
}
O problema principal é uma estratégia repetida. Ackrite recomenda parar, identificar a suposição que torna a substituição aparentemente necessária e verificar essa suposição em vez de tentar a mesma intervenção novamente.
Modelo de confiabilidade e segurança
Ackrite é intencionalmente conservador. Ele não realiza varredura de repositório, solicitações HTTP, consulta de documentação externa, execução de código ou reparo autônomo na v0.1. Cada conclusão inclui proveniência que a limita ao material fornecido pelo chamador. Evidência ausente é um resultado, não um erro a esconder.
O servidor remove padrões comuns de credenciais antes de retornar texto de diagnóstico, incluindo valores de autorização bearer/basic, atribuições semelhantes a senhas, prefixos de token comuns, chaves de query-string e campos de chave de API. Isso é defesa em profundidade—não permissão para enviar segredos reais. Não envie credenciais de produção para ferramentas de diagnóstico.
O armazenamento de sessão é local ao processo e limitado: ele retém afirmações recentes, evidências, tentativas, conclusões e suposições não resolvidas para até 32 sessões nomeadas. Cada coleção por sessão é limitada, sessões menos recentemente usadas são removidas e todo o histórico é perdido quando o processo termina. Isso mantém a v0.1 útil para uma investigação focada sem se tornar uma plataforma de memória.
Desenvolvimento
| Comando | Propósito |
|---|---|
npm install | Instala dependências de desenvolvimento e runtime. |
npm run build | Compila TypeScript em dist/. |
npm run check | Executa verificação estrita de TypeScript sem gerar saída. |
npm test | Compila, executa testes unitários, exercita a descoberta de ferramentas MCP e invoca cada ferramenta através de um subprocesso stdio real. |
npm start | Inicia Ackrite compilado via stdio. |
npm run dev | Observa fontes TypeScript durante o desenvolvimento. |
A suíte de testes inclui cobertura positiva e negativa para classificação de afirmações, evidências contraditórias, afirmações sem suporte, remoção de segredos, estado limitado, cada ferramenta principal, falhas repetidas, inicialização do servidor, descoberta de ferramentas e chamadas de ferramentas através do protocolo MCP.
Limitações
A análise de Ackrite é determinística e orientada por evidências, em vez de um sistema completo de raciocínio autônomo. A ferramenta audit revisa descrições de uma proposta; não é um analisador estático e não inspeciona uma árvore de trabalho. A detecção de estratégia repetida usa termos normalizados das descrições de tentativas fornecidas, então tentativas semanticamente idênticas mas com palavras muito diferentes podem não ser agrupadas. As regras de remoção de segredos cobrem padrões comuns, mas não podem reconhecer todo formato de credencial proprietário.
Ackrite usa apenas stdio na v0.1. Ele é projetado para permanecer independente de L-Dopa e outros servidores MCP. Um futuro transporte HTTP, camada de persistência ou adaptador ciente de repositório deve permanecer opcional e deve preservar as mesmas garantias de não-fabricação e remoção de segredos.
Licença
Ackrite é lançado sob a Licença MIT.