ClaimsMCP: Instructions file for Codex

AGENTS.md - Project Documentation for AI Agents

Project Overview

ClaimsMCP is a Model Context Protocol (MCP) server that implements the "Claimify" research methodology for extracting verifiable factual claims from text. This is a production-ready implementation using OpenAI's structured outputs API and follows the peer-reviewed approach from "Towards Effective Extraction and Evaluation of Factual Claims" by Metropolitansky & Larson (2025).

Key Insight: This is NOT just another text extraction tool. It implements a sophisticated 4-stage academic pipeline that filters out opinions, resolves ambiguities, and produces atomic, self-contained claims.

Architecture at a Glance

User Text → MCP Server → Pipeline → LLM Client → MCP Sampling (primary)
                            ↓                    ↓ (or fallback)
         [Splitting → Selection → Disambiguation → Decomposition]
                            ↓                    ↓
                    Structured Claims        OpenAI API

Core Components

1. claimify_server.py - MCP Server Entry Point

• Purpose: Exposes claim extraction as an MCP tool via stdio
• Protocol: Uses Model Context Protocol for client communication
• Tool: extract_claims(text_to_process, question) - the main interface
• Important: Uses stdio (stdin/stdout), NOT HTTP - this is intentional for MCP
• Async: Built on asyncio, runs single-threaded event loop

Key Implementation Details:

• Returns JSON array of claims as string
• Error handling wraps all exceptions
• Validates API keys on startup
• Logs to stderr (stdout reserved for MCP protocol)

2. pipeline.py - Core Extraction Logic

• Purpose: Orchestrates the 4-stage Claimify methodology
• Architecture: Each stage is a separate function with structured I/O

The 4 Stages:

1. Sentence Splitting (split_into_sentences)
   • Uses NLTK's punkt tokenizer
   • Handles paragraphs and list items
   • Maintains sentence boundaries accurately