cosense-mcp-worker

Cosense（旧Scrapbox）の単一プロジェクトを操作する、stateless構成のRemote MCPサーバーです。Cloudflare Workers上で動作し、HTTPルーティングにはHono、MCPにはCloudflare AgentsのcreateMcpHandler()とMCP SDK v2を使用します。OAuthの実装はWorkerに持たせず、Cloudflare Access Managed OAuthへ委譲します。

1つのWorkerは、1つのCosenseプロジェクトと1つのconnect.sidに固定されます。MCPツールの引数から、別プロジェクトや認証情報を指定・変更することはできません。

Cloudflareへワンクリックデプロイ

このボタンから利用者自身のCloudflareアカウントへWorkerを作成・ビルド・デプロイできます。セットアップ画面ではWorker名と、COSENSE_PROJECT_NAME、CF_ACCESS_TEAM_DOMAIN、CF_ACCESS_AUD、SecretのCOSENSE_SIDを入力します。

Cloudflare Access Applicationの作成、Managed OAuthの有効化、Access Policyの設定は、デプロイ後に利用者自身が行う必要があります。

提供するエンドポイント

MCPツール

ローカルセットアップ

必要なものは、Node.js 20以降、Corepack、Cloudflare Zero Trustを利用できるCloudflareアカウント、対象Cosenseプロジェクトへの権限を持つセッションIDです。

git clone <リポジトリURL> cosense-mcp-worker
cd cosense-mcp-worker
corepack enable
pnpm install

秘密情報ではない値をwrangler.jsoncで設定します。

"vars": {
  "COSENSE_PROJECT_NAME": "your-project",
  "CF_ACCESS_TEAM_DOMAIN": "https://your-team.cloudflareaccess.com",
  "CF_ACCESS_AUD": "YOUR_ACCESS_APPLICATION_AUDIENCE_TAG"
}

セッションIDは必ずWorker Secretとして設定してください。wrangler.jsonc、ソースコード、Gitへ保存してはいけません。

pnpm wrangler secret put COSENSE_SID

ローカル開発専用では、コミットしない.dev.varsへ設定します。

COSENSE_SID=your-connect.sid-value

検証とローカル実行は以下のとおりです。

pnpm lint
pnpm typecheck
pnpm test
pnpm wrangler dev --local

Cloudflare Access Managed OAuthの設定

デプロイする準備ができた段階でのみ、次のコマンドを実行します。

pnpm deploy

続いてCloudflare Zero Trustダッシュボードで、Workerのホスト名に対するAccess Applicationを作成します。

1. Workerのドメインおよび/mcpパスを対象に、MCP server applicationを作成します。

2. 対象Cosenseプロジェクトの利用を許可するユーザーまたはIDグループでAccess Policyを設定します。

3. Application Audience（AUD）Tagをコピーし、CF_ACCESS_AUDへ設定します。

4. Zero TrustのTeam DomainがCF_ACCESS_TEAM_DOMAINと一致することを確認します。

5. ApplicationのAdvanced settingsでManaged OAuthを有効にします。

6. MCPクライアントへhttps://<worker-host>/mcpを登録します。

Authorization Code Flow、PKCE、ログイン、リフレッシュトークン、OAuth discovery、Access PolicyはすべてCloudflare Accessが担当します。Worker自身はOAuthサーバーを実装しません。

WorkerはCf-Access-Jwt-Assertionを受け取り、TeamのJWKSエンドポイントを使ってRS256署名・issuer・AUDを検証した後にのみ、/mcpへの要求をMCPハンドラーへ渡します。

Managed OAuth利用時のOAuth discovery情報はAccess層からクライアントへ返されます。Worker内にOAuthエンドポイントや独自の認可サーバーを追加しないでください。

セキュリティ上の性質

• COSENSE_SIDはSecret bindingとして扱い、JSONレスポンスやログに含めません。

• /mcpはAccess assertionがない、または無効な要求を401で拒否します。

• Access JWTはhttps://<team-domain>/cdn-cgi/access/certsで署名を検証し、issuerとAUDも検証します。

• /mcpのOriginは全許可です。Remote MCPクライアントとの互換性を優先しており、アクセス制御はCloudflare AccessのOAuthトークンとWorker内のJWT検証で行います。

• MCPツールのスキーマは未定義の入力を拒否するため、呼び出し側からプロジェクトや認証情報を上書きできません。

• Cosense側の任意のエラー内容をそのまま返さず、操作単位のエラーへ限定します。

• 意図せず巨大なレスポンスを返さないよう、ツール出力は100,000文字で上限を設けています。

ディレクトリ構成

src/
  config.ts                 Worker bindingの検証
  index.ts                  Honoルートとstateless MCP HTTP transport
  middleware/access-auth.ts Access JWTの検証
  mcp/server.ts             MCP SDK v2 server factory
  mcp/tools/                ツールごとのスキーマと登録処理
  cosense/client.ts         Cosense adapter
  cosense/formatter.ts      LLM向けページ整形
  cosense/insert-lines.ts   純粋な挿入位置計算
test/                       外部Cosense APIを呼ばないユニットテスト

参考資料

• Cloudflare Agents MCP handler APIs

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Cosense APIヘルプ

yosider/cosense-mcp-serverに着想を得ています。本プロジェクトは同リポジトリのコードをコピーせず、Cloudflare Workers向けに新規実装したものです。