Ackrite

Ackrite

ACKRITE. PROVE IT.

An MCP server that makes AI agents prove their assumptions before acting on them.

Ackrite is a focused verification utility for AI agents. It does not attempt to solve every problem, browse for convenient answers, or invent corroboration. Instead, it challenges an agent’s technical claim using only the evidence supplied to it, distinguishes facts from hypotheses, identifies missing proof, and recommends the smallest next check that can settle the question.

Its purpose is to prevent a familiar failure mode: an agent sees an error, assumes the cause, confidently rewrites half the system, and only then discovers the assumption was wrong. Ackrite pushes the agent toward evidence, targeted experiments, scoped changes, and explicit uncertainty.

Ackrite does	Ackrite does not
Classify claims from supplied evidence	Invent, fetch, or imply evidence it was not given
Detect contradictions and unsupported assumptions	Present an inference as a fact
Challenge rewrites and scope creep before implementation	Apply code changes or call external systems
Track a bounded, in-process verification history	Persist a large memory system or depend on L-Dopa
Redact common secrets from diagnostic output	Guarantee perfect secret detection for every custom credential format

Why it exists

An agent’s confidence is not evidence. A claim such as “the API removed native authentication” is often a useful hypothesis, but it becomes dangerous when it is treated as established fact and used to justify a rewrite. Ackrite asks four narrow questions:

1. What does the supplied evidence actually establish?
2. What contradicts the claim, if anything?
3. What assumption is doing the work?
4. What is the smallest empirical check to run next?

The result is deliberately concise enough to put directly back into an agent’s context window.

Claim statuses

Ackrite uses a deliberately conservative classification model.

Status	Meaning	Evidence threshold
KNOWN	Direct, high-reliability supplied evidence supports the claim.	At least one high-reliability direct item, such as a focused test result, HTTP response, observed behavior, or user-provided fact.
SUPPORTED	Direct supplied evidence supports the claim, but remains limited in scope or reliability.	Direct supporting evidence without a qualifying high-reliability item.
PLAUSIBLE	The claim may be true, but the material is indirect, neutral, or inferred.	Neutral evidence or inference only.
UNVERIFIED	No supplied supporting evidence establishes the claim.	No relevant evidence.
CONTRADICTED	At least one supplied evidence item contradicts the claim.	Contradiction takes precedence until it is reconciled.

Fundamental rule: Ackrite never upgrades an inference into a fact. It labels the boundary between observation and conclusion instead.

Architecture

Ackrite is intentionally small. The MCP boundary, domain analysis, evidence handling, and bounded state are separate so that the verification rules can be tested without a running MCP client.

Layer	Location	Responsibility
MCP transport and schemas	src/mcp/server.ts, src/index.ts	Registers five tools and serves them over standard input/output.
Tool orchestration	src/tools/verification-tools.ts	Produces agent-ready challenge, verification, audit, proof-plan, and reality-check responses.
Evidence model	src/core/evidence.ts	Normalizes provenance, reliability, polarity, excerpts, and secret redaction.
Claim analysis	src/core/claim-analysis.ts	Determines status, confidence, assumptions, missing proof, and next action.
Session history	src/core/state.ts	Maintains a bounded in-process record of claims, evidence, attempts, conclusions, and unresolved assumptions.
Tests	test/ackrite.test.mjs	Exercises the domain logic and real MCP stdio client/server behavior.

Ackrite is implemented in TypeScript using the official MCP TypeScript server and client packages. It exposes a stdio server: a client starts Ackrite as a subprocess and exchanges JSON-RPC messages through standard input and output, which is a standard MCP transport. [1] [2]

Installation

Ackrite requires Node.js 20 or later.

git clone https://github.com/mshanghai570/Ackrite.git
cd Ackrite
npm install
npm run build

Start the server directly after building:

npm start

The process communicates over standard input/output, so it may appear idle when run in a terminal. That is expected: your MCP client supplies the requests. Keep normal logs off standard output; MCP stdio reserves it for protocol messages. [1]

MCP client setup

Build the project first, then add an entry like the following to your MCP client configuration. Replace /absolute/path/to/Ackrite with the directory containing this repository.

{
  "mcpServers": {
    "ackrite": {
      "command": "node",
      "args": ["/absolute/path/to/Ackrite/dist/index.js"]
    }
  }
}

If your client supports running package scripts, the equivalent command is node dist/index.js with the repository as its working directory. Ackrite accepts no credentials and makes no network calls in v0.1.

Available tools

All five tools are declared read-only and return both readable JSON text and structured content. They accept an optional sessionId; use the same value during a related investigation to retain bounded history within the running process.

Tool	Use it when	Primary result
ackrite	An agent makes a technical claim and needs to be challenged.	Status, confidence, supporting and contradicting evidence, assumptions, missing proof, and next action.
verify	You need a structured evidence ledger for a claim.	What is known, assumed, contradicted, missing, and the decisive experiment.
audit	A code change or implementation plan is proposed.	Concise findings for unnecessary rewrites, scope, API-contract assumptions, security-sensitive work, error handling detail, and tests.
prove_it	You want the minimum evidence needed to establish a claim.	A claim-domain-specific proof checklist and a falsifiable experiment.
reality_check	An agent may be stuck, repeating itself, or claiming success too early.	The most important reasoning failure first, plus additional observed risks.

Shared evidence input

Pass evidence explicitly rather than embedding it in unstructured context. context may provide background, but it is not counted as proof.

{
  "type": "http_response",
  "source": "staging request, 2026-08-27",
  "content": "POST /v1/session returned 401 with code AUTH_REQUIRED.",
  "polarity": "contradicts",
  "reliability": 0.9
}

Field	Required	Description
type	No	One of code, log, http_request, http_response, test_result, documentation, observed_behavior, user_fact, inference, or other.
source	No	A concise provenance label, such as a test name, log source, or code location.
content	Yes	The supplied observation, excerpt, result, or inference.
polarity	No	supports, contradicts, or neutral; defaults to neutral to avoid guessing.
reliability	No	Caller-assessed number from 0 to 1; defaults to 0.7.

Example interactions

Challenge an unsupported API claim

Claim: “The API no longer supports native authentication.”

{
  "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 responds with CONTRADICTED, preserves both pieces of provenance, and recommends inspecting the older authentication flow before replacing the client. It does not conclude that native authentication exists or that the old flow is applicable; that would exceed the supplied evidence.

Audit a rewrite proposal

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

The audit calls out the rewrite’s higher evidence bar, the unsupported API-contract assumption, missing test plan, and the apparently unrelated theme change. It does not claim to have inspected src/auth.ts or src/theme.ts unless their contents are supplied as evidence.

Break a repeated failure loop

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

The primary issue is a repeated strategy. Ackrite recommends stopping, identifying the assumption that makes the replacement seem necessary, and verifying that assumption rather than attempting the same intervention again.

Reliability and security model

Ackrite is intentionally conservative. It performs no repository scanning, HTTP requests, external documentation lookup, code execution, or autonomous repair in v0.1. Every conclusion includes provenance that limits it to caller-supplied material. Missing evidence is a result, not an error to hide.

The server redacts common credential patterns before returning diagnostic text, including bearer/basic authorization values, password-like assignments, common token prefixes, query-string keys, and API-key fields. This is defense in depth—not permission to send real secrets. Do not submit production credentials to diagnostic tools.

The session store is process-local and bounded: it retains recent claims, evidence, attempts, conclusions, and unresolved assumptions for up to 32 named sessions. Each per-session collection is capped, least-recently-used sessions are evicted, and all history is lost when the process exits. This keeps v0.1 useful for a focused investigation without becoming a memory platform.

Development

Command	Purpose
npm install	Install development and runtime dependencies.
npm run build	Compile TypeScript into dist/.
npm run check	Run strict TypeScript checking without generating output.
npm test	Build, run unit tests, exercise MCP tool discovery, and invoke every tool over a real stdio subprocess.
npm start	Start compiled Ackrite over stdio.
npm run dev	Watch TypeScript sources during development.

The test suite includes positive and negative coverage for claim classification, contradictory evidence, unsupported claims, redaction, bounded state, each core tool, repeated failures, server startup, tool discovery, and tool calls through the MCP protocol.

Limitations

Ackrite’s analysis is deterministic and evidence-driven rather than a full autonomous reasoning system. The audit tool reviews descriptions of a proposal; it is not a static analyzer and does not inspect a working tree. Repeated-strategy detection uses normalized terms from supplied attempt descriptions, so semantically identical but very differently worded attempts may not be grouped. The secret-redaction rules cover common patterns but cannot recognize every proprietary credential format.

Ackrite uses stdio only in v0.1. It is designed to remain independent of L-Dopa and other MCP servers. A future HTTP transport, persistence layer, or repository-aware adapter should remain opt-in and must preserve the same no-fabrication and redaction guarantees.

License

Ackrite is released under the MIT License.

References

[1] Model Context Protocol — Transports

[2] Official Model Context Protocol TypeScript SDK