cosense-mcp-worker

Ein zustandsloser Remote-MCP-Server zur Bedienung eines einzelnen Cosense-Projekts (ehemals Scrapbox). Er läuft auf Cloudflare Workers, nutzt Hono für das HTTP-Routing und für MCP den createMcpHandler() von Cloudflare Agents sowie das MCP SDK v2. Die OAuth-Implementierung liegt nicht im Worker, sondern wird an Cloudflare Access Managed OAuth delegiert.

Ein Worker ist an genau ein Cosense-Projekt und eine connect.sid gebunden. Über die Argumente der MCP-Tools können keine anderen Projekte oder Anmeldeinformationen angegeben oder geändert werden.

Ein-Klick-Bereitstellung auf Cloudflare

Über diese Schaltfläche können Benutzer einen Worker in ihrem eigenen Cloudflare-Konto erstellen, bauen und bereitstellen. Im Einrichtungsbildschirm werden der Workername sowie COSENSE_PROJECT_NAME, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD und das Secret COSENSE_SID eingegeben.

Die Erstellung der Cloudflare-Access-Anwendung, die Aktivierung von Managed OAuth und die Konfiguration der Zugriffsrichtlinie müssen vom Benutzer nach der Bereitstellung selbst durchgeführt werden.

Bereitgestellte Endpunkte

MCP-Tools

Lokale Einrichtung

Erforderlich sind Node.js 20 oder höher, Corepack, ein Cloudflare-Konto mit Cloudflare-Zero-Trust-Zugang und eine Sitzungs-ID mit Berechtigungen für das Ziel-Cosense-Projekt.

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

Nicht geheime Werte werden in wrangler.jsonc konfiguriert.

"vars": {
  "COSENSE_PROJECT_NAME": "your-project",
  "CF_ACCESS_TEAM_DOMAIN": "https://your-team.cloudflareaccess.com",
  "CF_ACCESS_AUD": "YOUR_ACCESS_APPLICATION_AUDIENCE_TAG"
}

Die Sitzungs-ID muss unbedingt als Worker-Secret festgelegt werden. Sie darf nicht in wrangler.jsonc, im Quellcode oder in Git gespeichert werden.

pnpm wrangler secret put COSENSE_SID

Nur für die lokale Entwicklung wird sie in .dev.vars gespeichert, das nicht eingecheckt wird.

COSENSE_SID=your-connect.sid-value

Validierung und lokale Ausführung erfolgen wie folgt:

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

Einrichtung von Cloudflare Access Managed OAuth

Führen Sie die folgenden Befehle erst aus, wenn Sie bereit sind, die Bereitstellung durchzuführen.

pnpm deploy

Erstellen Sie anschließend im Cloudflare-Zero-Trust-Dashboard eine Access-Anwendung für den Worker-Hostnamen.

1. Erstellen Sie eine MCP-Serveranwendung für die Worker-Domain und den Pfad /mcp.

2. Konfigurieren Sie eine Zugriffsrichtlinie mit Benutzern oder Identitätsgruppen, die Zugriff auf das Ziel-Cosense-Projekt haben sollen.

3. Kopieren Sie das Application Audience (AUD)-Tag und legen Sie es in CF_ACCESS_AUD fest.

4. Stellen Sie sicher, dass die Team-Domain von Zero Trust mit CF_ACCESS_TEAM_DOMAIN übereinstimmt.

5. Aktivieren Sie unter den erweiterten Einstellungen der Anwendung Managed OAuth.

6. Registrieren Sie https://<worker-host>/mcp beim MCP-Client.

Authorization-Code-Flow, PKCE, Anmeldung, Aktualisierungstoken, OAuth-Discovery und Zugriffsrichtlinien werden vollständig von Cloudflare Access übernommen. Der Worker selbst implementiert keinen OAuth-Server.

Der Worker empfängt die Cf-Access-Jwt-Assertion, validiert die RS256-Signatur, den Aussteller und die AUD mithilfe des JWKS-Endpunkts des Teams und leitet die Anfrage nur dann an den MCP-Handler weiter, wenn die Validierung erfolgreich ist.

Die OAuth-Discovery-Informationen bei Verwendung von Managed OAuth werden von der Access-Ebene an den Client zurückgegeben. Fügen Sie dem Worker keine OAuth-Endpunkte oder einen eigenen Autorisierungsserver hinzu.

Sicherheitseigenschaften

• COSENSE_SID wird als Secret-Binding behandelt und nicht in JSON-Antworten oder Protokollen angezeigt.

• /mcp lehnt Anfragen ohne oder mit ungültiger Access-Assertion mit 401 ab.

• Das Access-JWT wird mit https://<team-domain>/cdn-cgi/access/certs auf die Signatur überprüft, außerdem werden Aussteller und AUD validiert.

• Der Ursprung von /mcp ist auf alle erlaubt. Die Kompatibilität mit Remote-MCP-Clients hat Priorität; die Zugriffskontrolle erfolgt über OAuth-Token von Cloudflare Access und die JWT-Validierung im Worker.

• Das MCP-Toolschema lehnt undefinierte Eingaben ab, sodass der Aufrufer Projekt- oder Anmeldeinformationen nicht überschreiben kann.

• Es werden keine beliebigen Fehlermeldungen von Cosense unverändert zurückgegeben, sondern nur auf die jeweilige Operation bezogene Fehler.

• Die Tool-Ausgabe ist auf 100.000 Zeichen begrenzt, um unbeabsichtigt große Antworten zu vermeiden.

Verzeichnisstruktur

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

Referenzen

• Cloudflare Agents MCP handler APIs

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Cosense API-Hilfe

Inspiriert von yosider/cosense-mcp-server. Dieses Projekt kopiert keinen Code aus diesem Repository, sondern ist eine Neuimplementierung für Cloudflare Workers.