Claimify

Extrae afirmaciones factuales de texto utilizando la metodología Claimify. Requiere una clave de API de OpenAI.

Documentación

Claimify: Extracción de Afirmaciones Basada en Investigación mediante MCP

Una implementación de la metodología "Claimify" para la extracción de afirmaciones fácticas, entregada como un servidor local del Protocolo de Contexto de Modelo (MCP). Esta herramienta implementa el enfoque de extracción de afirmaciones de múltiples etapas detallado en el artículo académico "Towards Effective Extraction and Evaluation of Factual Claims" de Metropolitansky & Larson (2025).

Lea el artículo aquí

Los prompts del artículo han sido modificados para su uso con Salidas Estructuradas. ESTO NO ES UNA IMPLEMENTACIÓN OFICIAL.

Descripción General

Claimify extrae afirmaciones fácticas verificables y descontextualizadas del texto utilizando un sofisticado pipeline de cuatro etapas:

División de Oraciones: Divide el texto en oraciones individuales con contexto circundante
Selección: Filtra oraciones que contienen proposiciones verificables, excluyendo opiniones y especulaciones
Desambiguación: Resuelve ambigüedades o descarta oraciones que no pueden aclararse
Descomposición: Descompone oraciones en afirmaciones fácticas atómicas y autocontenidas

La herramienta utiliza exclusivamente la función de salidas estructuradas de OpenAI para una mayor fiabilidad y expone su funcionalidad a través del Protocolo de Contexto de Modelo, poniéndola a disposición de clientes compatibles con MCP como Cursor y Claude Desktop.

Características

Metodología basada en investigación: Implementa el enfoque Claimify revisado por pares
Salidas estructuradas: Utiliza las salidas estructuradas de OpenAI para respuestas fiables y seguras de tipos
Integración MCP: Se integra sin problemas con entornos de desarrollo
Análisis robusto: Maneja varios formatos de texto, incluyendo listas y párrafos
Consciente del contexto: Utiliza oraciones circundantes para resolver ambigüedades
Soporte multilingüe: Conserva el idioma original mientras extrae afirmaciones
Almacenamiento de recursos: Almacena automáticamente las afirmaciones extraídas como recursos MCP para una fácil recuperación
Registro exhaustivo: Registro detallado de todas las llamadas al LLM, respuestas y etapas del pipeline
Listo para producción: Incluye manejo de errores, monitoreo y gestión de configuración

Requisitos

API de OpenAI: Requiere una clave de API de OpenAI (si su host MCP no admite muestreo (GitHub Copilot en vsCode sí lo admite))
Modelo Compatible: Debe usar un modelo que admita salidas estructuradas:
- gpt-4o (recomendado)
- gpt-4o-mini (más rápido y económico)
Python 3.10+: Para anotaciones de tipo adecuadas y soporte de Pydantic

Inicio Rápido

1. Instalación

# Clone the repository
git clone <repository-url>
cd ClaimsMCP

# Create and activate a virtual environment
python -m venv claimify-env
source claimify-env/bin/activate  # On Windows: claimify-env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download required NLTK data (done automatically on first run)
python -c "import nltk; nltk.download('punkt_tab')"

2. Configuración

Cree un archivo .env en la raíz del proyecto:

# Copy the example file
cp env.example .env

Edite .env y añada su clave de API:

# API Keys
OPENAI_API_KEY="your-openai-api-key-here"

# LLM Configuration
LLM_MODEL="gpt-4o-2024-08-06"  # Model that supports structured outputs

# Logging Configuration
LOG_LLM_CALLS="true"   # Set to "false" to disable logging
LOG_OUTPUT="stderr"    # "stderr" or "file" - where to send logs
LOG_FILE="claimify_llm.log"  # Used only if LOG_OUTPUT="file"

Configuración del Cliente MCP

Para Cursor

Abra Cursor y navegue a Configuración > MCP
Haga clic en "Añadir un Nuevo Servidor MCP Global"
Añada la siguiente configuración a su archivo de configuración MCP (generalmente ~/.cursor/mcp.json):

{
  "mcpServers": {
    "claimify-local": {
      "command": "/path/to/your/claimify-env/bin/python",
      "args": [
        "/path/to/your/project/claimify_server.py"
      ]
    }
  }
}

Reemplace las rutas con las rutas absolutas a su ejecutable de Python y al script del servidor

El "Servidor de Extracción Claimify" debería aparecer ahora como una herramienta conectada en su chat habilitado para MCP.

Ejemplos de Uso

Una vez configurado, puede usar la herramienta en su cliente MCP:

Uso de la Herramienta de Extracción de Afirmaciones

Uso de los Prompts

El servidor expone dos prompts para ayudar a verificar y documentar las afirmaciones extraídas:

1. Verificar una Afirmación Individual (`verify_claim`)

Proporciona un prompt preconstruido que instruye al LLM a verificar una única afirmación fáctica contra fuentes externas.

Argumentos:

claim_text (obligatorio): La afirmación fáctica descontextualizada a verificar.

Comportamiento:

Se instruye al LLM a buscar fuentes autorizadas (publicaciones académicas, medios de noticias de confianza, organizaciones oficiales).
Devuelve uno de tres estados:
- VERIFIED: La afirmación está claramente respaldada por fuentes confiables (proporciona al menos 3 referencias con URLs + justificación)
- UNCERTAIN: La afirmación puede ser correcta pero carece de precisión, tiene ambigüedad o evidencia limitada/contradictoria
- DISPUTED: La afirmación es demostrablemente falsa o está contradicha por fuentes confiables
Las fuentes no deben ser inventadas; se prefiere referencias primarias.

Ejemplo de recuperación (conceptual – la llamada real depende de la API del cliente):

get_prompt(name="verify_claim", arguments={"claim_text": "Python was first publicly released in 1991."})

Ejemplo de formato de respuesta esperado del LLM:

**Claim:** Python was first publicly released in 1991.

**Status:** IN_PROGRESS

[After research...]

**Claim:** Python was first publicly released in 1991.

**Status:** VERIFIED

**Evidence:**
- Source 1: [Python.org Release History](https://www.python.org/doc/versions/) - Official Python release history page confirms the initial public release year
- Source 2: [Computer History Museum](https://www.computerhistory.org/collections/catalog/102726710) - Archive referencing Python's early development
- Source 3: [Wikipedia - Python](https://en.wikipedia.org/wiki/Python_(programming_language)) - Encyclopedia entry citing original release year

Si es incierta:

**Claim:** Stockholm has 800,000 inhabitants.

**Status:** UNCERTAIN

**Evidence:**
- Source 1: [Statistics Sweden](https://www.scb.se/en/) - Reports varying population figures depending on whether measuring city proper, municipality, or metropolitan area

**Analysis:**
The claim lacks specificity about which definition of "Stockholm" is being referenced (city proper ~975k, municipality ~975k, or urban area ~1.6M as of 2023). The figure of 800,000 may have been accurate for certain definitions at specific time periods, but without temporal and geographic context, full verification is not possible.

Si está disputada:

**Claim:** The Earth is flat.

**Status:** DISPUTED

**Analysis:**
This claim contradicts overwhelming scientific evidence. The Earth's spherical shape has been confirmed by satellite imagery, space missions, and centuries of astronomical observations. Reliable sources universally reject this claim.

2. Crear Informe de Afirmaciones (`create_claims_report`)

Genera un archivo CLAIMS.md inicial con todas las afirmaciones marcadas como TODO. Las afirmaciones pueden verificarse luego de forma incremental, actualizando su estado a través del flujo de trabajo: TODO → IN_PROGRESS → VERIFIED/UNCERTAIN/DISPUTED.

Flujo de trabajo:

Creación Inicial: Todas las afirmaciones comienzan con estado TODO
Durante la Verificación: Actualizar afirmaciones individuales a IN_PROGRESS
Después de la Verificación: Actualizar a VERIFIED, UNCERTAIN o DISPUTED con evidencia

Argumentos:

Ninguno (adjunte el recurso de extracción al contexto en VS Code)

Comportamiento:

Analiza todas las afirmaciones del recurso de extracción adjunto en el contexto
Crea CLAIMS.md con todas las afirmaciones marcadas como TODO
Proporciona una estructura de plantilla lista para la verificación incremental

Ejemplo de uso: Al ver un recurso de extracción en VS Code, adjúntelo al contexto del prompt. El prompt generará un archivo CLAIMS.md inicial listo para la verificación.

Estructura inicial de CLAIMS.md:

# Claims Report

**Extraction ID:** extraction_1_1730678400
**Generated:** 2025-11-03
**Total Claims:** 5
**TODO:** 5
**In Progress:** 0
**Verified:** 0
**Uncertain:** 0
**Disputed:** 0

---

## Claims

### Claim 1
**Text:** Apple Inc. was founded in 1976.

**Status:** TODO

---

### Claim 2
**Text:** Steve Jobs co-founded Apple Inc.

**Status:** TODO

---
...

Después de las actualizaciones de verificación:

### Claim 1
**Text:** Apple Inc. was founded in 1976.

**Status:** VERIFIED

**Evidence:**
- Source 1: [Wikipedia - Apple Inc.](https://en.wikipedia.org/wiki/Apple_Inc.) - States company was founded in 1976
- Source 2: [Apple Official](https://www.apple.com/about/) - Corporate history confirms 1976 founding
- Source 3: [Britannica](https://www.britannica.com/topic/Apple-Inc) - Encyclopedia entry validates founding year

---

### Claim 2
**Text:** Stockholm has 800,000 inhabitants.

**Status:** UNCERTAIN

**Evidence:**
- Source 1: [Statistics Sweden](https://www.scb.se/en/) - Reports varying figures depending on definition

**Analysis:**
The claim lacks specificity about which geographic definition and time period. Population varies significantly between city proper (~975k), municipality (~975k), and metropolitan area (~1.6M) as of 2023. The 800k figure may have been accurate historically for certain definitions.

---

### Claim 3
**Text:** The company invented smartphones.

**Status:** DISPUTED

**Analysis:**
While Apple popularized smartphones with the iPhone in 2007, they did not invent smartphones. Earlier devices like the IBM Simon (1994) and BlackBerry devices (early 2000s) preceded the iPhone. The claim conflates innovation/popularization with invention.

---
...

Nota: El servidor solo proporciona los prompts; la búsqueda externa depende de las capacidades del cliente/modelo.

Ejemplo 1: Texto Fáctico Simple

Input: "The American flag contains 50 stars and 13 stripes."
Output: [
  "The American flag contains 50 stars [representing the 50 states] and 13 stripes [representing the original 13 colonies].",
  "The American flag was designed in 1777",
  "The American flag has been modified 27 times"
]

Ejemplo 2: Hecho y Opinión Mezclados

Input: "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne. The company is incredibly innovative and has the best products in the world."
Output: [
  "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne."
]

(Nota: El contenido subjetivo sobre ser "increíblemente innovador" y tener "los mejores productos" se filtra)

Ejemplo 3: Soporte Multilingüe

Input: "String-systemet är en prisbelönt ikon som kombinerar elegant och minimalistisk design med ett brett utbud av färger och storlekar. Nisse Strinning skapade första hyllan redan 1949."
Output: [
  "String-systemet [ett hyllsystem] är en prisbelönt ikon [inom design]",
  "String-systemet kombinerar elegant och minimalistisk design med ett brett utbud av färger och storlekar",
  "Nisse Strinning skapade den första String-hyllan [String-systemet] 1949"
]

(Nota: El contenido se conserva en sueco original, con aclaraciones contextuales añadidas entre corchetes)

Acceso a las Afirmaciones Extraídas como Recursos

Cada extracción genera dos tipos de recursos:

Recurso de Extracción Agregado (claim://extraction_<n>_<timestamp>)
- Contiene metadatos (marca de tiempo, vista previa, pregunta) y la lista completa de afirmaciones
- Devuelve formato JSON
Recursos de Afirmaciones Individuales (claim://<slug>)
- Cada afirmación es accesible mediante un slug único (identificador seguro para URL derivado del texto de la afirmación)
- Devuelve texto plano (la afirmación en sí)

Ejemplo JSON de Extracción Agregada

{
  "id": "extraction_1_1730678400",
  "timestamp": "2025-11-03T14:30:00.123456",
  "question": "What is the history of Apple?",
  "text_preview": "Apple Inc. was founded in 1976 by Steve Jobs...",
  "claims": [
    "Apple Inc. was founded in 1976 by Steve Jobs, Steve Wozniak, and Ronald Wayne."
  ],
  "claim_count": 1
}

URI: claim://apple-inc-was-founded-in-1976-by-steve-jobs

Ejemplos de Recursos de Afirmaciones Individuales

Patrón de URI: claim://<slug>

Ejemplos:

claim://apple-inc-was-founded-in-1976-by-steve-jobs-steve-wozniak-and-ronald
claim://stockholm-is-the-capital-of-sweden
claim://python-was-first-publicly-released-in-1991

Contenido: Texto plano de la afirmación (sin envoltorio JSON)

Beneficios de los recursos por afirmación:

Acceso directo: Recupere cualquier afirmación por su slug
Formato simple: Texto plano, sin necesidad de análisis
Identificadores únicos: Cada afirmación tiene una URI estable y legible
Citación fácil: Enlace directo a afirmaciones individuales

Estructura del Proyecto

ClaimsMCP/
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── env.example                  # Environment configuration template
├── claimify_server.py          # Main MCP server script
├── llm_client.py               # LLM client with structured outputs support
├── pipeline.py                 # Core claim extraction pipeline
├── structured_models.py        # Pydantic models for structured outputs
├── structured_prompts.py       # Optimized prompts for structured outputs
├── setup.py                    # Package setup configuration
├── test_claimify.py            # Test suite for the claim extraction pipeline
└── LICENSE                     # Apache 2.0 license

Arquitectura

El sistema sigue una arquitectura modular con salidas estructuradas:

Servidor MCP: Expone la extracción de afirmaciones como una herramienta a través del Protocolo de Contexto de Modelo
ClaimifyPipeline: Orquesta el proceso de extracción de múltiples etapas utilizando salidas estructuradas
LLMClient: Maneja la comunicación con la API de OpenAI utilizando salidas estructuradas y modelos Pydantic
Modelos Estructurados: Modelos Pydantic que definen el formato de respuesta esperado para cada etapa
Funciones de Etapa: Funciones individuales para Selección, Desambiguación y Descomposición
Gestión de Prompts: Prompts simplificados optimizados para salidas estructuradas

Beneficios de las Salidas Estructuradas

La implementación utiliza la función de salidas estructuradas de OpenAI, que proporciona:

Seguridad de Tipos: Las respuestas se validan automáticamente contra modelos Pydantic
Fiabilidad: No más fallos de análisis de expresiones regulares ni JSON malformado
Rechazos Explícitos: Los rechazos basados en seguridad son detectables programáticamente
Consistencia: Adherencia garantizada al esquema de respuesta esperado
Rendimiento: Menor necesidad de lógica de reintentos y manejo de errores

Opciones de Configuración

Variable de Entorno	Descripción	Predeterminado	Opciones
`LLM_MODEL`	Modelo específico a usar	`gpt-4o-2024-08-06`	Modelos que admiten salidas estructuradas
`OPENAI_API_KEY`	Clave de API de OpenAI	Ninguna	Su clave de API
`LOG_LLM_CALLS`	Habilitar registro detallado de todas las interacciones del LLM	`true`	`true`, `false`
`LOG_OUTPUT`	Dónde enviar la salida del registro	`stderr`	`stderr`, `file`
`LOG_FILE`	Nombre del archivo de registro (usado cuando LOG_OUTPUT=file)	`claimify_llm.log`	Cualquier nombre de archivo

Solución de Problemas

Problemas Comunes

Error "El modelo no admite salidas estructuradas"
- Asegúrese de usar un modelo compatible: gpt-4o-2024-08-06, gpt-4o-mini o gpt-4o
- Actualice su archivo .env: LLM_MODEL=gpt-4o-2024-08-06
Error "Clave de API no configurada"
- Asegúrese de que su archivo .env exista y contenga la clave de API de OpenAI correcta
- Verifique que la clave comience con sk-
"Tokenizador punkt de NLTK no encontrado"
- Ejecute: python -c "import nltk; nltk.download('punkt_tab')" o python -c "import nltk; nltk.download('punkt')"
El cliente MCP no puede conectarse
- Verifique que las rutas en su configuración MCP sean absolutas y correctas
- Asegúrese de que su entorno virtual de Python esté activado
- Verifique que el script del servidor sea ejecutable: chmod +x claimify_server.py
No se extrajeron afirmaciones
- Revise los registros para obtener información detallada sobre cada etapa del pipeline
- Asegúrese de que el texto de entrada contenga declaraciones fácticas verificables
- Pruebe primero con oraciones fácticas más simples y directas

Desarrollo

Para extender o modificar el sistema:

Añadir nuevos campos de respuesta: Actualice los modelos Pydantic en structured_models.py
Modificar prompts: Edite los prompts en structured_prompts.py
Añadir nuevas etapas: Cree nuevas funciones en pipeline.py siguiendo el patrón existente
Pruebas: Use el registro integrado para depurar el comportamiento del pipeline

El enfoque de salidas estructuradas hace que el sistema sea mucho más fiable y más fácil de depurar en comparación con los métodos tradicionales de análisis de texto.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 - consulte el archivo LICENSE para más detalles.

Referencias

Metropolitansky & Larson (2025). "Towards Effective Extraction and Evaluation of Factual Claims"

Soporte

Para problemas relacionados con:

Configuración e instalación: Consulte este README y la sección de solución de problemas
Integración MCP: Consulte la documentación del Protocolo de Contexto de Modelo
Metodología de investigación: Consulte el artículo original de Claimify