TweekIT MCP Server

TweekIT MCP 服务

将几乎任何文件类型导入并转换为 AI 工作流

当前版本：v1.6.1

🤖 Claude 用户：受够了“文件类型不受支持”错误？请跳转至我们的 Claude 文件格式启用工具——这是一款基于浏览器的工具，可在数秒内将 450 多种格式（DOC、XLS、PSD、DWG 等）转换为 Claude 兼容的文件。

概述

TweekIT MCP 服务是面向 AI 工作流的通用媒体转换器，可在数秒内让任何文件为处理做好准备。TweekIT 基于 Equilibrium 的 MediaRich Server 强大的内容处理引擎构建。这项技术自 2000 年以来不断开发，深受全球大型门户网站和媒体公司的信赖。TweekIT 汇集了数十年的专业经验，擅长处理复杂媒体，其技术传承还包括著名的 DeBabelizer。

借助 TweekIT，你可以通过统一的 API 或小组件界面，上传、预览、转换和下载 400 多种受支持的文件类型。它会自动规范化素材并为工作流的下一步做好准备，从而消除应对不可预测输入格式的烦恼。

什么是 TweekIT？

TweekIT 是一项通用媒体导入与转换服务，旨在接收任何受支持的文件，并在数秒内使其为 AI 做好准备。无论你是要规范化格式、调整素材大小，还是从复杂文档中提取单页，TweekIT 都能通过一致、以 API 为先的方式，精准提供你所需的输出，无需担心各种文件类型的特殊问题。

为什么在 MCP 环境中使用它？

在模型上下文协议（MCP）工作流中，TweekIT 就像媒体的通用转换器。它位于 AI Agent 与其遇到的不可预测的现实世界文件之间，确保每项素材在处理之前都转换为兼容的标准格式。这类似于 GitHub Actions 如何简化软件自动化，只不过 TweekIT 将这种能力用于 AI 流水线中的媒体处理。

将 TweekIT 纳入 MCP 工具集后，你的 Agent 可以：

• 接受用户范围更广的输入，而不会失败
• 自动应用裁剪、调整大小、格式转换和背景更改等转换操作
• 无需人工介入修复我们都非常熟悉的、由客户文件导入失败造成的持续问题，即可将干净、可直接使用的素材传递给 AI 工作流的下一步

🤖 Claude 用户：请参阅解决 Claude 的文件类型限制，了解如何使用 TweekIT 克服 Claude 内置的文件格式限制，以及如何使用我们的独立网页转换工具。

示例场景

在入职流程中，用户上传了一份身份证扫描件 PDF。你的 MCP Agent 调用 TweekIT 来：

• 将 PDF 转换为 PNG 图像
• 裁剪图像，仅保留身份证
• 将图像调整为标准的 300x300 像素头像
• 将转换后的图像直接返回验证流水线

整个过程只需数秒，工作流也无需处理不兼容的文件格式。

主要功能

• 支持 400 多种文件类型，实现无缝导入与转换，依托经过二十余年打磨的核心引擎处理动态图像和视频。
• 无状态、以 API 为先的设计，便于快速构建可扩展的集成
• 提供小组件或 REST API，适配各种应用架构
• 企业级安全性，支持安全的密钥处理和短期素材存储
• 即时修复兼容性问题，立即避免 AI 流水线因输入格式不佳而失败

立即试用

• AI 文件格式启用工具——基于浏览器的转换器，适用于 Claude、OpenAI 和其他 AI 工具（DOC、XLS、PSD、DWG → PDF/PNG）
• 在线演示——在浏览器中上传并转换文件
• 用例示例——在网站上查看实际工作流和代码示例。具体的 MCP 清单转换示例见下文第 7 节。

目录

• 概述
• 解决 Claude 的文件类型限制
• 要求
• 安装
• 快速入门
• 身份验证
• 服务与托管
• 客户端兼容性
  • 快速入门（Claude Desktop）
  • 快速入门（ChatGPT MCP）
  • 快速入门（Cursor IDE）
  • 快速入门（Continue IDE）
  • 快速入门（OpenAI Codex CLI）
• 速率限制与定价
• 核心概念
• MCP API 参考
• REST API 参考
• 使用场景
• 演示 + 展示代码
• 错误处理与故障排查
• 高级主题
• 注册表就绪情况
• 资源

要求

• Python 3.10 或更高版本
• Docker（可选，用于容器化构建）
• 用于 HTTP 请求的 httpx 库
• 用于工具注册和服务功能的 FastMCP

安装

选项 1：从 PyPI 安装（推荐）

# Using pip
pip install tweekit-mcp

# Using uv
uv pip install tweekit-mcp

# Using pipx (isolated environment)
pipx install tweekit-mcp

在本地运行 MCP 服务：

tweekit-mcp --transport streamable-http --port 8080

CLI 封装了 server.py，并接受相同的标志（--transport、--host、--port）。

选项 2：克隆仓库

git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp
uv sync            # or: pip install -r requirements.txt

按需设置环境变量：

• PORT – Streamable HTTP 端口（默认值：8080）。
• PLUGIN_PROXY_PORT – ChatGPT 插件代理的端口（独立运行时默认值：8080）。
• MCP_SERVER_PORT – 使用 start_services.sh 时 MCP 服务的内部端口（默认值：8000）。

快速入门

第 1 步：注册

创建免费的 TweekIT 账户，即可开始使用，并免费获得 10,000 次 API 调用。
在此查看定价并注册，在 MANAGE ACCOUNT 页面生成 API 凭据，然后开始使用服务。

第 2 步：选择身份验证方式

TweekIT 支持多种身份验证方式。但只有 Key/Secret 配对方式适用于 MCP 集成。

• API Key 和 Secret – MCP 生产环境使用的必需方式，更安全且更易于控制访问

注册后，你可以在账户信息中心找到这些值。请妥善保管，切勿在客户端代码中暴露。

第 3 步：发起首次 API 调用

下面是一个最简可运行的 JSON 示例：发送一张图片并执行基本的调整大小操作，预览转换效果，然后返回结果。此示例使用 API Key 和 Secret 身份验证。

此 JSON 是通过使用 MCP Inspector 与公开可用的 MCP 服务捕获的。

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "png",
      "outfmt": "png",
      "blob": "iVBORw0KGgoAAAANSUhEUgAAABwAAAA6CAYAAACj+Dm/AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAAsSAAALEgHS3X78AAAAHnRFWHRTb2Z0d2FyZQBFcXVpbGlicml1bSBNZWRpYVJpY2h7w4AAAAAB30lEQVRYhe2Xv0vDQBTHP4rQTRGhLqKiYt38MaggKIi46e6im2Rw7FJw7NAh4uAi+h/oIDgKnR3VQZROKiLYrZtOOiQH1+RevJQ0INwXQt7de7lP++7l7tJTq9XIU7250hzQAR3QAR3QAXMH3gM/wG0ewHtgNrSXgXo3gXUNprTSLaAPrBv6C4DXDeBBgm8ha+ArwT+RNJkl8BoY/SNmKiugB2xaxA1nBayQnEolY+GkBdqkUlescNIAPWBL8D0I/bHCSQOsCP3fwFx4jypWOLbApFRehfdPgy9WODbApKpsATuh/WHwxwrHBphUlRea/SLErKUBniGn8g3Y19qPQtx4GuBugu8y0q4KcRN6oy9hwFvkVDaAfoKtaQgYBAaE2KINsE6wkUqaDi9b+UBZAn5ht3Sl0bwyTHOYNQxgRAIad+kMNJY3sAAcQvscesQPQ7qaBPP7Bbxr/XeaXab9BKdrMQrcS4AdhYPZ6EkArkJ7SucNQRC8c7YwCNZW084xAPgKeI25Or+B4xQwpWehf0MBl4SAG+C0A6D0zIwCFg3OJrDdAUwBTaeAggI2DM6TDmFKcwT7pa6GApY0aAs4R17908gnyBTh+CX9tShlAIiqSuSH/+sPUgd0QAf8J8BfT2hGnMaA5CUAAAAASUVORK5CYII=",
      "noRasterize": false,
      "width": 30,
      "height": 30,
      "page": 1,
      "bgcolor": ""
    }
  },
  "jsonrpc": "2.0",
  "id": 4
}

第 4 步：查看实际效果

你可以先通过可视化方式探索 TweekIT，再编写代码。通过在线演示，你可以上传文件、应用转换并立即下载结果。

• 打开在线演示
• 查看使用场景示例，了解实际工作流和代码示例

身份验证

TweekIT 支持多种身份验证方式（REST API、APP ID 方式仅供使用）。设置 API Key 和 Secret，即可快速开始，同时遵循安全最佳实践。

用于 MCP 服务：API Key + Secret

这是最安全、最灵活的选项。所有生产环境部署都应使用此方式。

步骤：

1. 在 TweekIT 账户设置中生成 API Key 和 Secret。
2. 安全地保存它们，切勿提交到源代码管理系统。
3. 使用服务端代码或反向代理，将凭据注入请求。

安全提示：

• 始终使用反向代理或其他服务端方式来保护凭据。
• 切勿在客户端代码中嵌入密钥。

后续步骤：
完成身份验证后，你可以：

• 在请求中使用 Base-64 上传媒体
• 接收输出

服务与托管

托管的就绪 MCP 服务

所有工具和资源均可在此使用，适用于测试和免费试用：

• 公共 MCP 端点（HTTP 传输）：https://mcp.tweekit.io/mcp

当前可用的资源名称为 'version'。当前可用的工具名称为 'doctype'、'convert' 和 'convert_url'。参数见下文，也可以查询 MCP 服务，它会返回指导如何使用这些工具的元数据。

版本控制与构建编号

项目采用 major.minor.build 格式跟踪语义化版本，其中 build 部分补齐为两位数（例如 1.6.01）。使用 scripts/bump_version.py 确保所有元数据文件保持一致：

# Increment just the build number (e.g., 1.6.01 -> 1.6.02)
python scripts/bump_version.py --bump-build

# Set an explicit version, resetting the build counter as needed
python scripts/bump_version.py --set 1.7.00

该脚本会更新 VERSION、pyproject.toml、server.py、server.json、README.md 和 uv.lock，确保容器构建、清单和文档保持同步。

MCP 安装

你可以在本地运行 TweekIT MCP 服务，也可以连接到托管实例。建议在开发和测试时使用本地选项。

本地安装

git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp
pip install -r requirements.txt

运行服务：

uv run server.py

服务将在以下地址监听：

• http://localhost:8080

配置选项

本地开发模式
默认情况下，server.py 会绑定到 localhost 的 8080 端口。你可以使用 PORT 环境变量覆盖端口：

PORT=9090 uv run server.py

Cloud Run 部署

使用提供的脚本，在 Google Cloud Run 上构建并部署容器化的预发布或生产服务。

前置条件：

• 可访问 Google Cloud 项目（默认为 tweekitmcp-a26b6）。
• 已通过身份验证的 gcloud CLI（gcloud auth login）；如果标准配置目录为只读，还需提供可写的导出路径，例如 export CLOUDSDK_CONFIG="$(pwd)/.gcloud-config"。

使用 Docker 在本地运行容器（构建镜像 tweekit-mcp-local:dev 并绑定到 8080）：

bash scripts/deploy_cloud_run.sh local --version dev

部署到预发布环境（创建或更新 tweekit-mcp-stage 服务）：

bash scripts/deploy_cloud_run.sh stage --version 1.6.01

部署到生产环境（更新 tweekit-mcp 服务）：

bash scripts/deploy_cloud_run.sh prod --version 1.6.01

如果需要覆盖当前的 gcloud 配置，请传入 --project <PROJECT_ID>；如需以 YAML 格式提供 Cloud Run 环境变量，请传入 --env-file <path>。

辅助脚本不会打包凭据。运行脚本时，请始终提供你自己的 Google Cloud 项目、区域和密钥来源；Equilibrium 的预发布/生产密钥存储在托管密钥库中，并有意排除在此代码库之外。

Firebase Functions 的 Python 依赖项会在部署时解析。scripts/deploy_firebase.sh 会在本地将这些依赖项打包到 functions/packages/（一个被 git 忽略的目录），以保持代码库轻量。

客户端兼容性

• Claude Desktop / claude.ai：兼容（HTTP 传输；提供 .mcpb 捆绑包）。
• ChatGPT (OpenAI)：兼容（HTTP 传输；提供插件代理）。
• OpenAI Codex CLI：兼容（使用 --mcp-server 标志或 ~/.codex/config.yaml）。
• Cursor：兼容（通过 ~/.cursor/mcp.json 使用 HTTP 传输）。
• Continue (VS Code / JetBrains)：兼容（通过 ~/.continue/config.json 使用 Streamable HTTP）。
• Windsurf / Sourcegraph Cody：兼容（通过测试版设置使用 HTTP MCP 端点）。

示例

• Claude Desktop（配置片段）：

  {
    "mcpServers": {
      "tweekit": {
        "transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp" }
      }
    }
  }
  

• Claude 工具调用（参数示例）：

  {
    "name": "convert",
    "arguments": {
      "apiKey": "YOUR_KEY",
      "apiSecret": "YOUR_SECRET",
      "inext": "png",
      "outfmt": "webp",
      "blob": "<base64>",
      "width": 300,
      "height": 300
    }
  }
  

• OpenAI（Node，使用 MCP TypeScript 客户端）：

  import { Client } from "@modelcontextprotocol/sdk/client";
  import { HttpClientTransport } from "@modelcontextprotocol/sdk/client/transport/http";
  
  const transport = new HttpClientTransport(new URL("https://mcp.tweekit.io/mcp"));
  const client = new Client({ name: "tweekit-example", version: "1.0.0" }, { capabilities: {} }, transport);
  await client.connect();
  const tools = await client.listTools();
  const res = await client.callTool({
    name: "doctype",
    arguments: { ext: "pdf", apiKey: process.env.TWEEKIT_API_KEY, apiSecret: process.env.TWEEKIT_API_SECRET },
  });
  console.log(res);
  

• OpenAI（Python，快速调用）：

  import asyncio
  import os
  
  from fastmcp import Client
  
  async def main():
      async with Client("https://mcp.tweekit.io/mcp") as c:
          print(await c.list_tools())
          out = await c.call_tool(
              "convert",
              {
                  "apiKey": os.environ["TWEEKIT_API_KEY"],
                  "apiSecret": os.environ["TWEEKIT_API_SECRET"],
                  "inext": "png",
                  "outfmt": "txt",
                  "blob": "<base64>",
              },
          )
          print(out)
  asyncio.run(main())
  

快速开始（Claude Desktop）

在 Claude Desktop 中使用 Tweekit 有两种方式：

1. 托管 HTTP 服务 – 通过“设置” → “连接器” → “高级” → “开发者模式” →“添加 HTTP 服务”，让 Claude 连接到 https://mcp.tweekit.io/mcp。
2. 本地软件包（.mcpb） – 安装打包好的 stdio 服务，以便离线使用或分发定制版本。

我们使用 scripts/build_claude_bundle.py 和引导式辅助脚本 scripts/configure_claude_desktop.py 来维护本地软件包。该辅助脚本会引导你选择版本、生成软件包、验证 dxt 清单，最后提醒你导入生成的 dist/tweekit-claude.mcpb。它还会再次说明，我们的生产级 Tier 1 无头节点运行在 Equilibrium 自有的 CPUcoin 企业矿机上，这些矿机位于符合 SAS 70 / ISO 27001 标准的数据中心——本地软件包提供相同的功能集。

连接后（任一方式均可）：

• 提问：“通过 doctype 列出支持的输入类型。”
• 或使用你的密钥／密钥对和 base64 数据调用 convert：

{
  "name": "convert",
  "arguments": { "apiKey": "…", "apiSecret": "…", "inext": "png", "outfmt": "webp", "blob": "<base64>" }
}

快速开始（ChatGPT MCP）

如果你的 ChatGPT 环境支持 MCP 工具，请添加一个指向公共端点的 HTTP MCP 服务。

1. 配置服务：URL 为 https://mcp.tweekit.io/mcp（HTTP 传输）
2. 在聊天中使用工具：

• doctype

{ "name": "doctype", "arguments": { "ext": "pdf", "apiKey": "…", "apiSecret": "…" } }

• convert

{
  "name": "convert",
  "arguments": {
    "apiKey": "…",
    "apiSecret": "…",
    "inext": "png",
    "outfmt": "txt",
    "blob": "<base64>"
  }
}

快速开始（Cursor IDE）

Cursor 从 ~/.cursor/mcp.json 加载 MCP 配置。要启用托管的 TweekIT 服务，请将以下代码片段（也发布于 configs/cursor-mcp.json）合并到现有文件中：

{
  "mcpServers": {
    "tweekit": {
      "type": "http",
      "url": "https://mcp.tweekit.io/mcp",
      "headers": {
        "ApiKey": "${TWEEKIT_API_KEY}",
        "ApiSecret": "${TWEEKIT_API_SECRET}"
      }
    }
  }
}

• 将 .env.example 复制为 .env，填写 TWEEKIT_API_KEY / TWEEKIT_API_SECRET，然后执行 source .env（或手动导出这些变量）。

2. 重启 Cursor 并运行“列出工具”，确认 version、doctype、convert 和 convert_url 均可用。
3. 可选：在内部托管该 JSON，并为团队成员提供“添加到 Cursor”的深层链接。

快速开始（Continue IDE）

Continue（VS Code / JetBrains）将 MCP 服务配置存储在 ~/.continue/config.json 中。在 mcpServers 下添加 TweekIT 服务（可直接复制的 JSON 位于 configs/continue-mcp.json）：

{
  "mcpServers": {
    "tweekit": {
      "type": "streamable-http",
      "url": "https://mcp.tweekit.io/mcp",
      "headers": {
        "ApiKey": "${TWEEKIT_API_KEY}",
        "ApiSecret": "${TWEEKIT_API_SECRET}"
      }
    }
  }
}

保存配置后：

1. 重新加载 Continue，使其读取新的 MCP 条目。
2. 使用 Continue 的“工具”面板，传入相应参数调用 doctype、convert 或 convert_url。
3. 记录适用于工作区的凭证设置步骤，让团队成员能够快速连接。

快速开始（OpenAI Codex CLI）

OpenAI Codex CLI（@openai/codex）将 MCP 服务作为一等插件提供支持。添加 TweekIT 有两种方式：

选项 A — 单行命令，轻松添加插件（无需配置文件）：

export TWEEKIT_API_KEY=your_key TWEEKIT_API_SECRET=your_secret
codex --mcp-server tweekit:https://mcp.tweekit.io/mcp

每次会话都传入 --mcp-server 标志，或在 shell 配置文件中为其设置别名，以便永久使用。

选项 B — 持久化配置（~/.codex/config.yaml）：

将以下条目（也位于 configs/codex-mcp.yaml）合并到 Codex 配置中：

mcpServers:
  tweekit:
    type: http
    url: https://mcp.tweekit.io/mcp
    headers:
      ApiKey: “${TWEEKIT_API_KEY}”
      ApiSecret: “${TWEEKIT_API_SECRET}”

通过任一方式连接后：

• 提问：“通过 TweekIT doctype 列出支持的输入类型。”
• 或提问：“使用 TweekIT 将此 DOC 文件转换为 PDF，以便你阅读。”
• 或提问：“将 <url> 处的图像转换为 800×600 的 WebP。”

安装 Codex CLI： npm install -g @openai/codex

速率限制和定价

TweekIT 提供充足的免费套餐，让你可以免费探索和集成。

免费套餐

• 包含 10,000 次 API 调用，无需付费。
• 完全使用所有核心上传、预览、下载和删除功能。
• 开始使用无需信用卡。

付费方案

如果超出免费套餐限额，你可以随时升级到付费方案。
详情请参阅完整定价指南。使用 MCP 服务需要持有令牌密钥对：
https://www.tweekit.io/pricing/

处理速率限制错误

达到每月配额后，API 将返回 HTTP 429 Too Many Requests 状态。

MCP 集成提示：
你的 MCP 客户端应：

1. 捕获 429 响应。
2. 向用户显示清晰的错误消息。
3. 建议立即升级方案，以便继续使用。

核心概念

了解这些核心概念，有助于你在 MCP 工作流中充分发挥 TweekIT 的作用。

请求包含 Base-64 内容 → 响应包含 Base-64 结果

TweekIT MCP Server 使用这套简单、无状态且安全的管道处理文档请求。

转换

TweekIT 支持多种转换，并在预览时应用：

• 调整大小：按宽度和高度调整（如果只发送一个参数，系统会自动计算另一个参数以保持宽高比）
• OutFormat：将文件格式转换为其他类型
• 背景颜色：填充透明或留白区域
• NoRasterize：与 PDF 输出格式结合使用时，将整个文本类文档转换为 PDF 文件，以供上游 AI 导入。

无状态处理

TweekIT 不会持久存储你的文件。

• 每次请求后都会清除作业文件夹和临时存储。
• 这种设计可尽量减少存储开销，并为敏感文件提供更强的隐私保护。
• 传输中的数据通过 SSL 加密。

MCP 参考

资源

/version

说明： 获取 TweekIT API 的当前版本。不接受任何参数。

/server-version

说明： 返回此 MCP 服务的版本字符串（例如，1.6.01）。不接受任何参数。

工具

/doctype

说明： 获取支持的输入文件格式列表，或将文件扩展名映射为其文档类型。如果返回的文档类型字段为空，则表示不支持读取该格式。

参数：

• extension：文件扩展名（例如，jpg、docx）。可选，默认为“*”（返回所有支持的输入文档类型）。
• apiKey：用于身份验证的 API 密钥。
• apiSecret：用于身份验证的 API 密钥。

/convert

说明：将 Base64 编码的文档转换为指定的输出格式。

参数：

• apiKey：用于身份验证的 API 密钥。
• apiSecret：用于身份验证的 API 密钥。
• inext：输入文件扩展名（例如，jpg、png、doc、docx 等）。
• outfmt：所需的输出格式（例如，jpg、pdf、png）。
• blob：Base64 编码的文档数据。

可选参数：

• noRasterize：如果输入文档是基于文本的文档（doc、odt、xls 等），且输出格式设为“pdf”，并将此参数设为 true，则不会对文档进行栅格化和图像操作，而是将所有页面转换为 PDF 并返回。如果输出格式不是“pdf”，则会忽略此参数。默认为 false。
• width：输出的所需宽度（默认值：0，表示不调整大小）。
• height：输出的所需高度（默认值：0，表示不调整大小）。
• x1、y1、x2、y2：整数裁剪坐标。默认值均为 0（不裁剪）。裁剪会在调整大小之前应用。x1 和 y1 的值可以为负数，这会在顶部和左侧添加留白；x2 和 y2 的值可以大于原始栅格尺寸，这会在右侧和底部添加留白。
• page：要转换的页码（对于多页文档，默认为 1）。
• alpha：布尔值（默认为 True；如果输出格式支持，则保留 alpha 通道）。如果为 false，则移除 alpha 通道，并用 bgColor 值替换像素。
• bgColor：背景颜色，用于填充留白，或在透明文档需要移除 alpha 通道时设置背景（默认值：“000000”，即黑色）。十六进制值前可以加“#”（网页颜色标识符）。

响应中将返回指定页面（或第 1 页）的图像，并设置正确的内容类型。如果 noRasterize 设为 true 且满足所有其他条件，则会返回所提交文档全部内容的 PDF。

/convert_url

描述：通过 HTTP(S) 下载远程文档，并将其发送到 TweekIT 转换流水线处理，无需调用方提供 base64 输入。

参数：

• apiKey：用于身份验证的 API 密钥。
• apiSecret：用于身份验证的 API 密钥。
• url：指向源文档的 HTTPS 或 HTTP URL。
• outfmt：所需的输出格式（例如 jpg、pdf、png）。

可选参数：

• inext：输入扩展名的覆盖值。省略时，服务端会根据 URL 路径或响应的 content-type 标头推断。
• noRasterize、width、height、x1、y1、x2、y2、page、alpha、bgColor：与 /convert 的语义相同。
• fetchHeaders：下载远程资源时要包含的 HTTP 标头对象（例如 Authorization）。

返回：与 /convert 相同——二进制图像/文件载荷会以 FastMCP Image/File 对象的形式呈现；JSON 响应则直接传递。

/search

描述：执行轻量级 DuckDuckGo 查询（无需 API 密钥），并返回 { query, results: [{ title, url, snippet }] }。此功能旨在帮助你查找公开文档或图像，然后将 URL 直接传入 /convert_url。如果你的环境需要使用其他提供方，可以替换 server.py 中的 HTTP 调用——docs/quickstarts.md 说明了原因及自定义位置。

参数：

• query：搜索查询字符串。
• max_results：要返回的结果数上限（默认值：5，最大值：10）。

/fetch

描述：获取 URL，并根据 content-type 返回内容。

参数：

• url：要获取的 http 或 https URL。

返回：

• 对于 image/* 响应，将图像内容作为 image 资源返回。
• 对于 application/pdf，将 PDF 作为 format="pdf" 的 resource 返回。
• 对于文本/JSON，将其作为包含 text 和元数据的 JSON 对象返回。
• 对于其他二进制内容，将其作为 format="bin" 的通用 resource 返回。

REST API 参考

请参阅文档 (https://tweekit.io/docs/rest-api/)，了解 MCP 服务如何与 TweekIT REST API 通信，以便将 MCP 请求代理到 TweekIT。

使用场景

以下是 TweekIT 可提升媒体处理可靠性和速度的常见工作流。每个示例都展示了 REST API 和 MCP 的使用方式。

1. 员工头像自动化处理

自动裁剪并调整图像尺寸，使其大小和格式保持一致。

MCP 示例

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "png",
      "outfmt": "png",
      "blob": "iVBORw0KGgoAAAANSUhEUgAAABwAAAA6CAYAAACj+Dm/AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAAsSAAALEgHS3X78AAAAHnRFWHRTb2Z0d2FyZQBFcXVpbGlicml1bSBNZWRpYVJpY2h7w4AAAAAB30lEQVRYhe2Xv0vDQBTHP4rQTRGhLqKiYt38MaggKIi46e6im2Rw7FJw7NAh4uAi+h/oIDgKnR3VQZROKiLYrZtOOiQH1+RevJQ0INwXQt7de7lP++7l7tJTq9XIU7250hzQAR3QAR3QAXMH3gM/wG0ewHtgNrSXgXo3gXUNprTSLaAPrBv6C4DXDeBBgm8ha+ArwT+RNJkl8BoY/SNmKiugB2xaxA1nBayQnEolY+GkBdqkUlescNIAPWBL8D0I/bHCSQOsCP3fwFx4jypWOLbApFRehfdPgy9WODbApKpsATuh/WHwxwrHBphUlRea/SLErKUBniGn8g3Y19qPQtx4GuBugu8y0q4KcRN6oy9hwFvkVDaAfoKtaQgYBAaE2KINsE6wkUqaDi9b+UBZAn5ht3Sl0bwyTHOYNQxgRAIad+kMNJY3sAAcQvscesQPQ7qaBPP7Bbxr/XeaXab9BKdrMQrcS4AdhYPZ6EkArkJ7SucNQRC8c7YwCNZW084xAPgKeI25Or+B4xQwpWehf0MBl4SAG+C0A6D0zIwCFg3OJrDdAUwBTaeAggI2DM6TDmFKcwT7pa6GApY0aAs4R17908gnyBTh+CX9tShlAIiqSuSH/+sPUgd0QAf8J8BfT2hGnMaA5CUAAAAASUVORK5CYII=",
      "noRasterize": false,
      "width": 30,
      "height": 30,
      "page": 1,
      "bgcolor": ""
    }
  }
}

等效的 REST 示例（需要单独的上传步骤）

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"width": 30, "height": 30, "fmt": "png"}'

2. KYC 照片导入与标准化

将身份证件照片处理成标准格式，以便进行自动验证。

MCP 示例

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "jpg",
      "outfmt": "webp",
      "blob": "{Your base64 encoded photo}",
      "width": 600,
      "height": 600,
      "bgcolor": "FFFFFF"
    }
  }
}

等效的 REST 示例

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"width": 600, "height": 400, "fmt": "webp", "bgcolor": "#FFFFFF"}'

3. 社交媒体和电子商务图像尺寸调整

生成符合平台要求的商品图像，确保宽高比和背景填充正确。

MCP 示例

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "jpg",
      "outfmt": "jpg",
      "blob": "{Your base64 encoded photo}",
      "width": 1080,
      "height": 1080,
      "bgcolor": "FFFFFF"
    }
  }
}

等效的 REST 示例

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"width": 1080, "height": 1080, "fmt": "jpg", "bgcolor": "#FFFFFF"}'

4. 跨平台资源转换

在不同格式之间转换文件，确保其兼容不同工具和工作流。

MCP 示例

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "{filename extension of the input doc}",
      "outfmt": "webp",
      "blob": "{Your base64 encoded document}"
    }
  }
}

等效的 REST 示例

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"fmt": "webp"}'

5. 将多页文档转换为 PDF

将复杂文档或旧版文件类型从原始格式转换为 PDF 文件，以便兼容当前的 AI 工作流。

MCP 示例

{
  "method": "tools/call",
  "params": {
    "name": "convert",
    "arguments": {
      "apiKey": "{Your TweekIT API key}",
      "apiSecret": "{Your TweekIT API secret}",
      "inext": "{filename extension of the input doc}",
      "outfmt": "pdf",
      "noRasterize": true,
      "blob": "{Your base64 encoded document}"
    }
  }
}

等效的 REST 示例

curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -d '{"fmt": "pdf", noRasterize: true}'

显式清理文档（REST API）

若要在 20 分钟自动过期前立即删除文档及其所有关联文件，请使用 DELETE 端点。当用户在会话中途取消工作流时，此功能很有用。MCP delete_document 工具会封装此调用。

curl -X DELETE "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
  -H "apikey: {Your API Key}" \
  -H "apisecret: {Your API Secret}"

**注意：**无论如何，文档都会在 20 分钟后自动过期。显式删除是可选的，但建议在对安全性敏感的工作流中使用。

演示 + 查看代码

TweekIT 提供了一个支持 MCP 的交互式演示，你可以在浏览器中尝试上传、预览和转换工作流，然后查看在自己的项目中重现这些操作所需的准确代码。

交互式 Tweekit 演示

打开在线演示：

1. 上传任意受支持的文件。
2. 预览调整大小、裁剪、背景填充和格式转换等处理效果。
3. 下载处理后的输出。

上传预览界面

演示提供拖放或点击上传界面，供你选择文件。上传后，你会看到：

• 文件名和类型。
• 生成的 DocId（20 分钟后过期）。
• 原始图像预览。

转换界面

在浏览器中直接调整转换参数：

• 调整尺寸。
• 裁剪区域（矩形或椭圆形）。
• 输出格式。
• 填充背景颜色。

更改会通过与你的应用将调用的相同 REST 端点实时应用。

自动生成代码选项卡

演示中的每项操作都可显示相应代码，支持：

• Node.js

  await fetch(`https://www.tweekit.io/tweekit/api/image/preview/${docId}`, {
    method: 'POST',
    headers: { "apikey": "{Your API Key}", "apisecret": "{Your API Secret}" },
    body: JSON.stringify({ width: 300, height: 300, fmt: 'png' })
  });
  

• curl

  curl -X POST "https://dapp.tweekit.io/tweekit/api/image/{docId}" \
    -H "apikey: {Your API Key}" \
    -H "apisecret: {Your API Secret}" \
    -H "Content-Type: application/json;charset=UTF-8" \
    -d '{"width": 300, "height": 300, "fmt": "png"}'
  

错误处理与故障排除

使用 TweekIT 构建稳健的 MCP 工作流，意味着要预判并处理常见错误场景。API 会返回明确的 HTTP 状态码和错误载荷，以便你的客户端或 MCP 操作做出适当响应。

常见问题

格式错误

• 原因：文件格式不受支持，或请求的输出格式无效。

• 解决方法：查看文档中的受支持文件格式列表。确保转换请求使用有效的 fmt 值。

• HTTP 状态：400 Bad Request

• 错误示例：

  {
    "error": "invalid_format",
    "message": "The requested format is not supported."
  }
  

超出配额

• 原因：已达到每月 API 调用限额。

• 解决方法：升级到更高级别的套餐，或等待配额重置。

• HTTP 状态：429 Too Many Requests

• 错误示例：

  {
    "error": "rate_limit_exceeded",
    "message": "You have reached your 10,000 call monthly limit."
  }
  

建议的重试与回退模式

• 重试：对于暂时性网络错误（5xx），采用指数退避，最多重试 3 次。
• 回退：如果转换失败，则改为提供原始文件或缓存的先前版本。
• 优雅降级：对于配额限制，显示对用户友好的消息，并提供升级套餐链接。

使用 Tweekit API 请求日志进行调试

在 MCP 上下文中使用 TweekIT 时：

1. TweekIT API 调用请求会记录在你的 tweekit.io 账户中，每个正在使用的密钥下都有相应日志。
2. 如果 MCP 请求失败，会返回相应响应。
3. 查看 MCP 服务配置中由你指定的控制台输出。

高级主题

对于希望让 TweekIT 不止用于简单转换的团队，这些高级技巧有助于更深入地集成到 AI 流水线、提升性能并强化安全性。

与 AI 流水线集成

TweekIT 可作为 AI 工作流的预处理层，确保输入内容在传递给下游模型之前具有正确的格式和尺寸。与其遇到错误或糟糕／无法完成的转换，不如使用 tweekit，确保文件能够按预期使用。

示例

• 图像转视频：在将所有帧传递给视频合成模型之前，对其进行规范化。
• 图像转图像：将任意文件规范化，包括任何文档或 pdf 的首页、camera raw、tiff、psd、illustrator 等各种格式，转换为 LLM 可处理的 .png 或 .jpg。
• 风格迁移：调整图像大小并转换格式，使其符合模型预期的输入尺寸。
• OCR 流水线：将文档转换为高对比度 PNG，以提高文本识别准确率。
• 专业格式（即 Adobe Illustrator）导入：转换为可用图像格式，以便渲染复杂的 PDF 文档，而不是失败或得到无法使用的结果。
• Office 文档、旧版及复杂格式转 PDF：现在，各类 Word 文件（.doc、.docm、.docx、.dot、.ppt、.vso）都可以转换为标准 PDF，供大多数 AI LLM 导入。

在 MCP 中，先串联 TweekIT 转换，再调用 AI 模型操作。

性能调优

• 缩减输出大小：使用 fmt (rest) outfmt (MCP)，并采用 webp 等便于压缩的格式，以加快交付速度。
• 尽量减少转换步骤：将转换操作合并到一个请求中，而不是多次预览。

安全加固

• API 密钥管理：定期轮换密钥，并尽可能限制其权限范围。
• 反向代理密钥：使用服务端代理注入凭据，避免凭据暴露在浏览器中。
• CORS 和域名限制：配置账户，仅接受来自可信域名的组件调用。
• 缩短 DocId 生命周期：依靠默认的 20 分钟有效期，减少上传文件暴露的风险。（仅适用于 REST API——对于 MCP，文件仅在处理期间使用，之后会被清除）

注册目录准备情况

准备提交到 MCP 目录（Pulse、OpenAI、Anthropic 等）？请在 docs/mcp-pulse-checklist.md 中跟踪公开要求。检查清单涵盖：

• 所需材料（在线端点、插件代理、Claude bundle、文档、变更日志）
• 自动化测试要求（pytest、可选的预发布环境检查）
• 运营策略（密钥、监控、回滚、SLA）
• 提交材料（截图、日志、支持联系人、许可证参考）

每次提交前，请及时更新未完成任务部分。

资源

使用以下链接深入了解技术信息、定价详情和支持渠道。

• API 参考
  TweekIT REST API 文档
  完整的端点列表、参数、身份验证方式和示例代码。

• 组件 API 参考
  TweekIT 组件文档
  构造函数选项、属性、方法和事件监听器。

• 定价
  TweekIT 定价指南
  免费套餐详情、付费套餐级别和超额使用费率。

• Claude Desktop Bundle 指南
  docs/claude-bundle.md
  逐步打包说明、configure_claude_desktop.py 辅助工具，以及有关我们 Tier 1 无头节点的安全说明。

• 搜索工具和远程资源
  docs/quickstarts.md
  介绍由 DuckDuckGo 提供支持的 search 工具如何帮助你在运行 convert_url 前查找文件，并说明如何更换服务提供商。

• 支持联系 电子邮件：[email protected] 提交工单以获取技术帮助、解决账户问题或提出功能请求。

解决 Claude 的文件类型限制

问题：AI 工具的文件摄取限制

Claude、ChatGPT 和其他 AI 工具都内置了文件类型限制，导致你无法分析、提取或处理数百种常见文件格式。虽然 Claude 可以读取 PDF 和常见图像格式（PNG、JPEG、WebP），但它无法直接处理：

• 旧版 Microsoft Office 文档：DOC、XLS、PPT 及更早的二进制格式
• OpenDocument 格式：ODT、ODS、ODP
• Adobe 文件：PSD、AI、INDD
• CAD/设计文件：DWG、DXF、SKP
• 专业格式：EPS、TIFF、RAW 相机文件、专有格式
• 以及其他 400 多种文件类型

注意：虽然较新的 XML 格式（如 DOCX、XLSX、PPTX）可能有更好的支持，但旧版 Office 二进制格式（DOC、XLS、PPT）和专业格式仍会持续引发问题。

这会造成令人沮丧的工作流瓶颈：文件中有宝贵的内容，但 AI 工具却直接拒绝处理。

解决方案：TweekIT 文件格式启用器

TweekIT MCP 服务充当通用转换器，可将 450 多种文件格式转换为 Claude 兼容的格式（PDF、PNG、JPEG、WebP），从而解决这一问题。这意味着：

✅ 不再出现“文件类型不受支持”错误 ✅ 分析任何文档格式中的内容 ✅ 从旧文件中提取文本和数据 ✅ 在 AI 工作流中处理专业设计文件 ✅ 将 Office 文档转换为 AI 可读取的 PDF

AI 文件格式转换网页工具

我们创建了一款独立的网页转换工具，专为帮助 Claude、OpenAI 和其他 AI 工具的用户克服文件类型限制而设计：

位置：examples/web-converter/index.html

用途：在上传到 Claude、ChatGPT 或其他 AI 工具之前，将不受支持的文件类型转换为 AI 兼容格式（PDF、PNG、JPEG、WebP）

使用方法：

1. 在浏览器中打开 examples/web-converter/index.html
2. 输入你的 TweekIT API 凭据（可在 tweekit.io 免费获取凭据）
3. 上传任意文件格式（DOC、XLS、PSD、AI、DWG 等）
4. 选择输出格式（PDF、PNG、JPEG 或 WebP）
5. 下载转换后的文件
6. 将转换后的文件上传到 Claude

常见使用场景：

• 旧版 Word 文档 → PDF：将 DOC 文件转换为 PDF，供 Claude 分析
• 旧版 Excel 电子表格 → PNG：将 XLS 转换为图像，以便可视化数据
• 旧版 PowerPoint → PDF：将 PPT 演示文稿转换为 PDF，以提取内容
• 设计文件 → PNG：将 PSD、AI 或其他设计文件转换为可查看的图像
• CAD 文件 → PDF：将 DWG/DXF 文件转换为 PDF，以供技术审查
• 专有格式 → 标准格式：将特殊文件类型转换为通用标准格式

与 Claude Desktop 集成

如需在 Claude Desktop 中无缝集成，请安装 TweekIT MCP 服务：

{
  "mcpServers": {
    "tweekit": {
      "transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp" }
    }
  }
}

然后让 Claude 直接转换文件：

“使用 TweekIT 将这个 DOC 文件转换为 PDF，这样你就能读取它了”

Claude 会自动调用 TweekIT MCP 服务、转换文件，并返回 Claude 兼容的格式。

这为何重要

使用 TweekIT 之前：用户上传旧版 DOC 文件 → Claude 拒绝处理 → 用户手动转换 → 用户重新上传 → 工作流中断

使用 TweekIT 后：用户上传 DOC 文件 → Claude 调用 TweekIT → 文件转换为 PDF → Claude 读取文件 → 工作流无缝衔接

这消除了文件格式限制带来的困扰，让 Claude 几乎能够处理任何文件类型。