内容
# 文件 AI
用于代理的只读文档感知MCP服务器。文件AI使用Flyfish文件查看器核心作为格式识别的真实来源，然后将本地文件转换为稳定的配置文件、锚点、块、块组、轮廓、搜索结果和上下文代码段，以便代理在不需要逆向工程PDF、OOXML、电子表格、电子邮件或存档内部结构的情况下理解文档内容。
MCP注册表名称：`io.github.flyfish-dev/file-ai`
## 安装
直接使用`npx`：
```bash
npx -y @flyfish-dev/file-ai
```
或全局安装：
```bash
npm install -g @flyfish-dev/file-ai
file-ai --transport stdio
```
## MCP客户端配置
标准输入输出：
```json
{
"mcpServers": {
"file-ai": {
"command": "npx",
"args": ["-y", "@flyfish-dev/file-ai"]
}
}
}
```
可流式传输的HTTP：
```bash
npx -y @flyfish-dev/file-ai --transport http --host 127.0.0.1 --port 8765
```
端点：
```text
http://127.0.0.1:8765/mcp
```
## 工具
- `doc_analyze`：解析本地文件并缓存文档索引。
- `doc_read`：从现有索引或路径读取块、块组或锚点。
- `doc_search`：使用源锚点搜索缓存内容。
- `doc_context`：检索锚点或查询周围的附近块。
- `doc_list_formats`：列出文件查看器核心注册表格式、所有支持的扩展名、渲染器功能和文件AI提取器覆盖范围。
## 资源
- `doc://{indexId}/profile`
- `doc://{indexId}/outline`
- `doc://{indexId}/chunks`
## 支持的文件
文件AI通过`@file-viewer/core/headless`识别格式，目前涵盖206种已注册的扩展名。因此，`profile.format`与Flyfish文件查看器使用的相同渲染器选择保持一致。
内容提取是一个单独的层。文件AI为文本/代码/Markdown/JSON、PDF文本、DOCX、XLSX/CSV、PPTX、EML和存档清单提供结构化感知。其他文件查看器仅限渲染器的格式，如CAD、3D、媒体、图像、地理空间、绘图、电子书和数据资产，仍在`profile.format`中得到识别；当尚不存在结构化文本提取器时，文件AI返回配置文件以及尽力而为的元数据/文本和`profile.warnings`和`profile.extraction`中的明确警告。
每个内容块都带有锚点，如页、幻灯片、工作表、行范围、嵌套路径或字节/文本位置。代理在提出基于文档的声明时应引用返回的`anchorId`值。
## 开发
```bash
pnpm install
pnpm build
pnpm test
pnpm validate:skill
```
本地运行：
```bash
pnpm dev -- --transport stdio
pnpm dev -- --transport http --port 8765
```
## 发布
软件包包括：
- `@flyfish-dev/file-ai`的npm元数据
- `server.json`中的MCP注册表元数据
- GitHub Actions工作流`.github/workflows/publish-mcp.yml`
发布流程：
```bash
git tag v0.1.0
git push origin v0.1.0
```
工作流首先发布npm软件包，然后通过GitHub OIDC将`io.github.flyfish-dev/file-ai`发布到官方MCP注册表。存储库必须具有可以发布`@flyfish-dev/file-ai`的`NPM_TOKEN`密钥。
服务器是只读的。它不会修改源文档。
