TweekIT MCP服务器
摄取几乎任何文件类型并将其转换为AI工作流
当前版本:v1.6.01
> 演示环境(2025年11月23日)
>
> - 演示UI: https://e2b-hackathon-demo-u7zpezrloq-uw.a.run.app
> - MCP端点: https://mcp.tweekit.io/mcp
> - Cloud Run修订版: stage-00002-qlr, tweekit-mcp-stage-00022-8kw
> AI代理和IDE用户: 专为MCP助手、IDE连接器(Cursor、Continue、Windsurf、v0)、CLI+插件工作流和Claude/ChatGPT/Groq集成而构建。这 convert, convert_url, doctype, fetch,以及 search 工具开箱即用400英镑 + 格式。
概述
使用TweekIT,您可以使用一致的API或小部件接口上传、预览、转换和下载400多种支持的文件类型。它通过自动标准化和为工作流程的下一步准备资产,消除了不可预测的输入格式的痛苦。
TweekIT是什么?
TweekIT是一种通用的媒体摄取和转换服务,旨在获取任何支持的文件,并在几秒钟内使其AI就绪。无论您是对格式进行规范化、调整资产大小,还是从复杂文档中提取单个页面,TweekIT都提供了一种一致的API第一种方法来获得所需的输出,而无需担心单个文件类型的特殊性。
为什么在MCP环境中使用它?
通过MCP工具集中的TweekIT,您的代理可以:
- 无故障地接受用户更广泛的输入
- 自动应用裁剪、调整大小、格式转换和背景更改等转换
- 将干净、即用型资产传递到人工智能工作流程的下一步,无需人工干预,即可修复我们都熟悉的持续的客户文件摄入故障
> 您在寻找克劳德的特定演练吗?看 解决Claude的文件类型限制 获取专用指南和基于浏览器的转换器。
示例场景
用户上传身份证的扫描PDF作为入职流程的一部分。您的MCP代理致电TweekIT:
- 将PDF转换为PNG图像
- 只裁剪到身份证
- 调整为标准300x300像素头像
- 将转换后的图像直接返回到验证管道中
整个过程在几秒钟内完成,您的工作流永远不会看到不兼容的文件格式。
关键能力
- 支持 400+ 用于无缝摄取和转换的文件类型, 利用经过二十多年改进的核心引擎来处理动态成像和视频处理。
- 无状态和API首次设计用于快速、可扩展的集成
- Widget或REST API访问,以适应任何应用程序架构
- 企业级安全,具有安全的密钥处理和短期资产存储
- 即时兼容性修复,可立即防止AI管道因输入格式错误而发生故障
现在试试
- AI文件格式启用程序 –基于浏览器的转换器,适用于Claude、OpenAI和其他AI工具(DOC、XLS、PSD、DWG→ PDF/PNG)
- 现场演示 –在浏览器中上传和转换文件
- 用例示例 –在网站上查看实用的工作流程和代码示例。 具体的MCP清单转换如下文第7节所示。
目录
- 概述
- 解决Claude的文件类型限制
- 需求
- 安装
- 快速入门
- 认证
- 服务器和主机
- 客户端兼容性
- 快速入门(克劳德桌面版)
- 快速入门(ChatGPT MCP)
- 快速入门(游标IDE)
- 快速入门(继续IDE)
- 费率限制和定价
- 核心概念
- MCP API参考
- REST API参考
- 用例
- 演示+显示代码
- 错误处理和故障排除
- 高级主题
- 注册表准备就绪
- 资源
需求
- Python 3.10或更高版本
- Docker(可选,用于容器化构建)
httpxHTTP请求库FastMCP用于工具注册和服务器功能
安装
- 克隆存储库:```bash
git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp
1. 安装依赖项:```bash
pip install -r requirements.txt
- 设置环境变量:
- 端口:服务器将运行的端口(默认值:8080)。
快速入门
第一步:注册
创建免费的TweekIT帐户,免费获得10000个API调用。\
在此处定价和注册 在管理帐户页面中生成您的API凭据并开始使用该服务。
步骤2:选择您的身份验证方法
TweekIT支持多种身份验证方法。然而,只有密钥/秘密对方法适用于MCP集成。
- API密钥和秘密 –MCP生产使用所需,更安全,更容易控制访问
注册后,您将在帐户仪表板中找到这些值。保护它们的安全,永远不要在客户端代码中暴露它们。
第3步:进行第一次API调用
下面是一个最小的json示例,它发送一个具有基本大小调整操作的图像,预览转换并返回结果。此示例使用API密钥和机密身份验证。
JSON是通过使用MCP Inspector和公开可用的MCP服务器捕获的。```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
}
### 第四步:实际操作
在编写任何代码之前,您可以直观地探索TweekIT。实时演示允许您上传文件、应用转换并立即下载结果。
- 打开实时演示
- 查看用例示例 用于真实的工作流和代码示例
## 认证
TweekIT支持多种身份验证方法(REST API,APP ID方法仅供使用)。设置API密钥和机密,以便在维护安全最佳实践的同时快速启动。
### 用于MCP服务器:API密钥+密钥
这是最安全、最灵活的选择。将其用于所有生产部署。
**步骤:**
1. 在您的TweekIT帐户设置中生成您的API密钥和秘密。
1. 安全地存储它们——永远不要承诺进行源代码控制。
1. 使用服务器端代码或反向代理将凭据注入请求中。
**安全提示:**
- 始终使用反向代理或其他服务器端方法来保护凭据。
- 切勿在客户端代码中嵌入机密。
**下一步:**\
一旦通过身份验证,您可以:
- 使用Base-64上传媒体作为请求的一部分
- 接收器输出
## 服务器和主机
### 托管就绪的MCP服务器
所有工具和资源都可以在这里使用,用于测试和免费试用:
- 公共MCP端点(HTTP传输): https://mcp.tweekit.io/mcp/
当前可用的资源名称为“version”。当前可用的工具名称为“doctype”、“convert”和“convert_url”。请参阅下面的参数,或查询MCP服务器,因为它将返回指示使用这些参数的元数据。
### 版本控制和内部版本号
该项目跟踪中的语义版本 `major.minor.build` 其中构建组件填充为两位数字(例如, `1.6.01`).使用 `scripts/bump_version.py` 要保持每个元数据文件对齐:```bash
# 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服务器,也可以连接到托管实例。建议使用本地选项进行开发和测试。
本地安装```bash
git clone https://github.com/equilibrium-team/tweekit-mcp.git
cd tweekit-mcp
pip install -r requirements.txt
**运行服务器:**```bash
uv run server.py
服务器将监听:
http://localhost:8080
配置选项
地方发展模式\
默认情况下, server.py 将绑定到 localhost 在端口8080上。您可以使用以下命令覆盖端口 PORT 环境变量:```bash
PORT=9090 uv run server.py
### 云运行部署
使用提供的脚本在Google Cloud Run上构建和部署容器化的阶段或生产服务。
先决条件:
- 谷歌云项目访问(`tweekitmcp-a26b6` 默认情况下)。
- `gcloud` CLI已通过身份验证(`gcloud auth login`)如果您的标准配置目录是只读的,则可以进行可写导出,例如 `export CLOUDSDK_CONFIG="$(pwd)/.gcloud-config"`.
使用Docker在本地运行容器(构建镜像 `tweekit-mcp-local:dev` 并绑定到 `8080`):```bash
bash scripts/deploy_cloud_run.sh local --version dev
部署到暂存(创建/更新 tweekit-mcp-stage 服务):```bash
bash scripts/deploy_cloud_run.sh stage --version 1.6.01
部署到生产环境(更新 `tweekit-mcp` 服务):```bash
bash scripts/deploy_cloud_run.sh prod --version 1.6.01
通过 --project 如果你需要覆盖活动 gcloud 配置,以及 --env-file 以YAML格式提供Cloud Run环境变量。
> 辅助脚本从不捆绑凭据。运行时,始终提供您自己的Google Cloud项目、地区和秘密来源;Equilibrium的stage/prod密钥位于受管理的秘密存储中,并被有意排除在此存储库之外。
>
> Firebase函数的Python依赖关系在部署时得到解决。 scripts/deploy_firebase.sh 将它们出售给 functions/packages/ 本地(gitignored目录),因此仓库保持轻量级。
客户端兼容性
- Claude:兼容(通过listTools发现工具;使用HTTP传输)。
- ChatGPT(OpenAI):兼容(提供所需工具:
search,fetch). - 游标:没有目标(没有公开工作区/文件工具)。
例子
- Claude Desktop(配置片段):```json
{
"mcpServers": {
"tweekit": {
"transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp/" }
}
}
}
- Claude工具调用(参数示例):```json
{
"name": "convert",
"arguments": {
"apiKey": "YOUR_KEY",
"apiSecret": "YOUR_SECRET",
"inext": "png",
"outfmt": "webp",
"blob": "",
"width": 300,
"height": 300
}
}
- OpenAI(节点,使用MCP TypeScript客户端):```ts
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,快速调用):```py
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": "",
},
)
print(out)
asyncio.run(main())
快速入门(克劳德桌面版)
在Claude Desktop中使用Tweekit有两种方法:
- 托管HTTP服务器 –指向克劳德
https://mcp.tweekit.io/mcp/通过设置→ 连接器→ 高级→ 开发人员模式→ “添加HTTP服务器。” - 本地捆绑包(
.mcpb) –安装打包的stdio服务器,以便您可以离线工作或发布精心策划的构建。
我们通过以下方式维护本地捆绑包 scripts/build_claude_bundle.py 以及被引导的助手 scripts/configure_claude_desktop.py助手遍历版本选择、包生成、, dxt 清单验证,最后提醒您导入结果 dist/tweekit-claude.mcpb。它还重申了我们的生产层 1 无头节点在SAS内部均衡拥有的CPUcoin企业矿工上运行 70 / ISO 27001 兼容的数据中心——本地捆绑包反映了相同的功能集。
连接后(任一方法):
- 问:“通过doctype列出支持的输入类型。”
- 或者用你的密钥/秘密和base64 blob调用convert:```json
{
"name": "convert",
"arguments": { "apiKey": "…", "apiSecret": "…", "inext": "png", "outfmt": "webp", "blob": "" }
}
### 快速入门(ChatGPT MCP)
如果您的ChatGPT环境支持MCP工具,请添加一个指向公共端点的HTTP MCP服务器。
1. 配置服务器:URL `https://mcp.tweekit.io/mcp/` (HTTP传输)
1. 在聊天中使用工具:
- 文档类型```json
{ "name": "doctype", "arguments": { "ext": "pdf", "apiKey": "…", "apiSecret": "…" } }
- 转换```json
{
"name": "convert",
"arguments": {
"apiKey": "…",
"apiSecret": "…",
"inext": "png",
"outfmt": "txt",
"blob": ""
}
}
### 快速入门(游标IDE)
游标从加载MCP配置 `~/.cursor/mcp.json`。要启用托管的TweekIT服务器,请合并以下代码段(也发布在 `configs/cursor-mcp.json`)在您现有的文件中:```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,并为队友显示“添加到游标”深度链接。
快速入门(继续IDE)
Continue(VS Code/JetBrains)将MCP服务器存储在 ~/.continue/config.json.在下面添加TweekIT服务器 mcpServers (准备在以下位置复制JSON configs/continue-mcp.json):```json
{
"mcpServers": {
"tweekit": {
"type": "streamable-http",
"url": "https://mcp.tweekit.io/mcp",
"headers": {
"ApiKey": "${TWEEKIT_API_KEY}",
"ApiSecret": "${TWEEKIT_API_SECRET}"
}
}
}
}
保存配置后:
1. 重新加载继续,以便它拾取新的MCP条目。
1. 使用继续“工具”面板调用 `doctype`, `convert`,或 `convert_url` 具有适当的参数。
1. 记录工作区特定的凭证步骤,以便队友可以快速连接。
## 费率限制和定价
TweekIT提供了一个慷慨的免费等级,因此您可以免费探索和整合。
### 免费等级
- **10000个API调用** 免费包括在内。
- 完全访问所有核心上传、预览和下载功能。
- 开始时不需要信用卡。
### 付费计划
如果您超过免费等级限制,您可以随时升级到付费计划。\
有关详细信息,请参阅完整的定价指南。您必须拥有令牌密钥对才能使用MCP服务器:\
https://www.tweekit.io/pricing/
### 处理速率限制错误
当您达到每月配额时,API将以HTTP响应 `429 Too Many Requests` 状态。
**MCP集成提示**:\
您的MCP客户应该:
1. 抓住 `429` 响应。
1. 向用户显示明确的错误信息。
1. 建议立即升级计划以继续。
## 核心概念
了解这些核心概念将帮助您在MCP工作流程中充分利用TweekIT。
### 请求包括Base-64内容→ 响应包括Base-64结果
TweekIT MCP Server使用这种简单、无状态和安全的管道来处理文档请求。
### 变换
TweekIT支持广泛的转换,在预览时应用:
- **调整大小** 按宽度和高度(如果只发送一个参数,则会自动计算另一个参数以保持纵横比)
- **输出格式** 将文件格式更改为其他文件类型
- **背景颜色** 填充透明或填充区域
- **无光栅化** 当与PDF输出格式结合使用时,将整个文本文档转换为PDF文件,以便上游AI摄取。
### 无状态处理
TweekIT不会持久存储您的文件。
- 每次请求后,作业文件夹和临时存储都会被清除。
- 这种设计确保了最小的存储开销和敏感文件的更强隐私。
- 传输中的数据通过SSL加密。
## MCP参考
### 资源
#### /版本
说明:
获取TweekIT API的当前版本。不接受任何参数。
#### /服务器版本
说明:
返回此MCP服务器的版本字符串(例如。, `1.6.01`).不接受任何参数。
### 工具
#### /doctype
说明:
检索支持的输入文件格式列表或将文件扩展名映射到其文档类型。如果返回的文档类型字段为空,则不支持读取该格式。
参数:
- 扩展名:文件扩展名(例如jpg、docx)。可选,默认为“\*”。(返回所有支持的输入文档类型)。
- apiKey:用于身份验证的API密钥。
- apiSecret:用于身份验证的API机密。
#### /转换
说明:将base64编码的文档转换为指定的输出格式。
参数:
- apiKey:用于身份验证的API密钥。
- apiSecret:用于身份验证的API机密。
- inext:输入文件扩展名(例如jpg、png、doc、docx等)。
- outmt:所需的输出格式(例如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:boolean(默认为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。
- outmt:所需的输出格式(例如jpg、pdf、png)。
可选:
- inext:输入扩展名的覆盖。如果省略,服务器将从URL路径或响应内容类型标头中推断出来。
- noRasterize、width、height、x1、y1、x2、y2、page、alpha、bgColor:语义与 `/convert`.
- fetchHeaders:下载远程资源时要包含的HTTP标头对象(例如,Authorization)。
退货:与 `/convert`--二进制图像/文件有效载荷表面为FastMCP `Image`/`File` 物体;JSON响应被传递。
#### /搜索
描述:执行轻量级DuckDuckGo查询(不需要API键)并返回 `{ query, results: [{ title, url, snippet }] }`。它旨在帮助您定位公共文档或图像,然后将URL直接馈送到 `/convert_url`。如果您的环境需要其他提供程序,请交换HTTP调用 `server.py`—`docs/quickstarts.md` 解释了基本原理以及在哪里进行定制。
参数:
- query:搜索查询字符串。
- max_results:返回的最大结果数(默认值:5,最大值:10)。
#### /取回
描述:获取URL并根据内容类型返回内容。
参数:
- 网址:The `http` 或 `https` 要获取的URL。
退货:
- 图像内容为 `image` 资源用于 `image/*` 响应。
- PDF格式 `resource` 随着 `format="pdf"` 为了 `application/pdf`.
- 文本/JSON作为JSON对象 `text` 以及元数据。
- 其他二进制作为泛型 `resource` 随着 `format="bin"`.
## REST API参考
请参阅以下文档(https://tweekit.io/docs/rest-api/)以了解MCP服务器如何与TweekIT REST API对话,从而将MCP请求代理到TweekIT。
## 用例
以下是TweekIT提高媒体处理可靠性和速度的常见工作流程。每个示例都显示了REST API和MCP的使用模式。
### 1.员工头部自动化
自动将图像裁剪和调整大小为一致的大小和格式。
**MCP示例**```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": ""
}
}
}
等效REST示例(需要单独的上传步骤)```bash
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示例**```json
{
"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示例```bash
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示例**```json
{
"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示例```bash
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示例**```json
{
"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示例```bash
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示例**```json
{
"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示例```bash
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. 上传任何支持的文件。
1. 预览转换,如调整大小、裁剪、背景填充和格式转换。
1. 下载转换后的输出。
### 上传预览界面
演示提供了一个拖放或点击上传界面,用于选择文件。上传后,您将看到:
- 文件名和类型。
- 生成 **DocId** (20分钟后到期)。
- 原始图像预览。
### 转换UI
直接在浏览器中调整变换参数:
- 调整尺寸。
- 作物面积(矩形或椭圆形)。
- 输出格式。
- 背景颜色填充。
使用应用程序将调用的相同REST端点实时应用更改。
### 自动生成代码选项卡
演示中的每个操作都可以显示相应的代码:
- **Node.js**```javascript
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' })
});
- 卷曲```bash
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` 价值。
- **状态码**: `400 Bad Request`
- **错误示例**:```json
{
"error": "invalid_format",
"message": "The requested format is not supported."
}
配额超出
-
原因:达到每月API调用限制。
-
决心:升级到更高的计划或等待配额重置。
-
状态码:
429 Too Many Requests -
错误示例:```json
{
"error": "rate_limit_exceeded",
"message": "You have reached your 10,000 call monthly limit."
}
### 推荐的重试和回退模式
- **重试**:用于瞬态网络错误(`5xx`),使用指数回退最多重试3次。
- **后备方案**:如果转换失败,则返回到传递原始文件或缓存的先前版本。
- **故障弱化**:关于配额限制,请显示一条用户友好的消息和一个链接 升级你的计划.
### 使用Tweekit API请求日志进行调试
在MCP环境中使用TweekIT时:
1. TweekIT API调用请求记录在您的 tweetkit.io 每个正在使用的密钥下的帐户。
1. 如果MCP请求失败,将返回适当的响应。
1. 检查您在MCP服务器配置中定义的控制台输出。
## 高级主题
对于推动TweekIT超越简单转换的团队来说,这些先进技术可以帮助您更深入地集成到AI管道中,提高性能并加强安全性。
### 与AI管道集成
TweekIT可以作为人工智能工作流程的预处理层,确保输入在输入到下游模型之前具有正确的格式和大小。只需使用tweetkit,而不是错误或错误/不存在的转换,以确保文件可以按预期使用。
**例子**
- **图像转视频**:在将所有帧传递给视频合成模型之前,对其进行归一化。
- **图像到图像**:将任何文件(包括任何文档或pdf、相机原始文件、tiff、psd、插图等的第一页)标准化为LLM可以处理的.png或.jpg格式。
- **风格迁移**:调整图像大小并重新格式化,以匹配模型的预期输入尺寸。
- **OCR管道**:将文档转换为高对比度PNG,以提高文本识别的准确性。
- **专业格式(即Adobe Illustrator)摄取**:转换为可用的图像格式,以呈现复杂的PDF文档,而不是失败或收到不可用的结果。
- **Office文档、传统和复杂格式转换为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等)?跟踪以下公共要求 `docs/mcp-pulse-checklist.md`检查表包括:
- 所需工件(实时端点、插件代理、Claude捆绑包、文档、更改日志)
- 自动化测试预期(`pytest`,可选分段扫描)
- 操作策略(机密、监控、回滚、SLA)
- 提交数据包资产(屏幕截图、日志、支持联系人、许可证参考)
在每次提交之前,保持未完成任务部分的最新状态。
## 资源
使用以下链接获取更深入的技术参考、定价详细信息和支持。
- **api参考**\
TweekIT REST API文档\
完整的端点列表、参数、身份验证方法和示例代码。
- **小工具API参考**\
TweekIT小部件文档\
构造函数选项、属性、方法和事件侦听器。
- **定价**\
TweekIT定价指南\
免费等级详情、付费计划等级和超龄率。
- **Claude桌面捆绑包指南**\
`docs/claude-bundle.md`\
分步包装说明 `configure_claude_desktop.py` 我们Tier的助手和安全上下文 1 无头节点。
- **搜索工具和远程资产**\
`docs/quickstarts.md`\
解释DuckDuckGo是如何支持的 `search` 该工具可帮助您在运行前定位文件 `convert_url`,以及关于交换提供商的说明。
- **支持联系方式**
电子邮件:support@tweekit.io
提交技术帮助、帐户问题或功能请求的工单。
## 解决Claude的文件类型限制
### 问题:AI工具文件摄入限制
Claude、ChatGPT和其他人工智能工具具有内置的文件类型限制,阻止您分析、提取或处理数百种常见的文件格式。虽然克劳德可以阅读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+其他文件类型**
*注意:虽然DOCX、XLSX、PPTX等较新的基于XML的格式可能有更好的支持,但传统的二进制Office格式(DOC、XLS、PPT)和专用格式始终会导致问题。*
这造成了一个令人沮丧的工作流程瓶颈:你有一个包含有价值内容的文件,但你的人工智能工具只是拒绝了它。
### 解决方案:TweekIT文件格式启用程序
✅ **不再出现“不支持的文件类型”错误**
✅ **分析任何文档格式的内容**
✅ **从旧文件中提取文本和数据**
✅ **在AI工作流程中使用专业设计文件**
✅ **将办公文档转换为AI可读的PDF**
### AI文件格式启用程序Web工具
我们创建了一个独立的web转换器,专门用于帮助Claude、OpenAI和其他AI工具的用户克服文件类型限制:
**位置**: `examples/web-converter/index.html`
**目的**:在上传到Claude、ChatGPT或其他AI工具之前,将不支持的文件类型转换为AI兼容的格式(PDF、PNG、JPEG、WebP)
**如何使用**:
1. 打开 `examples/web-converter/index.html` 在浏览器中
1. 输入您的TweekIT API凭据(在获取免费凭据 tweetkit.io)
1. 上传任何文件格式(DOC、XLS、PSD、AI、DWG等)
1. 选择输出格式(PDF、PNG、JPEG或WebP)
1. 下载转换后的文件
1. 将转换后的文件上传到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服务器:```json
{
"mcpServers": {
"tweekit": {
"transport": { "type": "http", "url": "https://mcp.tweekit.io/mcp/" }
}
}
}
然后让Claude直接转换文件:
> “使用TweekIT将此DOC文件转换为PDF,以便您阅读”
Claude将自动调用TweekIT MCP服务器,转换文件,并返回与Claude兼容的格式。
为何这很重要
TweekIT之前:用户上传旧DOC文件→ 克劳德拒绝了→ 用户手动转换→ 用户重新上传→ 工作流程中断
使用TweekIT:用户上传DOC文件→ 克劳德打电话给TweekIT→ 文件转换为PDF→ 克劳德读它→ 无缝工作流程
这消除了文件格式限制的困扰,使Claude几乎可以处理任何文件类型。
