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。

一个 Worker 固定对应一个 Cosense 项目和一个 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 的全新实现。