# FocusZoo MCP Server

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/Watanabebashi/FocusZoo-SuperMCP)

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 等のリバースプロキシ配下のセルフホスト/共有ホスティングを含む）

## プロトコル

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

## セットアップ

```bash
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` に到達できる第三者が運営者権限でツールを実行できてしまうことを避けるための意図的な設計です。

## 環境変数

| 名前 | 説明 | 必須 |
|---|---|---|
| `FOCUSZOO_BASE_URL` | FocusZoo API のベース URL（デフォルト: `https://focuszoo.watanabebashi.net`） | 任意 |
| `HOST` | Node.js 時の bind アドレス（デフォルト: `127.0.0.1`） | 任意 |
| `ALLOWED_HOSTS` | Node.js 時の `Host` ヘッダー許可リスト（カンマ区切り） | **`HOST` が `0.0.0.0` または `::` の場合は必須。未設定だと起動に失敗します** |
| `PORT` | Node.js 時の待受ポート（デフォルト: 3000） | 任意 |
| `ENABLE_TOOL_CALL_LOGS` | Node.js 実行時、ツール呼び出しの構造化ログ（ツール名・認証成否・HTTPステータス・所要時間）を有効化（`true` で有効） | 任意。Cloudflare Workers では常時有効（Workers Logs 経由、`wrangler.toml` の `[observability]` で制御） |

## ローカル実行

### Node.js

```bash
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

```bash
npx wrangler dev
```

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

## デプロイ

### Cloudflare Workers

前提として [Cloudflare アカウント](https://dash.cloudflare.com/sign-up) が必要です。初回のみログインします。

```bash
npx wrangler login
```

デプロイします。

```bash
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クライアント側で以下のように接続します（設定形式はクライアントによって異なります）。

```json
{
  "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

## テスト

```bash
npm test
npm run typecheck
```

## OpenAPI 更新時

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

```bash
npm run generate
npm run typecheck
npm test
```

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

## ライセンス

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