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幾乎可以處理任何文件類型。