# File AI

Read-only document awareness MCP server for agents. File AI uses Flyfish File Viewer core as the source of truth for format recognition, then turns local files into a stable profile, anchors, blocks, chunks, outline, search results, and contextual snippets so an agent can understand document content without reverse-engineering PDF, OOXML, spreadsheet, email, or archive internals.

MCP Registry name: `io.github.flyfish-dev/file-ai`

## Install

Use it directly with `npx`:

```bash
npx -y @flyfish-dev/file-ai
```

Or install it globally:

```bash
npm install -g @flyfish-dev/file-ai
file-ai --transport stdio
```

## MCP Client Config

Stdio:

```json
{
  "mcpServers": {
    "file-ai": {
      "command": "npx",
      "args": ["-y", "@flyfish-dev/file-ai"]
    }
  }
}
```

Streamable HTTP:

```bash
npx -y @flyfish-dev/file-ai --transport http --host 127.0.0.1 --port 8765
```

Endpoint:

```text
http://127.0.0.1:8765/mcp
```

## Tools

- `doc_analyze`: parse a local file and cache a document index.
- `doc_read`: read blocks, chunks, or anchors from an existing index or path.
- `doc_search`: search cached content with source anchors.
- `doc_context`: retrieve nearby blocks around an anchor or query.
- `doc_list_formats`: list File Viewer core registry formats, all supported extensions, renderer capabilities, and File AI extractor coverage.

## Resources

- `doc://{indexId}/profile`
- `doc://{indexId}/outline`
- `doc://{indexId}/chunks`

## Supported Files

File AI recognizes formats through `@file-viewer/core/headless`, currently covering 206 registered extensions. `profile.format` is therefore aligned with the same renderer selection used by Flyfish File Viewer.

Content extraction is a separate layer. File AI provides structured awareness for text/code/Markdown/JSON, PDF text, DOCX, XLSX/CSV, PPTX, EML, and archive manifests. Other File Viewer renderer-only formats such as CAD, 3D, media, image, geospatial, drawing, ebook, and data assets are still recognized in `profile.format`; when no structured text extractor exists yet, File AI returns a profile plus best-effort metadata/text and explicit warnings in `profile.warnings` and `profile.extraction`.

Every content block carries an anchor such as a page, slide, worksheet, row range, nested path, or byte/text location. Agents should cite returned `anchorId` values when making document-grounded claims.

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm validate:skill
```

Run locally:

```bash
pnpm dev -- --transport stdio
pnpm dev -- --transport http --port 8765
```

## Publishing

The package includes:

- npm metadata for `@flyfish-dev/file-ai`
- MCP Registry metadata in `server.json`
- GitHub Actions workflow `.github/workflows/publish-mcp.yml`

Release flow:

```bash
git tag v0.1.0
git push origin v0.1.0
```

The workflow publishes the npm package first, then publishes `io.github.flyfish-dev/file-ai` to the official MCP Registry through GitHub OIDC. The repository must have an `NPM_TOKEN` secret that can publish `@flyfish-dev/file-ai`.

The server is read-only. It does not mutate source documents.