ACG Mcp

Servidor MCP independiente para el Protocolo de Generación de Contexto Auditado (ACG): verificación de hechos verificable y RAG fundamentado a través de MongoDB.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor ACG MCP

Servidor MCP independiente para el Protocolo de Generación de Contexto Auditado (ACG) — verificación de hechos comprobable y RAG fundamentado vía MongoDB.

ACG proporciona un estándar de doble capa para el aseguramiento de la veracidad:

UGVP (Capa 1): Fundamentación de hechos atómicos con Marcadores de Afirmación e Identidad de Hash de Fuente (SHI)
RSVP (Capa 2): Verificación de síntesis lógica con Marcadores de Relación

Por qué ACG — qué puedes hacer con él

Los LLM afirman con confianza cosas que son incorrectas, y generalmente no hay forma de verificarlas — la respuesta es una caja negra sin procedencia. ACG soluciona esto haciendo que cada respuesta sea auditable por construcción:

Fundamenta cada hecho en su fuente. Indexa una URL una vez y cada respuesta posterior construida a partir de ella lleva Marcadores de Afirmación en línea como [C1:9f7a2c4d8e1b:css=#acg-chunk-aa-0] — el prefijo SHI basado en SHA-256 identifica el documento fuente exacto, y el selector CSS apunta al fragmento preciso dentro de él.
Verifica en lugar de confiar. acg_verify_claims vuelve a obtener cada fuente y compara difusamente cada afirmación contra el texto real, por lo que la verificación no es una opinión auto-reportada del LLM — es una comprobación independiente y repetible. Una afirmación o existe en la fuente citada o falla.
Sabe cuándo la base de conocimiento es suficiente. acg_check_indexed devuelve una puntuación de confianza (ALTA / MEDIA / BAJA) antes de acceder a la red, por lo que solo obtienes nuevas páginas cuando el índice genuinamente no puede responder.
Obtén un rastro de auditoría legible por máquina. acg_build_var emite un Registro de Auditoría de Veracidad (entradas SSR + RAR) — un registro JSON de cada afirmación, su huella de fuente, y cada relación lógica entre afirmaciones, listo para ser consumido por sistemas posteriores o humanos.
Úsalo en dos modos. Ejecuta el flujo de trabajo forzado (acg_run_workflow) y obtén una respuesta completa, verificada y auditada en una sola llamada — o compón las herramientas individuales como tu propio flujo de trabajo requiera (ver Dos formas de usar ACG).

En resumen: ACG convierte "confía en mí, el modelo lo dijo" en "aquí está la afirmación, aquí está la ubicación exacta de la fuente, aquí está el resultado de la verificación, y aquí está el registro de auditoría."

Características

Flujo de trabajo forzado → Una llamada ejecuta todo el pipeline: búsqueda, auto-indexado, fundamentación, verificación, auditoría (ver Dos formas de usar ACG)
Indexar URLs → Extrae texto, divide en oraciones, genera embeddings, almacena en MongoDB
Buscar Fuentes → Búsqueda semántica (vectorial) + por palabras clave en contenido indexado
Verificar Indexado → Búsqueda con puntuación de confianza para evitar llamadas web_fetch innecesarias
Generar Texto Fundamentado → Crea salida verificable con Marcadores de Afirmación en línea
Verificar Afirmaciones → Vuelve a obtener fuentes, compara difusamente afirmaciones contra el texto fuente
Construir VAR → Genera Registro de Auditoría de Veracidad legible por máquina (SSR + RAR)
Rastrear e Indexar → Descubrimiento de URLs BFS + pipeline automático de indexado ACG
Restablecer Base de Datos → Elimina todas las colecciones ACG (con guardia de confirmación)

Requisitos

Python 3.11+
Instancia de MongoDB (local o Atlas)
- Atlas Vector Search es opcional — recurre a búsqueda por palabras clave si no hay modelo de embeddings

Instalación

Requiere Python 3.11+. Un entorno virtual es altamente recomendado — en Debian/Ubuntu reciente (23.04+) y otras distribuciones PEP 668, pip install desnudo se niega a escribir en el Python del sistema, por lo que la Opción A es la ruta confiable allí.

Opción A: Entorno virtual + instalación editable (recomendada)

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 .

Esto instala el paquete y sus dependencias en el venv y coloca el comando acg-mcp en PATH mientras el venv esté activo. El modo editable significa que los cambios locales de código se aplican inmediatamente — sin necesidad de reinstalar.

Los clientes MCP no cargan tu shell, así que apúntalos al binario del venv por ruta absoluta en lugar de depender de PATH (ver Conectar desde un cliente MCP).

Opción B: Instalación a nivel de sistema (agentes / herramientas CLI)

Si quieres acg-mcp disponible en PATH desde cualquier directorio sin un venv:

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

Si pip falla con externally-managed-environment (PEP 668), usa un venv (Opción A) o agrega --break-system-packages.

Opción C: Ejecutar desde el código fuente (sin instalación)

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

Configuración

Copia .env.sample a .env y configura:

# 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

Ejecutar el servidor MCP (transporte stdio)

Después de instalar con la Opción A o B:

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

Sin instalar el CLI (solo directorio fuente):

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

Ejecutar el flujo de trabajo forzado desde el CLI

El CLI de una sola ejecución ejecuta todo el pipeline auditado sin un 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 desde un cliente MCP

El servidor se comunica a través de stdio. Claude Desktop y Opencode usan formatos de configuración diferentes, por lo que los ejemplos a continuación están divididos por cliente: Claude Desktop usa la clave mcpServers; Opencode usa una clave de nivel superior mcp donde cada servidor necesita "type" y command es un arreglo.

Claude Desktop

Claude Desktop lee claude_desktop_config.json y usa la clave mcpServers. Si instalaste con la Opción A (venv), apunta al binario del venv — los clientes no cargan tu shell:

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

Con una instalación a nivel de sistema (Opción B), el comando desnudo funciona directamente:

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

Opencode

Opencode lee opencode.json (o opencode.jsonc) y usa una clave de nivel superior mcp. Los servidores locales requieren "type": "local", command como un arreglo del binario + argumentos, y variables de entorno bajo "environment" (no "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://..."
      }
    }
  }
}

Con una instalación a nivel de sistema (Opción B), usa el comando desnudo:

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

Ejecutar desde el directorio fuente

Si no has instalado el CLI, usa la ruta completa. Claude Desktop:

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

Opencode — nota cwd para que src.server se resuelva relativo al proyecto:

{
  "$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: Al usar python -m src.server, ejecuta el cliente MCP desde la raíz del proyecto (/path/to/acg_mcp) o establece cwd en la configuración MCP.

Ubicaciones de configuración

Herramienta	Archivo de configuración	Alcance
Claude Desktop	`claude_desktop_config.json`	A nivel de usuario
Opencode	`~/.config/opencode/opencode.json`	A nivel de usuario (global)
Opencode	`opencode.json` / `opencode.jsonc` (raíz del proyecto)	Por proyecto (local)

Dos formas de usar ACG

ACG incluye tanto un flujo de trabajo forzado de extremo a extremo como las herramientas individuales de las que está construido. Usa el que se ajuste a tu tarea.

1. Flujo de trabajo forzado — todo el protocolo en una llamada

Llama a acg_run_workflow(query, url="") y el servidor ejecuta el pipeline completo por ti, en este orden:

búsqueda — busca en las fuentes indexadas la consulta
indexado — si la confianza es BAJA y se proporcionó un url, indexa primero, luego vuelve a buscar (auto-obtención)
fundamentación — compone una respuesta fundamentada con Marcadores de Afirmación UGVP en línea
verificación — vuelve a obtener cada fuente citada y compara difusamente cada afirmación
auditoría — construye el Registro de Auditoría de Veracidad (SSR + RAR)

El informe único devuelto contiene todo: la respuesta fundamentada, resultados de verificación por afirmación, una Tabla de Firmas de Fragmentos, y el pie de auditoría — [Claims Verified: x/y], [ACG Accuracy: N%], [ACG Signed: ACG Protocol]. Obtienes una respuesta verificable sin orquestar ninguno de los pasos tú mismo.

// 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. Herramientas individuales — adapta ACG a tu propio flujo de trabajo

Cada paso también está disponible como herramienta independiente, para que puedas componer exactamente el pipeline que tu flujo de trabajo necesite — división diferente, umbrales de verificación personalizados, tu propia estrategia de recuperación, o ACG usado puramente como capa de auditoría post-generación.

Herramienta	Cuándo usarla
`acg_index_url`	Tienes una URL y quieres que esté en la base de conocimiento
`acg_check_indexed`	Quieres saber si el índice puede responder antes de obtener cualquier cosa
`acg_search_sources`	Quieres fragmentos coincidentes crudos con puntuaciones, para construir tu propia respuesta
`acg_generate_grounded_text`	Tienes una respuesta y quieres adjuntarle Marcadores de Afirmación
`acg_verify_claims`	Tienes texto marcado y quieres una pasada de verificación independiente
`acg_build_var`	Quieres el registro de auditoría legible por máquina (SSR + RAR)
`acg_crawl_and_index`	Tienes un sitio de documentación y quieres indexarlo como un todo

Por ejemplo, un flujo de trabajo "solo verificación" que audita texto generado en otro lugar:

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

Uso desde otras herramientas y agentes

Una vez instalado con la Opción A (venv) o la Opción B (a nivel de sistema), cualquier herramienta o agente en la máquina puede usar acg-mcp referenciándolo en su configuración MCP. Agrégalo a la configuración global de Opencode del agente (~/.config/opencode/opencode.json) usando la sintaxis mcp de Opencode:

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

El agente puede entonces llamar a las herramientas ACG directamente:

acg_run_workflow() — Una llamada: respuesta completa verificada y auditada
acg_check_indexed() — Verifica si existen respuestas en fuentes indexadas
acg_index_url() — Indexa nuevas URLs
acg_verify_claims() — Verifica afirmaciones de texto fundamentado
acg_search_sources() — Busca en la base de conocimiento indexada

Pasar variables de entorno

Pasa MONGO_URI y otra configuración a través del campo env (Claude Desktop) o el campo environment (Opencode) en la configuración MCP. El servidor también carga .env desde el directorio del proyecto (vía python-dotenv) cuando se instala editable (pip install -e .) o se ejecuta desde la raíz del proyecto.

Herramientas disponibles

Herramienta	Descripción
`acg_run_workflow`	Pipeline forzado — búsqueda, auto-indexado, fundamentación, verificación, auditoría en una llamada
`acg_index_url`	Indexa una URL para ACG — obtiene, divide, embebe, almacena
`acg_check_indexed`	Verifica si una consulta tiene resultados en fuentes indexadas
`acg_search_sources`	Busca en fuentes indexadas por palabras clave
`acg_list_sources`	Lista todas las fuentes indexadas
`acg_count_sources`	Cuenta el total de fuentes indexadas
`acg_generate_grounded_text`	Crea texto con Marcadores de Afirmación (UGVP)
`acg_verify_claims`	Verifica afirmaciones contra sus fuentes (comparación difusa)
`acg_build_var`	Construye Registro de Auditoría de Veracidad (SSR + RAR)
`acg_crawl_and_index`	Rastrea + indexa múltiples URLs (soporte en segundo plano)
`acg_crawl_status`	Verifica el estado de tareas de rastreo en segundo plano
`acg_crawl_list_tasks`	Lista todas las tareas de rastreo en segundo plano
`acg_reset_database`	⚠️ Elimina todos los datos indexados (requiere confirm=true)

Colecciones de base de datos

El servidor usa una estructura estándar de colecciones MongoDB:

Colección	Propósito
`sources`	Metadatos de fuente (url, shi_prefix, url_hash, total_chunks)
`data`	Fragmentos con embeddings (source_id, text, sentences, embedding)
`claims`	Afirmaciones verificadas (claim_id, shi_prefix, claim_text, verified)
`relationships`	Registros de relación RSVP (rel_id, rel_type, claim_ids)
`var_entries`	Entradas del Registro de Auditoría de Veracidad

Los índices se crean automáticamente en la primera conexión.

Licencia

MIT