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:

Terminal

npx -y @flyfish-dev/file-ai

Or install it globally:

Terminal

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

MCP Client Config

Stdio:

config.json

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

Streamable HTTP:

Terminal

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.