Metadata-Version: 2.5
Name: is-it-ai-mcp
Version: 0.1.0
Summary: MCP server that reads C2PA Content Credentials: what an image declares about its own origin, and whether that declaration still verifies
Project-URL: Homepage, https://github.com/JohannsenLum/is-it-ai-mcp
Project-URL: Repository, https://github.com/JohannsenLum/is-it-ai-mcp
Project-URL: Issues, https://github.com/JohannsenLum/is-it-ai-mcp/issues
Project-URL: Changelog, https://github.com/JohannsenLum/is-it-ai-mcp/releases
License: MIT
License-File: LICENSE
Keywords: ai-detection,c2pa,claude,content-authenticity,content-credentials,mcp,model-context-protocol,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: c2pa-python>=0.37
Requires-Dist: fastmcp>=3.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.JohannsenLum/is-it-ai-mcp -->

# is-it-ai-mcp

<h2 align="center">Read the file's own claim about itself, and check whether that claim still holds.</h2>

<p align="center">
  An image can carry a signed Content Credential declaring how it was made.<br>
  This server reads it, checks the signature against the bytes, and hands both<br>
  back to your AI assistant, which cannot see either on its own.
</p>

An MCP server that reads the C2PA Content Credential embedded in an image and reports
what the file declares about its own origin, plus whether that declaration still
verifies against the bytes in front of you.

[![PyPI](https://img.shields.io/pypi/v/is-it-ai-mcp)](https://pypi.org/project/is-it-ai-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/JohannsenLum/is-it-ai-mcp/blob/main/LICENSE)

## What it does

It opens an image, looks for an embedded C2PA manifest (a Content Credential), and if
one exists, reports two separate things: what the manifest claims about how the image
was made, and whether the cryptographic signature over that manifest still matches the
file's current bytes. It does not look at pixels and it does not guess. If there is no
manifest, or the manifest exists but the signature is broken, it says so plainly instead
of inventing an answer.

See [docs/pass-fail.md](docs/pass-fail.md) for why "the signature verified" and "the
claim is true" are two different questions, and why this server only ever answers the
first one.

## Install

### Running the server

`is-it-ai-mcp` is published on PyPI. Run it with:

```bash
uvx is-it-ai-mcp
```

**Install from source (contributors / unreleased `main`).** Not part of the normal
install path above, only needed if you want the latest unreleased code instead of the
published PyPI release:

```bash
uvx --from git+https://github.com/JohannsenLum/is-it-ai-mcp is-it-ai-mcp
```

Or run from a local clone:

```bash
git clone https://github.com/JohannsenLum/is-it-ai-mcp
cd is-it-ai-mcp
uv sync
```

No account, API key, or environment variable is required. The server only reads local
files you point it at.

### Claude Code and Claude Desktop

<a id="config-claude-code"></a>
<details>
<summary><strong>Claude Code</strong>: <code>~/.claude.json</code></summary>

```jsonc
{
  "mcpServers": {
    "is-it-ai": {
      "command": "uvx",
      "args": ["is-it-ai-mcp"]
    }
  }
}
```

</details>

<a id="config-claude-desktop"></a>
<details>
<summary><strong>Claude Desktop</strong>: <code>claude_desktop_config.json</code></summary>

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Copy this JSON in via **Settings → Developer → Edit Config**:

```jsonc
{
  "mcpServers": {
    "is-it-ai": {
      "command": "uvx",
      "args": ["is-it-ai-mcp"]
    }
  }
}
```
</details>

## Tools

### `check_image_provenance`

Give it the path to one image file on disk. It returns:

- **`verdict`**: one of the three states below (`AI_DECLARED`, `NO_AI_DECLARED`,
  `UNKNOWN`).
- **`reason`**: the specific basis for that verdict, for example `no-credential`,
  `credential-invalid`, `ai-source-type`, `capture-source-type`, or
  `credential-silent`.
- **`what_this_does_not_mean`**: a plain-language caveat attached to every verdict, so
  the result cannot be quietly upgraded into a stronger claim than the evidence
  supports.
- **`signature`**: the raw `validation_state`, a `verified` boolean, and any
  `failure_codes` the signature check produced.
- **`declared`**: what the manifest claims when one exists. `signer`, `claim_generator`,
  and `signed_at` are free text pulled straight from the file, so each is guarded per
  the Security section below before it reaches you. `source_types` (IPTC
  digital-source-type URIs, drawn from a closed vocabulary) and `watermark_declared` (a
  boolean) cannot carry attacker-authored text, so both are returned as-is and are
  never fenced.

A file that cannot be read (bad path, unsupported format) comes back as a distinct
error result rather than a fake `UNKNOWN`. It needs a real path on disk, not the image
bytes themselves. See [Note on file paths](#note-on-file-paths).

### `scan_directory`

Give it a folder. It walks the tree, runs every image it finds through the same check,
and returns aggregate counts by verdict and by signer, plus a capped sample of the
files that carried a credential, rather than a line per file. This is the tool that
reproduces this project's own 401-image sweep (see below) against any directory you
point it at.

## The three verdicts

| Verdict | Means | Reachable only when |
|---|---|---|
| `AI_DECLARED` | The file's manifest asserts AI or algorithmic generation | A manifest is present, its signature verifies, and it carries an IPTC digital-source-type marking AI involvement |
| `NO_AI_DECLARED` | The file's manifest asserts a real-world capture | A manifest is present, its signature verifies, and it carries an IPTC digital-source-type marking a capture (camera, film, print, minor edits) |
| `UNKNOWN` | Nothing usable was established | Everything else, including no manifest, a broken signature, or a manifest that never recorded a source type |

**`UNKNOWN` is the default and by far the most common answer.** In a scan of 401 real
images, only 14 carried a Content Credential at all, and every one of those was from
OpenAI: about 96.5% had no credential whatsoever. Expect `UNKNOWN` on almost everything
you check. That is not a bug in this server, it is the current state of image
provenance in the wild.

## What this cannot tell you

- **It does not detect AI from pixels.** There is no image analysis here at all, no
  model looking at the picture. Every verdict comes from a cryptographically signed
  text record, or from the absence of one.
- **A missing credential is not evidence of anything.** An unmarked AI image and an
  unmarked photograph are indistinguishable to this tool. Screenshotting, re-saving, or
  passing an image through almost any editor strips the credential, AI-made or not.
  `UNKNOWN` means "no usable record survived," never "no AI was involved."
- **A valid signature does not make the signer's claims true.** The signature proves
  the manifest has not been altered since it was signed and confirms who signed it. It
  proves nothing about whether the signer told the truth. Anyone can generate their own
  certificate, sign their own file, and assert whatever origin they like: it will
  verify perfectly and still be false. Verification is about the seal, not the letter.
  See [docs/pass-fail.md](docs/pass-fail.md).

## Why it exists

When you attach an image to a model, the image is decoded to pixels and re-encoded
before the model ever sees it. Container metadata, including any C2PA manifest, never
reaches the model: the model sees an RGB array, nothing more. Without a tool, it cannot
read a manifest at all, and it will tend to guess whether an image is AI-generated from
visual artefacts instead. Published benchmarks put that guess at roughly 18 to 31%
accuracy, little better than chance. This server exists so the model reads the actual
signed record on disk instead of pattern-matching on JPEG compression artefacts.

## Security

Every human-readable string returned by this server originated inside the file being
inspected: signer name, claim-generator string, and any free-text reason or label. That
text was written by whoever produced the file, not by you, and it lands in the same
context window as your own instructions. A field labelled "signer" carries an air of
verified authority, but the signature covers the asset's bytes, not the honesty of any
string inside the manifest. Anyone can sign their own file with their own certificate
and write anything they like in it.

Before any such string is returned, it is cleaned of control characters, length-capped,
and wrapped in a fenced boundary that marks it explicitly as untrusted data rather than
instructions, with a random nonce the file's author could not have pre-guessed.
Structural values, the verdict itself, the validation state, and the IPTC source-type
URIs are drawn from closed vocabularies this server controls and are never fenced,
since they cannot carry attacker-authored text.

See [`src/is_it_ai_mcp/safety.py`](src/is_it_ai_mcp/safety.py) for the implementation
and the full threat model in its module docstring.

## Note on file paths

This tool takes a **file path**, not image bytes. In Claude Code, an image you paste
into the conversation is written to disk first, so its path is reachable and this just
works. In other clients, a pasted or attached image may exist only as inline data with
no path on the filesystem the server can reach, in which case there is nothing for
this tool to open. If a check comes back unable to find the file, save the image to
disk first and point the tool at that path.

## Development

```bash
uv sync --extra dev
uv run pytest -v
```

`--extra dev` matters: without it, `pytest-asyncio` (needed for `asyncio_mode = "auto"`
in `pyproject.toml`) is not installed, and pytest prints an "Unknown config option:
asyncio_mode" warning on every run.

Tests run against the fixtures in [`fixtures/`](fixtures/), a real signed image plus
tampered and stripped variants with hand-verified expected outcomes. See
[`fixtures/GROUND-TRUTH.md`](fixtures/GROUND-TRUTH.md) for how each was produced and
what each is expected to prove.

## Licence

[MIT](LICENSE) © 2026 Johannsen Lum.

Use it, change it, redistribute it, build something commercial on it: the only
condition is that you keep the copyright notice and licence text. It comes with no
warranty of any kind.

Contributions are accepted under the same licence.
