# Fact-Checker MCP Server

[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides AI-powered fact-checking and claim verification. Uses Claude Haiku for claim extraction, SPO-based semantic fingerprinting, and Redis caching for deduplication.

Exposes both an MCP (StreamableHTTP) interface for AI agents and a REST API for HTTP clients.

## Features

### MCP Tools

| Tool            | Description                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| `extractClaims` | Extract verifiable claims from text with type and durability classification                                          |
| `verifyContent` | Verify outbound content — extracts claims, checks each against cache + Haiku, returns verdicts and corrected content |
| `verifySignal`  | Verify an inbound signal claim — returns a trust assessment with action recommendation                               |
| `getFactMemory` | Search the fact-checker cache for previously verified claims                                                         |

### REST API

| Method | Endpoint                     | Description                        |
| ------ | ---------------------------- | ---------------------------------- |
| POST   | `/api/extract-claims`        | Extract claims from text           |
| POST   | `/api/verify-content`        | Verify content (GATE tool)         |
| POST   | `/api/verify-signal`         | Verify a signal claim (SENSE tool) |
| GET    | `/api/fact-memory?query=...` | Search cached verifications        |
| GET    | `/health`                    | Health check                       |

## Quick Start

### Prerequisites

- Node.js 20+
- An [Anthropic API key](https://console.anthropic.com/)
- Redis (optional — caching is gracefully skipped when unavailable)

### Install from npm

```bash
npx -y @luminarylane/fact-checker-mcp
```

The command starts the server with Streamable HTTP on port `8005` by default.

### Install from source

```bash
git clone https://github.com/luminarylane/fact-checker-mcp.git
cd fact-checker-mcp
npm install
npm run build
```

### Configure

Copy the example env file and add your Anthropic API key:

```bash
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY
```

### Run

```bash
# Development (auto-reload)
npm run dev

# Production
npm start
```

The server starts two listeners:

- **REST API** on port 8004 (configurable via `PORT`)
- **MCP transport** on port 8005 (configurable via `MCP_PORT`)

### Connect an MCP client

Connect an MCP client to `http://localhost:8005/mcp` after starting the server.
The REST API is available on port `8004` by default. Configure both ports with
`MCP_PORT` and `PORT` if required.

## How It Works

### Claim Extraction (`extractClaims`)

Extracts verifiable claims from text using Claude Haiku. Each claim is classified by type (statistic, company_fact, quote, product_claim, market_assertion, opinion) and durability (permanent, durable, transient, volatile).

### Content Verification (`verifyContent` / GATE)

Full content verification pipeline:

1. Extract claims from content
2. Fingerprint each claim using SPO (Subject-Predicate-Object) triples
3. Check Redis cache for previously verified claims
4. Verify uncached claims via Claude Haiku with optional brand data and web context
5. Return verdicts (`publish`, `revise`, `block`) with corrected content

### Signal Verification (`verifySignal` / SENSE)

Verifies a single inbound claim (e.g., "Company X raised $50M") and returns:

- Signal verdict: `verified`, `likely_true`, `uncertain`, `likely_false`, `contradicted`
- Action recommendation: `safe_to_act`, `proceed_with_caution`, `needs_human_review`, `do_not_act`

### Semantic Fingerprinting

Claims are normalized into Subject-Predicate-Object triples via Haiku, then hashed. Equivalent claims (different wording, same meaning) produce the same fingerprint, enabling cache deduplication.

### Fact Memory (`getFactMemory`)

Search previously verified claims by keyword. Useful for avoiding re-verification during multi-step workflows.

## Configuration

| Env Var               | Default                     | Description                                             |
| --------------------- | --------------------------- | ------------------------------------------------------- |
| `ANTHROPIC_API_KEY`   | —                           | **Required.** Anthropic API key                         |
| `ANTHROPIC_MODEL`     | `claude-haiku-4-5-20251001` | Model to use for verification                           |
| `REDIS_URL`           | —                           | Redis connection URL (optional)                         |
| `PORT`                | `8004`                      | REST API port                                           |
| `MCP_PORT`            | `8005`                      | MCP transport port                                      |
| `HOST`                | `0.0.0.0`                   | Bind address                                            |
| `CACHE_TTL_PERMANENT` | `-1`                        | Cache TTL for permanent facts (seconds, -1 = no expiry) |
| `CACHE_TTL_DURABLE`   | `2592000`                   | Cache TTL for durable facts (30 days)                   |
| `CACHE_TTL_TRANSIENT` | `86400`                     | Cache TTL for transient facts (1 day)                   |
| `CACHE_TTL_VOLATILE`  | `3600`                      | Cache TTL for volatile facts (1 hour)                   |

## Architecture

- **Transport**: StreamableHTTP (MCP) + Express (REST)
- **AI**: Claude Haiku for claim extraction, verification, and SPO fingerprinting
- **Cache**: Redis with durability-based TTLs (gracefully degrades without Redis)
- **Rate Limiting**: Token-bucket rate limiter for Anthropic API calls (100 req/min)
- **Safety**: Untrusted content wrapped with hashed markers for prompt injection defence

## Development

```bash
# Development server (auto-reload)
npm run dev

# Type check
npx tsc --noEmit

# Run tests
npm test

# Test with coverage
npm run test:coverage

# Build
npm run build
```

## License

[MIT](LICENSE)