Tweekit MCP

🚀 TweekIT MCP Server

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

TweekIT MCP Server是一款用于AI工作流的通用媒体转换器，能在数秒内让任何文件做好处理准备。它基于Equilibrium的MediaRich Server强大的内容处理引擎构建，该技术自2000年以来不断发展，受到全球大型门户网站和媒体公司的信赖。TweekIT汲取了处理复杂媒体数十年的专业经验，其传承包括著名的DeBabelizer。

🚀 快速开始

第一步：注册

创建免费的TweekIT账户，即可免费获得10,000次API调用额度。 点击此处查看定价并注册，在“管理账户”页面生成API凭证，即可开始使用服务。

第二步：选择认证方式

TweekIT支持多种认证方式，但只有密钥/密钥对方式适用于MCP集成。

• API密钥和密钥：MCP生产环境必需，更安全且易于控制访问权限。

注册后，您可以在账户仪表盘找到这些值。请妥善保管，切勿在客户端代码中暴露。

第三步：进行首次API调用

以下是一个最小工作JSON示例，它发送一张图片并执行基本的调整大小操作，预览转换结果并返回结果。此示例使用API密钥和密钥认证。

该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
}

第四步：亲身体验

在编写代码之前，您可以直观地探索TweekIT。实时演示允许您上传文件、应用转换并立即下载结果。

• 打开实时演示
• 查看用例示例，了解实际工作流和代码示例

✨ 主要特性

• 支持400多种文件类型：无缝摄取和转换，利用经过二十多年优化的核心引擎处理动态成像和视频处理。
• 无状态和API优先设计：实现快速、可扩展的集成。
• 支持小部件或REST API访问：适应任何应用程序架构。
• 企业级安全：具备安全的密钥处理和短期资产存储功能。
• 即时兼容性修复：立即防止因输入格式错误导致的AI管道故障。

📦 安装指南

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

# 使用pip
pip install tweekit-mcp

# 使用uv
uv pip install tweekit-mcp

# 使用pipx（隔离环境）
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            # 或者: pip install -r requirements.txt

根据需要设置环境变量：

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

💻 使用示例

基础用法

# 保持原始代码和注释不变
# 此JSON示例展示了如何发送图片并执行基本调整大小操作
{
    "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
}

高级用法

# 高级场景说明：在AI工作流中，将TweekIT作为预处理层，确保输入文件在正确的格式和大小后再传递给下游模型。
# 例如，在图像到视频的工作流中，在将所有帧传递给视频合成模型之前进行归一化处理。
# 以下是一个示例，展示如何在MCP中链式调用TweekIT转换，然后调用AI模型操作。
# 假设已经有一个AI模型操作函数 call_ai_model
# 首先进行TweekIT转换
{
    "method": "tools/call",
    "params": {
        "name": "convert",
        "arguments": {
            "apiKey": "{Your TweekIT API key}",
            "apiSecret": "{Your TweekIT API secret}",
            "inext": "png",
            "outfmt": "png",
            "blob": "{Your base64 encoded image}",
            "width": 300,
            "height": 300,
            "page": 1,
            "bgcolor": ""
        }
    },
    "jsonrpc": "2.0",
    "id": 5
}
# 然后调用AI模型操作
call_ai_model(transformed_image)

📚 详细文档

目录

• 概述
• 解决Claude的文件类型限制
• 要求
• 安装
• 快速开始
• 认证
• 服务器和托管
• 客户端兼容性
  • Claude桌面版快速开始
  • ChatGPT MCP快速开始
  • Cursor IDE快速开始
  • Continue IDE快速开始
• 速率限制和定价
• 核心概念
• MCP参考
• REST API参考
• 用例
• 演示 + 代码展示
• 错误处理和故障排除
• 高级主题
• 注册表就绪性
• 资源

要求

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

认证

TweekIT支持多种认证方式，但只有密钥/密钥对方式适用于MCP集成。

• API密钥和密钥：MCP生产环境必需，更安全且易于控制访问权限。

注册后，您可以在账户仪表盘找到这些值。请妥善保管，切勿在客户端代码中暴露。

服务器和托管

托管就绪的MCP服务器

所有工具和资源均可在此处获取，用于测试和免费试用：

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

当前可用的资源名称为'version'。当前可用的工具名称为'doctype'、'convert'和'convert_url'。有关参数，请参见下文，或查询MCP服务器，它将返回使用说明的元数据。

版本控制和构建编号

项目以主版本号.次版本号.构建号格式跟踪语义版本，构建号部分填充为两位数（例如，1.6.01）。使用scripts/bump_version.py保持所有元数据文件一致：

# 仅增加构建号（例如，1.6.01 -> 1.6.02）
python scripts/bump_version.py --bump-build

# 设置显式版本，必要时重置构建计数器
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

云运行部署

使用提供的脚本在Google Cloud Run上构建和部署容器化的阶段或生产服务。

先决条件：

• Google Cloud项目访问权限（默认项目ID为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 <项目ID>，并使用--env-file <路径>以YAML格式提供Cloud Run环境变量。

辅助脚本从不捆绑凭据。运行这些脚本时，请始终提供自己的Google Cloud项目、区域和密钥源；Equilibrium的暂存/生产密钥存储在托管的密钥存储中，本仓库有意排除这些信息。

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

客户端兼容性

• Claude：兼容（通过listTools发现工具；支持HTTP传输）。
• ChatGPT（OpenAI）：兼容（提供所需工具：search、fetch）。
• Cursor：不支持（未暴露工作区/文件工具）。

示例

• Claude桌面版（配置片段）

{
    "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桌面版快速开始

在Claude桌面版中使用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。它还会再次强调，我们的生产一级无头节点运行在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（或手动导出变量）。
• 重启Cursor并运行“列出工具”，确认version、doctype、convert和convert_url可用。
• 可选：在内部托管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. 记录特定工作区的凭证步骤，以便团队成员快速连接。

速率限制和定价

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服务器使用这种简单、无状态且安全的管道处理文档处理请求。

转换

TweekIT支持广泛的转换，在预览时应用：

• 调整大小：按宽度和高度调整（如果只发送一个参数，另一个将自动计算以保持纵横比）。
• 输出格式更改：将文件格式更改为不同的文件类型。
• 背景颜色填充：用于透明或填充区域。
• 不光栅化：与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路径或响应内容类型头中推断。
• 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并根据内容类型返回内容。

参数：

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

返回：

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

REST API参考

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

用例

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

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": ""
        }
    },
    "jsonrpc": "2.0",
    "id": 4
}

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

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

演示 + 代码展示

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://www.tweekit.io/tweekit/api/image/preview/{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的第一页、相机原始文件、TIFF、PSD、Illustrator等）归一化为您的LLM可以处理的.png或.jpg格式。
• 风格迁移：调整图像大小和格式，使其符合模型预期的输入尺寸。
• OCR管道：将文档转换为高对比度的PNG，以提高文本识别准确性。
• 专业格式（如Adobe Illustrator）摄取：将其转换为可用的图像格式，以渲染复杂的PDF文档，而不是失败或得到不可用的结果。
• 办公文档、旧格式和复杂格式转换为PDF：各种类型的Word文件（.doc、.docm、.docx、.dot、.ppt、.vso）现在可以转换为标准PDF，以便大多数AI LLM摄取。

在MCP中，在调用AI模型操作之前链式调用TweekIT转换。

性能调优

• 减小输出大小：使用fmt (rest) outfmt (MCP)和压缩友好的格式（如webp），以实现更快的传输。
• 最小化转换步骤：将转换链式组合到一个请求中，而不是多次预览。

安全强化

• API密钥管理：定期轮换密钥，并在可能的情况下限制范围。
• 反向代理密钥：使用服务器端代理注入凭据，避免将其暴露在浏览器中。
• CORS和域名限制：配置您的账户，仅接受来自受信任域名的小部件调用。
• 短DocId生命周期：依赖默认的20分钟过期时间，限制上传文件的暴露时间。（仅适用于Rest API - 对于MCP，文件仅在处理期间使用，处理完成后即被清除）

注册表就绪性

准备好应对MCP注册表（Pulse、OpenAI、Anthropic等）了吗？请跟踪中的公共要求。该清单涵盖：

• 必需的工件（实时端点、插件代理、Claude包、文档、更新日志）
• 自动化测试期望（pytest，可选的暂存扫描）
• 操作策略（密钥、监控、回滚、SLA）
• 提交数据包资产（截图、日志、支持联系人、许可证参考）

在每次提交之前，保持未完成任务部分的最新状态。

资源

使用以下链接获取更深入的技术参考、定价详细信息和支持。

• API参考 TweekIT REST API文档 完整的端点列表、参数、认证方法和示例代码。
• 小部件API参考 TweekIT小部件文档 构造函数选项、属性、方法和事件监听器。
• 定价 TweekIT定价指南 免费套餐详情、付费计划层级和超额费率。
• Claude桌面版包指南 分步打包说明、configure_claude_desktop.py辅助脚本，以及我们一级无头节点的安全上下文。
• 搜索工具和远程资产 解释基于DuckDuckGo的search工具如何帮助您在运行convert_url之前定位文件，以及更换提供商的注意事项。
• 支持联系 邮箱：support@tweekit.io 提交技术帮助请求、账户问题或功能请求的工单。

解决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、相机原始文件、专有格式
• 以及400多种其他文件类型

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

这造成了令人沮丧的工作流瓶颈：您有一个包含有价值内容的文件，但您的AI工具却直接拒绝它。

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

TweekIT MCP服务器通过充当通用翻译器解决了这个问题，它可以将450多种文件格式转换为Claude兼容的格式（PDF、PNG、JPEG、WebP）。这意味着： ✅ 不再出现“不支持的文件类型”错误 ✅ 分析任何文档格式的内容 ✅ 从旧版文件中提取文本和数据 ✅ 在AI工作流中处理专业设计文件 ✅ 将办公文档转换为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桌面版集成

要在Claude桌面版中无缝集成，请安装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几乎可以处理任何文件类型。