# mcp-ai-detection

Open-source MIT MCP server for multi-tier AI-detection screening on academic
papers. It accepts `.tex` and `.docx`, extracts clean text, splits standard
paper sections, and runs a three-tier risk pipeline.

AI detection is screening, not proof. Reports include limits, threats to
validity, and a final recommendation framed as decision support.

## Features

- MCP tools: `extract_text`, `split_sections`, `full_pipeline`
- Input: LaTeX `.tex` and Word `.docx`
- Text extraction: Pandoc for LaTeX when installed, robust fallback cleaner,
  `python-docx` for Word
- Narrative/structured split: tables, formulas, captions, references,
  keyword lines, markdown tables, and dense math lines are excluded from the
  main authorship score
- Section splitting: Abstract, Introduction, Methods, Results, Discussion,
  Conclusion
- Tier 1 offline: burstiness, lexical diversity, AI-like connectives,
  n-gram repetition, sentence-length variance, repeated patterns, hedging,
  example density
- Optional Tier 1 local LLM through Ollama with `gemma4:e4b` by default
- Tier 2 local Gemma adjudicator through Ollama: rubric-based JSON screening
  calibrated with Tier 1 metrics, no paid API keys
- Tier 3 open-source ensemble hooks: DetectGPT, Fast-DetectGPT, NPR command
  adapters plus built-in proxy analysis for repetition, lexical diversity,
  and semantic coherence
- JSON and Markdown reports with executive summary, section breakdown,
  section x tier score table, narrative score, structured-content diagnostic,
  limits, and recommendation

## Install

```bash
python -m pip install -e .
```

Pandoc is optional but recommended for LaTeX:

```bash
# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc
```

## MCP server

Run with stdio transport:

```bash
python -m mcp_ai_detection.server
```

Example MCP client config:

```json
{
  "mcpServers": {
    "ai-detection": {
      "command": "python",
      "args": ["-m", "mcp_ai_detection.server"],
      "env": {
        "LOCAL_LLM_MODEL": "gemma4:e4b"
      }
    }
  }
}
```

## Tools

### `extract_text`

```json
{
  "file_path": "paper.tex",
  "prefer_pandoc": true
}
```

Returns clean text, word count, extractor used, and warnings.

### `split_sections`

```json
{
  "text": "Abstract\n...\nIntroduction\n..."
}
```

Returns detected standard sections with line ranges and word counts.

### `full_pipeline`

```json
{
  "file_path": "paper.docx",
  "use_llm": false,
  "tier2_provider": "gemma-local",
  "early_stop": true
}
```

Runs extraction, sectioning, Tier 1 statistics, conditional Tier 2 Gemma/Ollama,
conditional Tier 3, then returns `report_json` and `report_markdown`.

## CLI

```bash
python -m mcp_ai_detection.cli paper.tex --markdown report.md --json report.json
```

## Configuration

Environment variables:

```bash
LOCAL_LLM_MODEL=gemma4:e4b
OLLAMA_HOST=http://localhost:11434
OLLAMA_KEEP_ALIVE=30m
HTTP_TIMEOUT_SECONDS=120
TIER1_LLM_WEIGHT=0.6
TIER1_STATS_WEIGHT=0.4

DETECTGPT_CMD=
FAST_DETECTGPT_CMD=
NPR_CMD=
METHODS_WEIGHT_REDUCTION=0.75
```

Tier 2 uses the local Ollama model named by `LOCAL_LLM_MODEL`. Recommended:

```bash
ollama pull gemma4:e4b
ollama serve
```

Check that Ollama is using the GPU:

```bash
ollama ps
```

The `PROCESSOR` column should show `100% GPU` for loaded models.

External Tier 3 commands receive section text on stdin and should return JSON:

```json
{
  "score": 0.72,
  "confidence": 0.64,
  "details": {
    "model": "your-detector"
  }
}
```

If commands are not configured, built-in proxy scorers keep the pipeline fully
offline and deterministic.

## Thresholds

- `< 0.3`: low
- `0.3-0.6`: medium
- `>= 0.6`: high
- Tier 2 early stop: probability `< 0.4`
- Sections below 80 narrative words are marked `insufficient_evidence` and are
  excluded from the document-level narrative score

Methods sections get reduced Tier 3 weight by default to lower false positives
from formulaic scientific prose.

## Development

Run offline tests:

```bash
python -m unittest discover -s tests
```

Run lint if dev extras are installed:

```bash
ruff check .
```

`gemma3:4b` is a smaller fallback for slower machines:

```bash
LOCAL_LLM_MODEL=gemma3:4b
```