cosense-mcp-worker

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

Un Worker está fijado a un único proyecto de Cosense y a un único connect.sid. No se puede especificar ni cambiar otro proyecto o credenciales desde los argumentos de las herramientas MCP.

Cómo usar desde varias herramientas MCP

• Nombre Cosense

• Endpoint MCP https://<worker-host>/mcp

• Autenticación OAuth

Related MCP server: Remote MCP Server with Bearer Auth

Implementación con un clic en Cloudflare

Con este botón, el usuario puede crear, compilar e implementar un Worker en su propia cuenta de Cloudflare. En la pantalla de configuración, se ingresan el nombre del Worker y 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 la política de acceso deben realizarlas el propio usuario después de la implementación.

Endpoints proporcionados

Herramientas MCP

Configuración local

Lo necesario es Node.js 20 o posterior, Corepack, una cuenta de Cloudflare que pueda usar Cloudflare Zero Trust y un ID de sesión con permisos para 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 información secreta 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 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 desarrollo local, configúralo en .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 check ejecuta lint, verificación de tipos, pruebas unitarias, confirmación de sincronización de tipos de enlaces del Worker y verificación del paquete antes de la implementación.

pnpm check
pnpm wrangler dev --local

Configuración de Cloudflare Access Managed OAuth

Solo cuando estés listo para implementar, ejecuta el siguiente comando.

pnpm run deploy

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

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

2. Configura una política de acceso con los usuarios o grupos de identidad que permitan el uso del proyecto de Cosense de destino.

3. Copia la etiqueta de audiencia de la aplicación (AUD) y configúrala en CF_ACCESS_AUD.

4. Verifica que el dominio de equipo de Zero Trust coincida con CF_ACCESS_TEAM_DOMAIN.

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

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

El flujo de código de autorización, PKCE, inicio de sesión, token de actualización, descubrimiento de OAuth y política de acceso son todos manejados por Cloudflare Access. El Worker no implementa un servidor OAuth.

El Worker recibe Cf-Access-Jwt-Assertion y solo después de verificar la firma RS256, el emisor y la AUD mediante el punto final JWKS del equipo, pasa las solicitudes a /mcp al manejador MCP.

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

Propiedades de seguridad

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

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

• El JWT de acceso se verifica su firma en https://<team-domain>/cdn-cgi/access/certs, y también se verifican el emisor y la AUD.

• El origen de /mcp permite todos los orígenes. Se prioriza la compatibilidad con clientes MCP remotos; el control de acceso se realiza mediante el token OAuth de Cloudflare Access y la verificación JWT dentro del Worker.

• El esquema de las herramientas MCP rechaza entradas no definidas, por lo que el llamador no puede sobrescribir el proyecto ni las credenciales.

• No se devuelve el contenido de errores arbitrarios del lado de Cosense; se limita a errores por operación.

• Para evitar respuestas involuntariamente grandes, la salida de las herramientas tiene un límite de 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.