FocusZoo MCP Server

FocusZoo External API（docs/openapi.yaml）を MCP（Model Context Protocol）サーバとして公開します。同じ TypeScript コードベースを Cloudflare Workers と Node.js（Passenger/LiteSpeed配下の共有ホスティングを含む一般的な Node.js 実行環境）の両方で動作させられます。

対応プラットフォーム

• Cloudflare Workers

• Node.js 20+（@hono/node-server で動作する任意の環境。Passenger/LiteSpeed 等のリバースプロキシ配下のセルフホスト/共有ホスティングを含む）

Related MCP server: toolhive-mcp

プロトコル

MCP 2025-03-26 の Streamable HTTP トランスポートを使用し、responseMode: 'json' で stateless に動作します。長時間の SSE 接続を保持しないため、共有ホスティングのタイムアウト制限にも配慮しています。

セットアップ

npm install
npm run generate   # docs/openapi.yaml -> src/generated/tools.json

認証

FocusZoo API キー（fz_live_...）を、MCP クライアントから Authorization: Bearer fz_live_... ヘッダーで送信します。これが唯一の認証経路です。

tools/list は API キーなしでも取得できますが（ツールのスキーマ開示のみのため）、ツール呼び出し（tools/call）は例外なく有効な Authorization ヘッダーを要求します。サーバー側にデフォルトの API キーを環境変数として設定し、ヘッダー未送信のリクエストへ自動的に用いるフォールバックは存在しません。 /mcp に到達できる第三者が運営者権限でツールを実行できてしまうことを避けるための意図的な設計です。

環境変数

ローカル実行

Node.js

npm run node:dev

http://127.0.0.1:3000/mcp でアクセスできます（デフォルトで 127.0.0.1 にのみ bind されます）。リクエストには Authorization: Bearer fz_live_xxx ヘッダーを付与してください。外部公開する場合は HOST=0.0.0.0 と ALLOWED_HOSTS を明示的に設定します。

Cloudflare Workers

npx wrangler dev

http://localhost:8787/mcp でアクセスできます。

デプロイ

Cloudflare Workers

前提として Cloudflare アカウント が必要です。初回のみログインします。

npx wrangler login

デプロイします。

npx wrangler deploy

デプロイに成功すると、コマンドの出力に実際のURL（既定では https://focuszoo-mcp.<あなたのサブドメイン>.workers.dev/mcp。wrangler.toml の name から決まります）が表示されます。独自ドメインを使いたい場合は wrangler.toml に routes を追加してください。

wrangler.toml の [observability] を有効化しているため、console.log によるツール呼び出しログは Cloudflare ダッシュボードの Workers Logs から確認できます。デフォルトの API キーをシークレットとして設定する運用は行いません（上記「認証」参照）。

デプロイしたURLに対して、MCPクライアント側で以下のように接続します（設定形式はクライアントによって異なります）。

{
  "mcpServers": {
    "focuszoo": {
      "type": "http",
      "url": "https://focuszoo-mcp.<あなたのサブドメイン>.workers.dev/mcp",
      "headers": { "Authorization": "Bearer fz_live_xxx" }
    }
  }
}

なお、本 README 冒頭の Deploy to Cloudflare ボタンは、この手順とは別の導線です。ボタンは自分の GitHub/GitLab アカウントにリポジトリを複製し、push 時に自動デプロイされる Workers Builds（CI/CD）まで設定します。ローカルの clone から一度だけ手元でデプロイしたい場合は、本項の wrangler login → wrangler deploy で十分です。

Node.js（共有ホスティング / セルフホスト）

1. Node.js 20+ が動作するホスティング環境にアプリを配置し、Application startup file（または相当する起動エントリ）を src/node.ts（またはビルド後のエントリ）に設定

2. npm install を実行

3. 外部公開する場合は環境変数 HOST=0.0.0.0 と、実際にアクセスされるドメイン名を含む ALLOWED_HOSTS を設定（ALLOWED_HOSTS を設定せずに HOST=0.0.0.0 にすると起動時にエラーで停止します）

4. Restart

テスト

npm test
npm run typecheck

OpenAPI 更新時

docs/openapi.yaml を更新したら、以下を再実行してください。

npm run generate
npm run typecheck
npm test

src/generated/tools.json が再生成され、MCP ツール定義が更新されます。

ライセンス

MIT License。詳細は LICENSE を参照してください。