shiyui-cosense-mcp

https://scrapbox.io/shiyui 専用の Remote MCP Server。

• Cosense Personal Access Token（PAT）を必須とし、Cloudflare Secret COSENSE_PAT に保存

• shiyui 固定のCosense requestへ x-personal-access-token を送信

• PATが未設定または空ならCosenseへ接続せず失敗

• Public / Private pageを同じ認証経路で取得

• MCPはCloudflare Access Managed OAuthで保護

• 6つのread toolと、用途を分けた4つのwrite toolを公開

• writeは公式CLIと同じpage edit APIとreplace links APIを使用し、任意project、任意URL、cacheは持たない

Tools

project、origin、URL、HTTP header、credential、file pathはtool引数に含めない。

search_full_text、search_vector、get_related_pages の limit は1–100、既定値は20とする。list_pages の limit は1–1000、既定値は20で、sort と明示的な skip を受け取る。いずれも指定された範囲だけを取得し、自動paginationやpage detailのN+1取得は行わない。続きが必要な場合は、返されたcursorまたは nextSkip を指定して改めて呼ぶ。

get_page_changes は get_page が返す pageId と任意の commitId を受け取る。対象pageのcommitsとactor名解決用のproject usersを2 GETで並列取得し、他page、page本文、関連pageへ広げない。返却は最新100件の変更に限定し、変更前後のtextは各2000文字までとする。actorはnameだけを返し、email、user ID、line IDは返さない。

Write

write toolは、ユーザーの書き込み意思と対象が明確な場合に呼ぶ。依頼の範囲内でLLMが文章を整えて実行でき、生成した最終文字列の再提示と再承認は必須にしない。意図が曖昧な場合や依頼範囲を超える場合だけ確認する。

project固有の書き方・記法・編集方針の正本はCosenseの cosenseの書き方 とする。現在のcommit、page状態、既存の書式を判断するために必要な場合だけ get_page を使い、安全確認だけを目的とした一律のreadは要求しない。操作固有の削除・競合・再実行条件は各tool descriptionに置く。

• create_page は同名の実pageがある場合に失敗する。既存pageへの追記へ切り替えない

• append_to_page は対象の現在状態として取得済みの commitId を expectedCommitId として必須にする。既知の結果がcurrentなら確認だけの再readは行わない

• update_page も対象の現在状態を示す commitId を必須にし、title行を除く完成後の本文を body に指定する。body の省略は本文維持、空文字は本文全削除を表す。body を指定した場合、含めなかった既存行は削除される。任意の newTitle でタイトルも変更できる

• replace_links はproject内の [title]、#title、[title.icon] を一括置換する。pageタイトルは変更せず、previewも行わない。独立したtoolとして影響範囲を分離するが、ユーザーがrenameとlink更新をまとめて依頼した場合は追加確認なしで続けて実行できる

• page編集はpageが不存在、rename済み、または更新済みなら失敗する。競合時とsubmit結果が不明な場合は、最新pageを読んでから次の操作を判断する

• create / appendのtextとupdateのbodyにはMCP独自の文字数・行数・change数上限を設けない。NULを拒否し、appendは空白だけのtextも拒否する

• create / append / updateは1 call内で page-edit-for-ai/preview と submit を各1回までとし、自動retryしない

• submit結果が不明な場合は同じwriteを再実行せず、先に get_page で反映状態を確認する

• タイトル変更だけの依頼からlink置換を推測しない。link更新も明確に依頼されている場合は、update_page が返した実際のtitleを使って replace_links を続けて呼ぶ

• replace_links の通信失敗または5xxは一部だけ反映済みの可能性がある。同じ fromTitle / toTitle だけを再実行できる

preview ID、line ID、page ID、project、origin、credentialはwrite toolの引数に含めない。raw operationも公開しない。

Related MCP server: confluence-http-api-mcp

Requirements

• Node.js 24.11以上

• pnpm 11.16.0

• Cloudflare Workers Free plan

• Cloudflare Zero Trust Free plan

• Cosense Personal Access Token

• One-time PINを受信するemail address 1件

Install

pnpm install --frozen-lockfile
pnpm check

pnpm-workspace.yaml はdependencyのminimum release ageを7日に設定する。

Cosense PAT

PATは https://scrapbox.io/settings/personal-access-tokens で発行する。README、wrangler.jsonc、example file、Gitには保存しない。

localでは、Git管理外の .dev.vars を作成して実値を設定する。

cp .dev.vars.example .dev.vars

COSENSE_PAT=replace-with-personal-access-token

CloudflareにはSecretとして登録する。

npx wrangler secret put COSENSE_PAT

PATが未設定または空の場合はfail closedとし、匿名requestへfallbackしない。Cosenseが 401 または 403 を返した場合は認証失敗として扱い、PAT、upstream response body、statusごとの意味をclientへ返さない。

Cloudflare Access

1. Cloudflare Zero TrustにOne-time PIN identity providerを追加する。

2. Workerの公開hostname全体を対象にSelf-hosted Access applicationを作成する。

3. Allow policyのIncludeを本人のemail 1件にし、利用可能なidentity providerをOne-time PINだけにする。

4. applicationでManaged OAuthとDynamic Client Registrationを有効にする。

5. DCRのredirect URIにChatGPT管理画面で表示されたcallback URIを登録する。

6. localhost clientとloopback clientを無効にする。

7. Application Audience tagとteam domainを wrangler.jsonc に設定する。

8. Preview URLは使用しない。wrangler.jsonc で preview_urls: false を明示し、Cloudflare上でも無効になっていることを確認する。

{
  "vars": {
    "TEAM_DOMAIN": "https://<team>.cloudflareaccess.com",
    "POLICY_AUD": "<application-audience-tag>"
  }
}

Access for SaaS application、OIDC client ID / secret、Worker callback、custom scopeは使用しない。

課金

• Workers FreeとZero Trust Freeだけを使用し、有料planへupgradeしない

• KV、Durable Objects、D1、R2、Queues、Workers AIは使用しない

• readは1 tool callあたり最大2 request。page writeは最大4 request、replace_links は1 requestで、自動retryは行わない

• Workers Freeの1日100,000 requestを超えた場合は処理が失敗し、従量課金には移行しない

Deploy

pnpm exec wrangler login
pnpm exec wrangler whoami
pnpm check
pnpm exec wrangler deploy --dry-run
pnpm run deploy

ChatGPT Developer modeへ次を登録する。

https://<worker-origin>/mcp

初回接続でOne-time PIN認証を行い、10 toolの一覧と1回のread callを確認する。writeの動作確認を行う場合は、対象と書き込み意思を明示して依頼する。

Data boundary

• readはallowlist済みの GET、page writeは対象確認用の GET とpreview / submit POST、link置換は固定projectのreplace links POSTだけを使用し、すべて cache: "no-store" とする

• 全Cosense requestへ x-personal-access-token を付与し、Public / Privateで分岐しない

• MCP responseも Cache-Control: no-store

• responseにemail、user ID、line ID、raw API responseを含めない。変更履歴のactorはnameだけを返す

• list_pages は1 GETだけとし、N+1取得、全件走査、自動paginationを行わない

• get_page_changes は対象pageのcommitsとactor名解決用usersの2 GETだけとし、他pageへ広げない

• title、query、pageId、commitId、cursorは500文字までとする。Workerの16 KiB URL境界を超えないための通信上の制約であり、page本文の利用制限ではない

• writeは新規作成、末尾追記、完成形によるpage更新、link一括置換に限定し、同名存在またはcommit不一致から別操作へfallbackしない

• 自動retry、polling、background同期、事前indexを行わない

• PAT、OAuth token、Access assertion、page本文、queryをlogしない

• 401 / 403 はtokenとupstream bodyを含まない認証失敗として返す

• Cosense internal APIとPAT headerの利用方法は予告なく変更される可能性がある

read調査の履歴は docs/research.md、writeの設計根拠は docs/write-design.md を参照する。