# `@filesniff/mcp` — Local File Inspection & Provenance MCP Server

`@filesniff/mcp` is a zero-dependency Node 22+ Model Context Protocol (MCP) server over `stdio`. It exposes the exact same bounded, local-only ES modules used by [File Sniff Online](https://www.filesniff.dev/tools/):

- **`assets/js/checker/detector.mjs`** — Magic-byte file identification and ZIP central-directory inspection (`sniff_file`)
- **`static/js/provenance/documents.mjs`** — Office `.docx`, `.xlsx`, and `.pptx` XML provenance, AI/automation clues, hidden worksheets, fonts, colours, and workflow hints (`inspect_office_document`)
- **`assets/js/image/container.mjs`** — Lossless container-level EXIF, GPS, XMP, IPTC, thumbnail, and trailer removal for JPEG, PNG, and WebP (`strip_image_metadata`)

---

## Requirements

- **Node.js 22+** (zero external npm packages required)

---

## Configuration

### Option 1: Remote Streamable HTTP MCP (Zero Install, Header-Only)

Connect any Streamable HTTP MCP client directly to `https://www.filesniff.dev/mcp` (or `https://www.filesniff.dev/api/mcp`):

```json
{
  "mcpServers": {
    "filesniff-remote": {
      "type": "http",
      "url": "https://www.filesniff.dev/mcp"
    }
  }
}
```

The remote endpoint enforces a strict 4 KiB request limit (max 512 sample bytes) so full files are never uploaded, and exposes:
- `identify_magic_bytes` — Identify a format and extension mismatch from up to 512 leading bytes in hex or base64.
- `lookup_file_format` — Look up magic-byte signatures, MIME types, and File Sniff browser tools/guides for any format or extension.
- `explain_provenance_marker` — Explain IPTC `DigitalSourceType` values (`trainedAlgorithmicMedia`, `compositeWithTrainedAlgorithmicMedia`, `algorithmicallyEnhanced`) and C2PA Content Credentials.

### Option 2: Local `stdio` MCP (Full Local Disk Inspection)

For Claude Desktop, Cursor, or Claude Code (`mcpServers`) when inspecting full local files on disk:

```json
{
  "mcpServers": {
    "filesniff": {
      "command": "node",
      "args": ["/absolute/path/to/FileSniffWebsite/mcp/server.mjs"]
    }
  }
}
```

---

## Exposed Tools

### 1. `sniff_file`
Inspects up to the first 64 KiB (plus any ZIP central directory) of a local file and compares its detected type against its filename extension.

- **Input**: `{ "path": "/path/to/holiday.pdf" }`
- **Returns**: `detectedName`, `detectedExtension`, `mime`, `comparison` (`match` | `mismatch` | `neutral` + label such as `.pdf → .mp4`), `note`, and first 64 bytes as uppercase hex.

### 2. `inspect_office_document`
Inspects a local `.docx`, `.xlsx`, or `.pptx` file without executing macros or fetching external links.

- **Input**: `{ "path": "/path/to/workbook.xlsx" }`
- **Returns**: `format`, `headline`, `detail`, `ai` (explicit AI tool references in metadata), `automation` (`openpyxl`, `python-docx`, etc.), `metadata`, `propertyGuide`, `sheets` (including `hidden` / `veryHidden`), `fonts`, `colours`, `authoring`, `relationships`, and `hints`.

### 3. `strip_image_metadata`
Losslessly strips identifying metadata segments from a JPEG, PNG, or WebP file by copying allowlisted pixel and colour chunks verbatim.

- **Input**:
  ```json
  {
    "inputPath": "/path/to/photo.jpg",
    "outputPath": "/path/to/photo-clean.jpg",
    "keepColour": true,
    "keepOrientation": true,
    "keepCredentials": false
  }
  ```
- **Returns**: `format`, `originalBytes`, `cleanBytes`, `bytesSaved`, `orientationBefore`, `orientationAfter`, `removedCount`, and `removed` segment list.

---

## Running Tests

```sh
node --test tests/mcp.test.mjs
```