TweekIT MCP Server

TweekIT MCP Server

あらゆるファイル形式を取り込み、AI ワークフローに変換

現在のバージョン：v1.6.1

🤖 Claude ユーザー向け：「未対応のファイル形式」というエラーにお困りですか？Claude のファイル形式制限を解決する方法をご覧ください。ブラウザー上で使えるこのツールは、450 種類以上の形式（DOC、XLS、PSD、DWG など）を数秒で Claude 対応ファイルに変換します。

概要

TweekIT MCP Server は、AI ワークフロー向けの汎用メディア変換ツールで、あらゆるファイルを数秒で処理可能な状態にします。2000 年から開発され、世界中の大規模ポータルやメディア企業から信頼されている Equilibrium の MediaRich Server の堅牢なコンテンツ処理エンジンを基盤としています。TweekIT は、著名な DeBabelizer を含む実績に裏打ちされた、複雑なメディア処理における数十年の専門知識を提供します。

TweekIT を使えば、一貫した API またはウィジェットインターフェースから、400 種類以上の対応ファイル形式をアップロード、プレビュー、変換、ダウンロードできます。入力形式が予測できない問題を解消し、アセットを自動的に正規化して、ワークフローの次のステップに備えます。

TweekIT とは？

TweekIT は、対応するあらゆるファイルを数秒で AI 対応にするために設計された、汎用メディア取り込み・変換サービスです。形式の正規化、アセットのサイズ変更、複雑なドキュメントからの単一ページの抽出など、個々のファイル形式の癖を気にせず、必要な出力を一貫した API ファーストの方法で取得できます。

MCP のコンテキストで使う理由

Model Context Protocol（MCP）ワークフローにおいて、TweekIT はメディア向けの汎用変換ツールとして機能します。AI エージェントと、エージェントが直面する予測不能な実世界のファイルとの間に位置し、処理の前にすべてのアセットを互換性のある標準形式へ変換します。これは GitHub Actions がソフトウェアの自動化を効率化するのと似ていますが、AI パイプラインにおけるメディア処理に適用したものです。

MCP ツールセットに TweekIT を加えると、エージェントは次のことができます。

• 失敗することなく、より幅広いユーザー入力を受け付ける
• トリミング、サイズ変更、形式変換、背景の変更などの変換を自動的に適用する
• いつも直面する、顧客からのファイル取り込み失敗を手作業で修正することなく、クリーンでそのまま使えるアセットを AI ワークフローの次のステップに渡す

🤖 Claude ユーザー向け：TweekIT を使って Claude に組み込まれたファイル形式の制限を解消する方法と、スタンドアロンのウェブ変換ツールについては、Claude のファイル形式制限を解決する方法をご覧ください。

使用例

オンボーディング手続きの一環として、ユーザーが ID カードをスキャンした PDF をアップロードします。MCP エージェントは TweekIT を呼び出して、次の処理を行います。

• PDF を PNG 画像に変換する
• ID カードだけを切り抜く
• 標準的な 300x300 ピクセルの顔写真にサイズを変更する
• 変換した画像を検証パイプラインに直接返す

この処理はすべて数秒で完了し、ワークフローが互換性のないファイル形式を扱うことはありません。

主な機能

• 400 種類以上のファイル形式に対応し、シームレスに取り込み・変換できます。20 年以上にわたって改良され、動的な画像処理と動画処理に対応するコアエンジンを活用しています。
• 高速でスケーラブルな連携を実現する、ステートレスで 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 呼び出しを使って始めましょう。
こちらから料金を確認してサインアップし、アカウント管理ページで API 認証情報を生成して、サービスの利用を開始してください。

ステップ 2：認証方法を選択する

TweekIT は複数の認証方法に対応しています。ただし、MCP 連携で使用できるのは Key/Secret ペア方式のみです。

• API Key と Secret – MCP の本番環境での使用に必須です。より安全で、アクセスを管理しやすくなります。

サインアップ後、アカウントダッシュボードでこれらの値を確認できます。安全に保管し、クライアント側のコードには決して公開しないでください。

ステップ 3：最初の API 呼び出しを行う

以下は、基本的なリサイズ処理で画像を送信し、変換をプレビューして、結果を返す最小限の動作する JSON の例です。この例では API Key と Secret による認証を使用します。

この JSON は、一般公開されている MCP サーバーで MCP Inspector を使用した際に取得したものです。

{
  "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 形式のセマンティックバージョンを使用しており、ビルドの値は 2 桁になるようにゼロ埋めされます（例：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 はポート 8080 で localhost にバインドされます。ポートは 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> を、Cloud Run の環境変数を YAML 形式で指定する場合は --env-file <path> を渡してください。

ヘルパースクリプトに認証情報が含まれることはありません。スクリプトの実行時には、必ずご自身の Google Cloud プロジェクト、リージョン、シークレットソースを指定してください。Equilibrium のステージング環境および本番環境のキーはマネージドシークレットストアに保管されており、意図的にこのリポジトリから除外されています。

Firebase Functions の Python 依存関係は、デプロイ時に解決されます。scripts/deploy_firebase.sh は、依存関係をローカルの functions/packages/（gitignore 対象のディレクトリ）にベンダー化するため、リポジトリを軽量な状態に保てます。

クライアントとの互換性

• 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（MCP TypeScript クライアントを使用した Node）：

  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 を使用する方法は 2 つあります。

1. ホスト型 HTTP サーバー – Settings → Connectors → Advanced → Developer Mode → 「Add HTTP server」で、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 ヘッドレスノードは、SAS 70 / ISO 27001 準拠のデータセンター内にある Equilibrium 所有の CPUcoin エンタープライズマイナーで稼働しており、ローカルバンドルも同じ機能セットを備えていることを改めてお知らせします。

どちらかの方法で接続した後：

• 「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 を再起動し、「List tools」を実行して、version、doctype、convert、convert_url が使用可能であることを確認します。
3. 任意：JSON を社内でホストし、チームメイト向けに「Add to 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 の「Tools」パネルで、適切なパラメーターを指定して doctype、convert、または convert_url を呼び出します。
3. チームメイトがすぐに接続できるよう、ワークスペース固有の認証情報の設定手順を文書化します。

クイックスタート（OpenAI Codex CLI）

OpenAI Codex CLI（@openai/codex）は、MCP サーバーを標準機能としてサポートしています。TweekIT を追加する方法は 2 つあります。

オプション A — 1 行で設定する簡単なプラグイン（設定ファイル不要）：

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

各セッションで --mcp-server フラグを渡すか、恒久的に使用できるようシェルのプロファイルでエイリアスを設定します。

オプション 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 は、費用をかけずに試用や統合を行える、充実した無料プランを提供しています。

無料プラン

• API 呼び出し 10,000 回が無料で含まれます。
• アップロード、プレビュー、ダウンロード、削除に関するすべての主要機能を利用できます。
• 利用開始時にクレジットカードは不要です。

有料プラン

無料プランの上限を超えた場合は、いつでも有料プランにアップグレードできます。
詳細は料金ガイドをご覧ください。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 は、プレビュー時に適用される幅広い変換に対応しています。

• サイズ変更：幅と高さを指定します（パラメーターを片方だけ送信すると、縦横比を維持するため、もう片方は自動的に計算されます）
• 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。出力形式が対応している場合、アルファチャンネルをそのまま引き継ぎます）。false の場合、アルファチャンネルが削除され、ピクセルは bgColor の値に置き換えられます。
• bgColor：背景色。余白の塗りつぶしや、透明なドキュメントからアルファチャンネルを削除する場合に使用します（デフォルト：「000000」、つまり黒）。16 進数値の前に「#」（ウェブカラーの記号）を付けても構いません。

指定したページ（または 1 ページ目）の画像が、適切なコンテンツタイプを設定してレスポンスで返されます。noRasterize が true に設定され、その他の条件もすべて満たされている場合、送信したドキュメント全体の内容を含む PDF が返されます。

/convert_url

説明：リモートドキュメントを HTTP(S) 経由でダウンロードし、呼び出し元が base64 入力を渡す必要なく、TweekIT の変換パイプラインに送ります。

パラメーター：

• 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 リファレンス

MCP サーバーが TweekIT REST API とどのように通信し、MCP リクエストを TweekIT にプロキシするかについては、ドキュメント（https://tweekit.io/docs/rest-api/）を参照してください。

ユースケース

以下は、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. ソーシャルメディアと E コマース向け画像のリサイズ

アスペクト比と背景の塗りつぶしを適切に設定した、プラットフォーム別の商品画像を生成します。

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. 変換後のファイルをダウンロードします。

アップロードプレビュー UI

デモでは、ドラッグ＆ドロップまたはクリックでファイルを選択してアップロードできます。アップロードすると、次の情報が表示されます。

• ファイル名と種類。
• 生成された DocId（有効期限は20分です）。
• 元の画像のプレビュー。

変換 UI

ブラウザーで変換パラメーターを直接調整します。

• サイズ変更の寸法。
• 切り抜き領域（長方形または楕円形）。
• 出力形式。
• 背景色の塗りつぶし。

変更はリアルタイムで適用されます。アプリケーションから呼び出すものと同じ 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 を使うだけで、ファイルを意図したとおりに使用できるようになります。

例

• 画像から動画へ：動画合成モデルに渡す前に、すべてのフレームを正規化します。
• 画像から画像へ：LLM で処理できる .png または .jpg に、あらゆるファイルを正規化します。文書の最初のページ、PDF、カメラ RAW、TIFF、PSD、Illustrator など、どのようなファイルでも対象にできます。
• スタイル転送：画像のサイズと形式を変更し、モデルが想定する入力寸法に合わせます。
• OCR パイプライン：文書を高コントラストの PNG に変換し、テキスト認識の精度を高めます。
• プロ向け形式（例：Adobe Illustrator）の取り込み：変換に失敗したり、使用できない結果が返されたりする代わりに、複雑な PDF 文書をレンダリングできる実用的な画像形式に変換します。
• Office 文書、旧式および複雑な形式から PDF への変換：あらゆる種類の Word ファイル（.doc、.docm、.docx、.dot、.ppt、.vso）を、ほとんどの AI LLM に取り込める標準的な PDF に変換できるようになりました。

MCP では、AI モデルのアクションを呼び出す前に TweekIT の変換を連鎖させます。

パフォーマンスのチューニング

• 出力サイズを削減する：fmt (rest) outfmt (MCP) と、webp などの圧縮に適した形式を使用すると、より高速に配信できます。
• 変換手順を最小限にする：プレビューを複数回行うのではなく、変換を1つのリクエストにまとめます。

セキュリティの強化

• 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 Desktop バンドルガイド
  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種類以上のファイル形式

注：DOCX、XLSX、PPTX などの新しい XML ベースの形式は、より適切にサポートされている場合がありますが、旧式のバイナリ Office 形式（DOC、XLS、PPT）や特殊な形式では、引き続き問題が発生します。

その結果、作業の流れに厄介なボトルネックが生じます。価値あるコンテンツを含むファイルがあるのに、AI ツールがそのファイルを拒否してしまうのです。

解決策：TweekIT ファイル形式イネーブラー

TweekIT MCP Server は、450種類以上のファイル形式を Claude 対応形式（PDF、PNG、JPEG、WebP）に変換する万能な変換ツールとして機能し、この問題を解決します。これにより、次のことが可能になります。

✅ 「サポートされていないファイル形式」というエラーが発生しなくなります ✅ あらゆる形式のドキュメントからコンテンツを分析できます ✅ 旧式のファイルからテキストやデータを抽出できます ✅ AI ワークフローでプロフェッショナルなデザインファイルを扱えます ✅ Office ドキュメントを AI が読み取れる PDF に変換できます

AI ファイル形式変換 Web ツール

Claude、OpenAI、その他の AI ツールのユーザーがファイル形式の制限を克服できるよう、専用のスタンドアロン Web コンバーターを作成しました。

場所：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：Claude による分析用に DOC ファイルを PDF に変換します
• 古い 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 は事実上あらゆるファイル形式を扱えるようになります。