Content
# 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.
