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 HTTP-Routing und für MCP die createMcpHandler()-Funktion 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 ein einzelnes Cosense-Projekt und eine einzelne connect.sid gebunden. Über die Argumente der MCP-Tools können kein anderes Projekt oder andere Anmeldedaten angegeben oder geändert werden.

Verwendung über verschiedene MCP-Tools

• Name Cosense

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

• Authentifizierung OAuth

Related MCP server: Remote MCP Server with Bearer Auth

Ein-Klick-Deployment auf Cloudflare

Über diesen Button können Sie einen Worker in Ihrem eigenen Cloudflare-Konto erstellen, bauen und bereitstellen. Im Einrichtungsbildschirm geben Sie den Worker-Namen sowie COSENSE_PROJECT_NAME, CF_ACCESS_TEAM_DOMAIN, CF_ACCESS_AUD und das Secret COSENSE_SID ein.

Das Erstellen der Cloudflare Access Application, das Aktivieren von Managed OAuth und das Einrichten der Access Policy müssen Sie nach dem Deployment selbst durchführen.

Bereitgestellte Endpunkte

MCP-Tools

Lokale Einrichtung

Erforderlich sind Node.js 20 oder höher, Corepack, ein Cloudflare-Konto mit Zugriff auf Cloudflare Zero Trust sowie 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 festgelegt.

"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 die nicht eingecheckte Datei .dev.vars eingetragen.

COSENSE_SID=your-connect.sid-value

Prüfung und lokale Ausführung erfolgen wie folgt. pnpm check führt Lint, Typprüfung, Unit-Tests, die Synchronisationsprüfung der Worker-Binding-Typen und die Bundle-Prüfung vor dem Deployment zusammen aus.

pnpm check
pnpm wrangler dev --local

Einrichtung von Cloudflare Access Managed OAuth

Führen Sie den folgenden Befehl erst aus, wenn Sie bereit für das Deployment sind.

pnpm run deploy

Erstellen Sie anschließend im Cloudflare Zero Trust Dashboard eine Access Application für den Hostnamen des Workers.

1. Erstellen Sie eine MCP server application für die Domain des Workers und den Pfad /mcp.

2. Richten Sie eine Access Policy für Benutzer oder ID-Gruppen ein, die die Nutzung des Ziel-Cosense-Projekts erlauben.

3. Kopieren Sie das Application Audience (AUD) Tag und setzen Sie es in CF_ACCESS_AUD.

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

5. Aktivieren Sie in den Advanced settings der Application Managed OAuth.

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

Authorization Code Flow, PKCE, Login, Refresh-Token, OAuth-Discovery und Access Policy werden alle von Cloudflare Access übernommen. Der Worker selbst implementiert keinen OAuth-Server.

Der Worker empfängt die Cf-Access-Jwt-Assertion und leitet Anfragen an /mcp nur dann an den MCP-Handler weiter, nachdem er die RS256-Signatur, den Issuer und die AUD über den JWKS-Endpunkt des Teams verifiziert hat.

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

Sicherheitseigenschaften

• COSENSE_SID wird als Secret-Binding behandelt und nicht in JSON-Antworten oder Logs aufgenommen.

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

• Die Signatur des Access-JWT wird über https://<team-domain>/cdn-cgi/access/certs verifiziert; auch Issuer und AUD werden geprüft.

• Der Origin von /mcp ist vollständig offen. Die Kompatibilität mit Remote-MCP-Clients hat Priorität; die Zugriffskontrolle erfolgt über das OAuth-Token von Cloudflare Access und die JWT-Verifizierung im Worker.

• Die Schemata der MCP-Tools lehnen undefinierte Eingaben ab, sodass der Aufrufer Projekt oder Anmeldedaten nicht überschreiben kann.

• Beliebige Fehlerinhalte von Cosense werden nicht direkt zurückgegeben, sondern auf fehlerhafte Operationen beschränkt.

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

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.