ACG Mcp

ACG MCP Server

Standalone MCP server for the Audited Context Generation (ACG) Protocol — verifiable fact-checking and grounded RAG via MongoDB.

ACG provides a dual-layer standard for veracity assurance:

• UGVP (Layer 1): Atomic fact grounding with Claim Markers and Source Hash Identity (SHI)
• RSVP (Layer 2): Logical synthesis verification with Relationship Markers

Why ACG — what you can do with it

LLMs confidently state things that are wrong, and there is usually no way to check — the answer is a black box with no provenance. ACG fixes this by making every answer auditable by construction:

• Ground every fact to its source. Index a URL once and every later answer built from it carries inline Claim Markers like [C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0] — the SHA-256-based SHI prefix fingerprints the exact source document, and the CSS selector points to the precise chunk inside it.

• Verify instead of trust. acg_verify_claims re-fetches every source and fuzzy-matches each claim against the actual text, so verification is not a self-reported LLM opinion — it is an independent, repeatable check. A claim either exists in the cited source or it fails.

• Know when the knowledge base is enough. acg_check_indexed returns a confidence score (HIGH / MEDIUM / LOW) before you ever hit the network, so you only fetch new pages when the index genuinely can't answer.

• Get a machine-readable audit trail. acg_build_var emits a Veracity Audit Registry (SSR + RAR entries) — a JSON record of every claim, its source fingerprint, and every logical relationship between claims, ready to be consumed by downstream systems or humans.

• Use it in two modes. Run the enforced workflow (acg_run_workflow) and get a complete, verified, audited answer in one call — or compose the individual tools any way your own workflow requires (see Two ways to use ACG).

In short: ACG turns "trust me, the model said so" into "here is the claim, here is the exact source location, here is the verification result, and here is the audit record."

Features

• Enforced workflow → One call runs the whole pipeline: search, auto-index, ground, verify, audit (see Two ways to use ACG)
• Index URLs → Extract text, chunk by sentences, generate embeddings, store in MongoDB
• Search Sources → Semantic (vector) + keyword search across indexed content
• Check Indexed → Confidence-scored lookup to avoid unnecessary web_fetch calls
• Generate Grounded Text → Create verifiable output with inline Claim Markers
• Verify Claims → Re-fetch sources, fuzzy-match claims against source text
• Build VAR → Generate machine-readable Veracity Audit Registry (SSR + RAR)
• Crawl & Index → BFS URL discovery + automatic ACG indexing pipeline
• Reset Database → Drop all ACG collections (with confirmation guard)

Requirements

• Python 3.11+
• MongoDB instance (local or Atlas)
  • Atlas Vector Search is optional — falls back to keyword search if no embedding model

Installation

Requires Python 3.11+. A virtual environment is strongly recommended — on recent Debian/Ubuntu (23.04+) and other PEP 668 distros, bare pip install refuses to write to the system Python, so Option A is the reliable path there.

Option A: Virtual environment + editable install (recommended)

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 .

This installs the package and its dependencies into the venv and puts the acg-mcp command on PATH while the venv is active. Editable mode means local code changes apply immediately — no reinstall needed.

MCP clients don't source your shell, so point them at the venv's binary by absolute path instead of relying on PATH (see Connect from an MCP client).

Option B: System-wide install (agents / CLI tools)

If you want acg-mcp available on PATH from any directory without a venv:

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

If pip fails with externally-managed-environment (PEP 668), either use a venv (Option A) or add --break-system-packages.

Option C: Run from source (no install)

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

Configuration

Copy .env.sample to .env and 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

For MongoDB Atlas:

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

Usage

Run the MCP server (stdio transport)

After installing with Option A or B:

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

Without installing the CLI (source directory only):

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

Run the enforced workflow from the CLI

The one-shot CLI runs the entire audited pipeline without an MCP client:

# 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

Connect from an MCP client

The server communicates over stdio. Claude Desktop and Opencode use different config formats, so the examples below are split per client: Claude Desktop uses the mcpServers key; Opencode uses a top-level mcp key where every server needs "type" and command is an array.

Claude Desktop

Claude Desktop reads claude_desktop_config.json and uses the mcpServers key. If you installed with Option A (venv), point at the venv binary — clients don't source your shell:

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

With a system-wide install (Option B), the bare command works directly:

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

Opencode

Opencode reads opencode.json (or opencode.jsonc) and uses a top-level mcp key. Local servers require "type": "local", command as an array of the binary + args, and env vars under "environment" (not "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://..."
      }
    }
  }
}

With a system-wide install (Option B), use the bare command:

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

Running from source directory

If you haven't installed the CLI, use the full path. Claude Desktop:

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

Opencode — note cwd so src.server resolves relative to the project:

{
  "$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://..."
      }
    }
  }
}

Important: When using python -m src.server, run the MCP client from the project root (/path/to/acg_mcp) or set cwd in the MCP config.

Config locations

Tool	Config File	Scope
Claude Desktop	claude_desktop_config.json	User-wide
Opencode	~/.config/opencode/opencode.json	User-wide (global)
Opencode	opencode.json / opencode.jsonc (project root)	Per-project (local)

Two ways to use ACG

ACG ships both an enforced end-to-end workflow and the individual tools it is built from. Use whichever fits your task.

1. Enforced workflow — the whole protocol in one call

Call acg_run_workflow(query, url="") and the server runs the full pipeline for you, in this order:

1. search — search the indexed sources for the query
2. index — if confidence is LOW and a url was provided, index it first, then re-search (auto-fetch)
3. ground — compose a grounded answer with inline UGVP Claim Markers
4. verify — re-fetch every cited source and fuzzy-match each claim
5. audit — build the Veracity Audit Registry (SSR + RAR)

The single returned report contains everything: the grounded answer, per-claim verification results, a Chunk Signatures Table, and the audit footer — [Claims Verified: x/y], [ACG Accuracy: N%], [ACG Signed: ACG Protocol]. You get a verifiable answer without orchestrating any of the steps yourself.

// 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. Individual tools — adapt ACG to your own workflow

Every step is also available as a standalone tool, so you can compose exactly the pipeline your workflow needs — different chunking, custom verification thresholds, your own retrieval strategy, or ACG used purely as a post-generation audit layer.

Tool	When to use it
acg_index_url	You have a URL and want it in the knowledge base
acg_check_indexed	You want to know if the index can answer before fetching anything
acg_search_sources	You want raw matching chunks with scores, to build your own answer
acg_generate_grounded_text	You have an answer and want to attach Claim Markers to it
acg_verify_claims	You have marked text and want an independent verification pass
acg_build_var	You want the machine-readable audit record (SSR + RAR)
acg_crawl_and_index	You have a docs site and want it indexed as a whole

For example, a "verify-only" workflow that audits text generated elsewhere:

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

Usage from other tools & agents

Once installed with Option A (venv) or Option B (system-wide), any tool or agent on the machine can use acg-mcp by referencing it in their MCP configuration. Add it to the agent's global Opencode config (~/.config/opencode/opencode.json) using Opencode's mcp syntax:

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

The agent can then call ACG tools directly:

• acg_run_workflow() — One call: full verified, audited answer
• acg_check_indexed() — Check if answers exist in indexed sources
• acg_index_url() — Index new URLs
• acg_verify_claims() — Verify grounded text claims
• acg_search_sources() — Search indexed knowledge base

Passing environment variables

Pass MONGO_URI and other config via the env field (Claude Desktop) or environment field (Opencode) in the MCP config. The server also loads .env from the project directory (via python-dotenv) when installed editable (pip install -e .) or run from the project root.

Available Tools

Tool	Description
acg_run_workflow	Enforced pipeline — search, auto-index, ground, verify, audit in one call
acg_index_url	Index a URL for ACG — fetches, chunks, embeds, stores
acg_check_indexed	Check if a query has results in indexed sources
acg_search_sources	Search indexed sources by keyword
acg_list_sources	List all indexed sources
acg_count_sources	Count total indexed sources
acg_generate_grounded_text	Create text with Claim Markers (UGVP)
acg_verify_claims	Verify claims against their sources (fuzzy matching)
acg_build_var	Build Veracity Audit Registry (SSR + RAR)
acg_crawl_and_index	Crawl + index multiple URLs (background support)
acg_crawl_status	Check background crawl task status
acg_crawl_list_tasks	List all background crawl tasks
acg_reset_database	⚠️ Delete all indexed data (requires confirm=true)

Database Collections

The server uses a standard MongoDB collection structure:

Collection	Purpose
sources	Source metadata (url, shi_prefix, url_hash, total_chunks)
data	Chunks with embeddings (source_id, text, sentences, embedding)
claims	Verified claims (claim_id, shi_prefix, claim_text, verified)
relationships	RSVP relationship records (rel_id, rel_type, claim_ids)
var_entries	Veracity Audit Registry entries

Indexes are auto-created on first connection.

License

MIT