cosense-mcp-worker

这是一个操作 Cosense（原 Scrapbox）单个项目的无状态远程 MCP 服务器。它运行在 Cloudflare Workers 上，使用 Hono 进行 HTTP 路由，使用 Cloudflare Agents 的 createMcpHandler() 和 MCP SDK v2 进行 MCP。OAuth 实现不放在 Worker 中，而是委托给 Cloudflare Access Managed OAuth。

一个 Worker 固定对应一个 Cosense 项目和一个 connect.sid。无法通过 MCP 工具参数指定或更改其他项目或认证信息。

从各种 MCP 工具使用的方法

• 名称 Cosense

• MCP 端点 https://<worker-host>/mcp

• 认证 OAuth

Related MCP server: Remote MCP Server with Bearer Auth

一键部署到 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 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. 将 https://<worker-host>/mcp 注册到 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 全新实现的。