File AI

Read-only document awareness MCP server for agents. File AI 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:

npx -y @flyfish-dev/file-ai

Or install it globally:

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

MCP Client Config

Stdio:

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

Streamable HTTP:

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

Endpoint:

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 known Flyfish File Viewer formats.

Resources

• doc://{indexId}/profile
• doc://{indexId}/outline
• doc://{indexId}/chunks

Supported Files

File AI prioritizes text, Markdown, JSON, source code, PDF, DOCX, XLSX, CSV, PPTX, EML, and archive manifests. Unsupported or weakly structured files return a best-effort profile, extracted text when available, and warnings.

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

pnpm install
pnpm build
pnpm test
pnpm validate:skill

Run locally:

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:

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.