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용으로 새로 구현한 것입니다.