cosense-mcp-worker

Es un servidor MCP remoto de arquitectura sin estado que opera sobre un único proyecto de Cosense (anteriormente Scrapbox). Se ejecuta en Cloudflare Workers, utiliza Hono para el enrutamiento HTTP y createMcpHandler() de Cloudflare Agents y el SDK de MCP v2 para MCP. La implementación de OAuth no reside en el Worker, sino que se delega en Cloudflare Access Managed OAuth.

Un Worker está vinculado a un único proyecto de Cosense y a un único connect.sid. No es posible especificar ni modificar otros proyectos o credenciales mediante los argumentos de las herramientas MCP.

Despliegue en un clic en Cloudflare

Con este botón puede crear, compilar e implementar un Worker en su propia cuenta de Cloudflare. En la pantalla de configuración, introduzca el nombre del Worker, COSENSE_PROJECT_NAME, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD y el secreto COSENSE_SID.

La creación de la aplicación de Cloudflare Access, la habilitación de Managed OAuth y la configuración de las políticas de acceso deben realizarlas usted mismo después del despliegue.

Puntos de conexión proporcionados

Herramientas MCP

Configuración local

Necesitará Node.js 20 o superior, Corepack, una cuenta de Cloudflare con acceso a Cloudflare Zero Trust y un ID de sesión con permisos sobre el proyecto de Cosense de destino.

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

Los valores que no son secretos se configuran en 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"
}

El ID de sesión debe configurarse siempre como un secreto del Worker. No debe guardarse en wrangler.jsonc, en el código fuente ni en Git.

pnpm wrangler secret put COSENSE_SID

Solo para el desarrollo local, configúrelo en el archivo .dev.vars, que no se confirma en el repositorio.

COSENSE_SID=your-connect.sid-value

La verificación y la ejecución local son las siguientes:

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

Configuración de Cloudflare Access Managed OAuth

Ejecute el siguiente comando solo cuando esté listo para implementar.

pnpm deploy

A continuación, cree una aplicación de acceso para el nombre de host del Worker en el panel de Cloudflare Zero Trust.

1. Cree una aplicación de servidor MCP para el dominio del Worker y la ruta /mcp.

2. Configure una política de acceso con los usuarios o grupos de identidad a los que desee permitir el uso del proyecto de Cosense de destino.

3. Copie la etiqueta de audiencia (AUD) de la aplicación y asígnela a CF_ACCESS_AUD.

4. Compruebe que el dominio de equipo de Zero Trust coincide con CF_ACCESS_TEAM_DOMAIN.

5. Habilite Managed OAuth en la configuración avanzada de la aplicación.

6. Registre https://<worker-host>/mcp en el cliente MCP.

Cloudflare Access se encarga de todo: flujo de código de autorización, PKCE, inicio de sesión, tokens de actualización, descubrimiento OAuth y políticas de acceso. El Worker no implementa un servidor OAuth.

El Worker recibe la cabecera Cf-Access-Jwt-Assertion y solo reenvía las solicitudes a /mcp al manejador MCP después de verificar la firma RS256, el emisor y la audiencia mediante el punto de conexión JWKS del equipo.

La información de descubrimiento OAuth al usar Managed OAuth se devuelve al cliente desde la capa de Access. No añada puntos de conexión OAuth ni un servidor de autorización propio dentro del Worker.

Consideraciones de seguridad

• COSENSE_SID se trata como un enlace secreto y no se incluye en las respuestas JSON ni en los registros.

• /mcp rechaza con 401 las solicitudes sin una aserción de acceso válida o con una aserción no válida.

• La firma del JWT de Access se verifica en https://<team-domain>/cdn-cgi/access/certs, y también se verifican el emisor y la audiencia.

• El origen de /mcp está permitido en su totalidad. Se prioriza la compatibilidad con clientes MCP remotos; el control de acceso se realiza mediante el token OAuth de Cloudflare Access y la validación JWT dentro del Worker.

• Como el esquema de las herramientas MCP rechaza entradas no definidas, quien llama no puede sobrescribir el proyecto ni las credenciales.

• No se devuelven los mensajes de error arbitrarios de Cosense; los errores se limitan a los de la operación.

• Para evitar respuestas involuntariamente enormes, la salida de las herramientas está limitada a 100 000 caracteres.

Estructura de directorios

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を呼ばないユニットテスト

Referencias

• Cloudflare Agents MCP handler APIs

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Ayuda de la API de Cosense

Se inspira en yosider/cosense-mcp-server. Este proyecto no copia el código de ese repositorio, sino que es una implementación nueva para Cloudflare Workers.