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ツールの引数から、別プロジェクトや認証情報を指定・変更することはできません。

各種MCPツールから使う方法

• 名前 Cosense
• MCPエンドポイント https://<worker-host>/mcp
• 認証 OAuth

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

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

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

提供するエンドポイント

エンドポイント	内容
GET /	サービス概要を返します。プロジェクト名や秘密情報は返しません。
GET /health	認証不要のヘルスチェックです。
ALL /mcp	Cloudflare Accessで保護されたStreamable HTTP MCPエンドポイントです。

MCPツール

ツール	入力	内容
get_page	title	ページ本文、直接リンク、1-hop・2-hop関連ページ、外部・他プロジェクトリンクを取得します。
list_pages	なし	更新日時順で最大100件のページを、説明と更新日時つきで取得します。
search_pages	query	設定済みプロジェクト内でCosense全文検索を実行します。
insert_lines	title、targetLineText、text	最初に完全一致した行の直後へ挿入します。一致がなければ末尾へ追加します。textには改行を含められます。

ローカルセットアップ

必要なものは、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 check はLint、型検証、ユニットテスト、Worker binding型の同期確認、デプロイ前バンドル検証をまとめて実行します。

pnpm check
pnpm wrangler dev --local

Cloudflare Access Managed OAuthの設定

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

pnpm run 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向けに新規実装したものです。