# anydoc-mcp

把 [Firecrawl anydoc](https://github.com/firecrawl/anydoc) 封装成 **MCP (Model Context Protocol) Server**，让任何支持 MCP 的 AI 平台/Agent 都能调用文档转 Markdown 能力。

纯本地运行、无 ML 模型、**无需 API key、不联网**，中位转换耗时 < 5ms。

## 功能

- 提供 MCP 工具 `convert_document_to_markdown`
- 输入：文件名 + 文件内容（base64）
- 输出：干净的 GitHub-Flavored Markdown
- 自动从文件内容识别格式（CSV 等无签名格式按扩展名识别）
- 结构化错误返回（`needsOcr` / `unsupported` / `encrypted` / `malformed` 等）

## 支持的格式

| 类别 | 扩展名 |
|---|---|
| Word | `.doc` `.docx` `.docm` |
| PowerPoint | `.ppt` `.pps` `.pot` `.pptx` `.pptm` `.ppsx` `.ppsm` |
| Excel | `.xls` `.xlsx` `.xlsm` `.xlsb` |
| OpenDocument | `.odt` `.ods` `.odp` |
| 其他 | `.rtf` `.epub` `.csv` `.pdf`（文本型） |

## 限制

- **单向**：只做 文档 → Markdown，没有 Markdown → DOCX
- **扫描型/图片型 PDF 不支持**（anydoc 无 OCR，会返回 `needsOcr` 错误）
- **不渲染内嵌图片**：只抽取文字，文档中的截图/图表不会进入 Markdown
- 每次调用只处理一个文档

## 本地开发

### 前置条件

- Node.js >= 18
- npm（或 pnpm / yarn）

### 安装依赖

```bash
npm install
```

### 运行冒烟测试

```bash
npm test
```

验证 anydoc 核心转换能力（CSV → Markdown、错误处理）。

### 手动启动 MCP Server（STDIO）

```bash
npm start
```

Server 通过 stdin/stdout 与 MCP 客户端通信。日志输出到 stderr。

### 手动测试 MCP 协议

可以用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行图形化测试：

```bash
npx @modelcontextprotocol/inspector node src/server.js
```

## 发布到 npm

> 包名使用 scope `@fclwtt/anydoc-mcp`，确保全局唯一。如需更换 scope，修改 `package.json` 中的 `name`。

```bash
# 1. 登录 npm
npm login

# 2. 发布（scope 包首次发布必须加 --access public）
npm publish --access public

# 后续更新版本号后重新发布
npm version patch   # 或 minor / major
npm publish
```

发布成功后，任何支持 MCP STDIO 的平台都可以通过 `npx @fclwtt/anydoc-mcp` 一键启动。

## 接入云平台（以 aikf.wtc.edu.cn 为例）

在平台的「接入 MCP 插件」页面填写：

| 配置项 | 值 |
|---|---|
| 插件名称 | anydoc（或自定义） |
| 插件描述 | 文档转 Markdown：支持 docx/pptx/xlsx/pdf/odt/rtf/epub/csv，纯本地离线运行 |
| 传输方式 | **STDIO** |
| 命令 | `npx` |
| 参数 | `-y @fclwtt/anydoc-mcp` |
| 环境变量 | 无需配置（纯本地运行，不需要 API key） |

> `-y` 参数让 npx 自动确认安装，避免交互式提示阻塞平台启动。

### 平台调用示例

平台的大模型会自动发现并调用 `convert_document_to_markdown` 工具，传入：

```json
{
  "filename": "报告.docx",
  "content_base64": "UEsDBBQAAAAIA..."
}
```

返回 Markdown 文本。

## 项目结构

```
anydoc-mcp/
├── src/
│   └── server.js          # MCP Server 主文件
├── test/
│   ├── smoke.mjs          # 冒烟测试
│   └── mcp_protocol_test.mjs  # MCP 协议级测试
├── .github/
│   └── workflows/
│       └── publish.yml    # GitHub Actions 自动发布
├── package.json
├── README.md
├── PUBLISH.md             # 发布指南
└── .gitignore
```

## 技术栈

- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — MCP 官方 Node.js SDK
- [@firecrawl/anydoc](https://github.com/firecrawl/anydoc) — Firecrawl 开源文档转 Markdown 库（Rust + Node 绑定）

## License

MIT