内容
<div align="center">
<img src="public/token-it-down.svg" alt="TokenItDown" width="72" height="72" />
# TokenItDown
**拖放文件或网页，即可获得适用于 AI 的 Markdown 文本 — 让 AI 直接读取，节省大量 tokens。**
一个快速、可自行托管的平台，能够将任意文档或网页转换为干净、适用于大型语言模型（LLM）的 Markdown 文本 — 并超越转换，提供可视化质量控制、RAG 就绪输出、token 经济模型和原生 AI 代理（MCP）访问。
[快速开始](#快速开始) · [文档](docs/) · [从任意 AI 代理使用](#从任意AI编码代理使用) · [贡献](#贡献) · [问题](../../issues)
</div>
<br />
<div align="center">
<img src=".github/screenshots/dashboard.png" alt="TokenItDown dashboard" width="900" />
</div>
<br />
由 **AnHourTec** 构建和维护。
> 如果 TokenItDown 为您节省了 tokens，请考虑为该项目点赞 — 这真的有助于其他人发现它。
## 为什么选择 TokenItDown
转换引擎本身已经很成熟。我们的价值在于围绕它的工作流程 — 库、修复循环、RAG 导出、代理集成和网页捕获扩展 — 以干净的方式打包，适用于云用户和自行托管用户。
两种部署目标来自同一代码库：
- **云** — 多租户 SaaS，带有托管处理、计费和托管 MCP 端点。
- **自行托管** — 一个 `docker compose up` 命令，全部处理本地，可选本地 LLM 模式，无数据外流。
## 功能
- **将任意内容转换为 Markdown** — 由 [Microsoft MarkItDown](https://github.com/microsoft/markitdown) 提供支持：PDF、Word、PowerPoint、Excel、图像（OCR + EXIF）、音频（转录）、HTML、CSV/JSON/XML、ZIP（迭代）、EPUB 和 YouTube / 网页 URL。
- **每种格式的转换页面** — 每个源类型都有专用页面，支持拖放批量上传、文档扫描动画和 GitHub 风格的渲染结果。
- **库** — 每个转换后的文档都在文件查看器中，支持 **预览 / 原始** 切换（通过 `react-markdown` + GFM 渲染 Markdown，或通过 Shiki 进行语法高亮显示源代码），以及复制、下载和删除。
- **文档** — 每个 **原始** 上传的文件都在原地预览，支持 **原始 / Markdown** 切换。原始文件存储在本地卷中；转换后的 Markdown 存储在 Postgres 中。
- **实时数据仪表盘** — 关键绩效指标（文档、节省的 tokens、代理转换、存储的原始文件）、30 天转换活动图表、最近转换、来源分解和 top token 节省者。
- **从 AI 编码代理（MCP）使用** — 内置的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器允许 Claude Code、Cursor、VS Code Copilot 或 Claude Desktop 自动调用 TokenItDown，当您将文件或 URL 传递给代理时。支持 **本地（stdio）** 转换您自己的文件，无需帐户，或 **托管（HTTP）** 适用于远程代理，带有每个用户的 API 密钥。
- **适用于任何代理，而不仅仅是 Claude** — Connect 编辑器页面提供每个编辑器的安装代码片段和可下载的、实例感知的 **`AGENTS.md` / `CLAUDE.md` / `skills.md`** 插入文件（可全文查看），以便 Codex、Cursor、Gemini、Windsurf、Cline、Aider 或任何 MCP 主机知道使用 TokenItDown。
- **每个用户 API 密钥 + 全透明** — 从仪表盘颁发可撤销的 API 密钥。代理使用密钥进行的转换通过与仪表盘相同的管道（清理、token 计数、保存到您的库），并归因于该密钥，因此 Connect 页面显示每个密钥的调用次数、节省的 tokens 和转换内容。
- **身份验证** — 带有 httpOnly cookie 会话的电子邮件/密码（[better-auth](https://www.better-auth.com/)）存储在 Postgres 中，CSRF 通过受信任的来源保护仪表盘。
## 截图
| 连接任意 AI 代理（MCP） | 库 |
| :-----------------------------------------: | :----------------------------------: |
|  |  |
| _每个用户 API 密钥，用法和插入文件_ | _预览 / 原始，token 节省_ |
|  |  |
| _转换任意格式_ | _实时数据仪表盘_ |
## 从任意 AI 编码代理（MCP）使用
TokenItDown 配备了 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，因此您的代理可以在您将文件或 URL 传递给它时调用它 — 无需复制粘贴，token 消耗极低。
```bash
# Claude Code — 本地（转换您自己的文件，无需帐户）：
claude mcp add tokenitdown -- python -m app.mcp_server
# 托管 — 在仪表盘的“连接编辑器”页面创建 API 密钥，然后：
claude mcp add --transport http tokenitdown https://<host>:8001/mcp \
--header "Authorization: Bearer YOUR_TOKENITDOWN_API_KEY"
```
三个工具可供模型使用：`convert_url_to_markdown`、`convert_file_to_markdown`（本地）和 `convert_document`（托管）。在托管模式下，每个转换都通过 Web 管道代理，因此它会被清理、计算 token、保存到您的库，并归因于该密钥。有关每个编辑器的设置的详细信息，请参见 [AI 代理文档](docs/pages/agents/index.mdx)。
## 架构
- **Web** — Next.js 应用（仪表盘、身份验证、API 路由）。转换请求从 `app/api/convert*` 代理到处理服务，通过内部网络，由共享密钥控制。转换路由接受会话（仪表盘）或 `Authorization: Bearer tid_…` API 密钥（代理）。
- **处理服务** (`server/`) — Python [FastAPI](https://fastapi.tiangolo.com/) 包装器围绕 `markitdown[all]`，带有 `/convert`（上传）和 `/convert-url`（SSRF 防护）。仅限内部使用。
- **MCP 服务器** (`server/app/mcp_server.py`) — `markitdown-mcp` 容器。在托管/HTTP 模式下，它验证代理的 API 密钥并 **将转换请求代理回 Web 管道**，因此代理活动被清理、跟踪和保存，如同其他转换。
- **Postgres** — 用户、会话、转换后的文档（标记为创建它们的 API 密钥）和 API 密钥（Drizzle ORM）。密钥存储为 SHA-256 哈希；完整 token 仅显示一次。
- **Redis** — 保留用于作业队列/会话存储。
> 完整细节 — 每个服务、请求生命周期、MCP/代理流程、安全边界和数据模型 — 参见 **[架构文档](docs/pages/architecture.mdx)**。
## 技术栈
- [Next.js 15](https://nextjs.org/)（应用路由器）+ [React 19](https://react.dev/)，严格 [TypeScript](https://www.typescriptlang.org/)，带有 [ts-reset](https://github.com/total-typescript/ts-reset)
- [Tailwind CSS v4](https://tailwindcss.com/) + [Radix UI](https://www.radix-ui.com/) + [CVA](https://cva.style/)；[react-markdown](https://github.com/remarkjs/react-markdown)，[Shiki](https://shiki.style/)，[recharts](https://recharts.org/)，[sonner](https://sonner.emilkowal.ski/)
- [better-auth](https://www.better-auth.com/) + [Drizzle ORM](https://orm.drizzle.team/) + PostgreSQL
- 处理：[Python](https://www.python.org/) / [FastAPI](https://fastapi.tiangolo.com/) / [MarkItDown](https://github.com/microsoft/markitdown) / [FastMCP](https://github.com/jlowin/fastmcp)
- 测试：[Vitest](https://vitest.dev)，[Playwright](https://playwright.dev/)，[pytest](https://docs.pytest.org/)；[T3 Env](https://env.t3.gg/) + [OpenTelemetry](https://opentelemetry.io/)
## 要求
- [Node.js](https://nodejs.org/) `>=22` 和 [npm](https://www.npmjs.com/)（项目的包管理器）
- [Docker](https://www.docker.com/) + Docker Compose（用于 Postgres/Redis 和全栈部署）
- [Python](https://www.python.org/) `>=3.10`（仅在 Docker 外运行处理服务时）
## 快速开始
```bash
# 1. 安装依赖
npm install
# 2. 配置环境变量
cp .env.example .env # 然后填写密钥（BETTER_AUTH_SECRET, MARKITDOWN_SERVICE_TOKEN, 数据库凭证…）
# 3. 启动 Postgres、Redis 和 MarkItDown 服务
docker compose up -d postgres redis markitdown
# 4. 运行 Web 应用（自动创建数据库 + 应用迁移）
npm run dev
```
打开 [http://localhost:3000](http://localhost:3000)。注册后，从侧边栏的 **转换** 开始转换；在 **库** 中查看结果，在 **文档** 中查看原始文件。
## 部署
自行托管版本作为 `docker compose` 包提供 — **Web + Postgres + Redis + MarkItDown 处理服务 + MCP 服务器 + 文档站点**。在主机上复制 `.env.example` → `.env`，设置真实密钥（包括 `MARKITDOWN_SERVICE_TOKEN`），然后：
```bash
./deploy.sh
```
这将构建镜像并启动整个栈；Web 容器等待处理服务，确保数据库并在启动时运行迁移。所有内容都可以通过一个来源访问：
- **应用** — `http://<host>:${WEB_PORT:-3030}`
- **文档** — `http://<host>:${WEB_PORT:-3030}/docs`（Web 应用代理 `/docs` 到文档容器；侧边栏也有 **文档** 链接）
- **MCP 端点** — `http://<host>:${MCP_PORT:-8001}/mcp`
## 文档
文档是 [Nextra](https://nextra.site/) 站点，位于 **[`docs/`](docs/)**，在运行的应用上提供 **`/docs`**（例如 `http://<host>:3030/docs`）— 无需单独端口。要在本地使用应用开发文档：
```bash
# 终端 1 — 应用在 :3000
npm run dev
# 终端 2 — 文档在 :3040（通过 basePath 在 /docs 下提供）
cd docs && npm install && npm run dev -- -p 3040
# 预览同源代理，设置 .env 中的 DOCS_INTERNAL_URL 并重启应用：
# DOCS_INTERNAL_URL=http://localhost:3040
# 然后打开 http://localhost:3000/docs
```
它涵盖了快速开始、自行托管、配置、转换、库、RAG 导出、**AI 代理 / MCP** 集成、架构、API 参考、路线图和常见问题。
## 贡献
欢迎贡献！参见 **[CONTRIBUTING.md](CONTRIBUTING.md)** 了解如何设置项目、我们遵循的约定以及如何提出一个好的拉取请求 — 特别是如何报告 **代理 / MCP 兼容性问题**（哪个代理、哪个传输、哪个安装代码片段）。查看 [开放问题](../../issues) 以了解可以改进的内容。
发现安全漏洞？请私下报告，而不是公开提出问题 — 参见 [安全](CONTRIBUTING.md#security) 部分。
## 致谢
转换功能由 [Microsoft MarkItDown](https://github.com/microsoft/markitdown) 提供支持。TokenItDown 是围绕它的工作流程、质量控制、RAG 导出和代理集成。
## 星级历史
[](https://www.star-history.com/#anhourtec/tokenitdown&Date)
## 许可证
[MIT](LICENSE) © AnHourTec
