da-mcp

Ein Remote-Model-Context-Protocol-Server (MCP) für Document Authoring (DA). Dieser Server bietet LLM-Assistenten wie Claude oder ChatGPT direkten Zugriff auf DA-Verwaltungsvorgänge.

Funktionen

• 10 DA Admin Tools: Vollständiger Satz von Tools zur Verwaltung von DA-Repositories

• Remote-Zugriff: Auf Cloudflare Workers mit globaler Edge-Verteilung bereitstellbar

• Streamable HTTP: Modernes MCP-Transportprotokoll für Remote-Server

• Token-Pass-through: Einfache Authentifizierung durch Weiterleitung von DA-API-Tokens über den Authorization-Header

• Produktionsreif: Fehlerbehandlung, Protokollierung, CORS-Unterstützung und Health-Checks

• TypeScript: Vollständig typisierte Codebasis für Zuverlässigkeit und Wartbarkeit

Related MCP server: Core Content Services MCP Server

Architektur

┌─────────────────┐
│   MCP Client    │
│ (Claude/Cursor) │
└────────┬────────┘
         │ Streamable HTTP
         │ + DA Token
         ↓
┌─────────────────────────┐
│  DA MCP                 │
│  ┌──────────────────┐   │
│  │   MCP Server     │   │
│  │   (10 Tools)     │   │
│  └──────────────────┘   │
└───────────┬─────────────┘
            │ HTTPS + Token
            ↓
┌─────────────────────────┐
│  DA Admin API           │
│  (admin.da.live)        │
└─────────────────────────┘

Projektstruktur

src/
├── index.ts              # Cloudflare Worker entry point
├── mcp/
│   ├── server.ts         # MCP server initialization
│   ├── tools.ts          # Tool definitions (schemas)
│   └── handlers.ts       # Tool implementation handlers
└── da-admin/
    ├── client.ts         # DA Admin API client
    └── types.ts          # TypeScript types

Verfügbare Tools

Voraussetzungen

• Node.js 18+ und npm

• Cloudflare-Konto (kostenloser Tarif ist ausreichend)

• Wrangler-CLI installiert (npm install -g wrangler)

• DA-Admin-API-Token

Installation

1. Repository klonen und Abhängigkeiten installieren:

git clone <repository-url>
cd da-mcp
npm install

2. Wrangler konfigurieren:

Bearbeiten Sie bei Bedarf wrangler.toml, um Ihre Bereitstellungseinstellungen anzupassen.

Entwicklung

Lokale Entwicklung

Führen Sie den Server lokal mit Hot Reload aus:

npm run dev

Der Server ist unter http://localhost:8787 verfügbar.

Test-Endpunkte

• Health-Check: http://localhost:8787/health

• MCP-Endpunkt: http://localhost:8787/mcp

Testen mit dem MCP Inspector

1. Starten Sie den lokalen Server: npm run dev

2. Öffnen Sie den MCP Inspector

3. Konfigurieren Sie die Verbindung:

   • Typ: Streamable HTTP

   • URL: http://localhost:8787/mcp

   • Header: Authorization: Bearer YOUR_DA_TOKEN

Bereitstellung

Bereitstellung auf Cloudflare Workers

# Deploy to production
npm run deploy

# Or deploy to development environment
wrangler deploy --env development

Öffentliche URLs

Nach der Bereitstellung ist Ihr MCP-Server erreichbar unter:

• Direkter MCP-Endpunkt:
  https://da-mcp.adobeaem.workers.dev/mcp

• IMS-authentifiziert über den AEM-API-Router:
  https://mcp.adobeaemcloud.com/adobe/mcp/da
  (Unterstützt die Adobe-IMS-Anmeldung. Einzelheiten finden Sie im Abschnitt Authentifizierung unten.)

Client-Konfiguration

Claude Desktop

Fügen Sie Folgendes zu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder der entsprechenden Datei hinzu:

{
  "mcpServers": {
    "da-live-admin": {
      "type": "streamable-http",
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    }
  }
}

VS Code / Cursor

Fügen Sie Folgendes zu .vscode/mcp.json oder den Cursor-Einstellungen hinzu:

{
  "mcpServers": {
    "da-admin-mcp-direct": {
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    },
    "da-prod-mcp": {
      "url": "https://mcp.adobeaemcloud.com/adobe/mcp/da"
    }
  }
}

Authentifizierung

Der Server verwendet eine einfache Token-Pass-through-Authentifizierung:

1. Der Client sendet das DA-Admin-API-Token im Authorization-Header

2. Der Server extrahiert das Token und reicht es an die DA-Admin-API weiter

3. Alle Anfragen an die DA-Admin-API verwenden dieses Token

Format des Authorization-Headers:

Authorization: Bearer YOUR_DA_USER_IMS_TOKEN

oder einfach:

Authorization: YOUR_DA_USER_IMS_TOKEN

Hinweis: Wenn Sie über die öffentliche (authentifizierte) URL des API-Routers auf die API zugreifen, wird die IMS-Anmeldung (Adobe Identity Management Service) automatisch vom AEM-API-Router übernommen. In diesem Fall müssen Sie kein DA-Admin-API-Token im Authorization-Header angeben – der IMS-Anmeldeablauf übernimmt die Authentifizierung für Sie.

Anwendungsbeispiele

Nach der Konfiguration können Sie Ihren KI-Assistenten bitten, DA-Vorgänge durchzuführen:

Claude, can you list all the sources in the adobe/my-docs repository?

Please get the content of docs/index.md from the adobe/my-docs repository.

Create a new file at docs/new-page.md with some markdown content.

API-Endpunkte

GET /health

Health-Check-Endpunkt, der den Serverstatus zurückgibt.

Antwort:

{
  "status": "healthy",
  "service": "da-mcp",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2025-01-07T12:00:00.000Z"
}

POST /mcp

MCP-Protokollendpunkt für die Tool-Ausführung. Erfordert den Authorization-Header mit dem DA-Admin-API-Token.

Fehlerbehandlung

Alle Tools enthalten eine umfassende Fehlerbehandlung:

• 401 Unauthorized: Fehlendes oder ungültiges DA-Admin-Token

• 404 Not Found: Ungültiger Endpunkt

• 408 Timeout: Die Anfrage dauerte länger als 30 Sekunden

• 500 Internal Error: Serverfehler mit Details

Die Fehler sind so formatiert, dass sie von LLM-Clients leicht verstanden werden können.

Protokollierung

Der Server protokolliert wichtige Ereignisse und Fehler in den Cloudflare-Workers-Protokollen:

# View logs in real-time
wrangler tail

# View logs for specific environment
wrangler tail --env production

Überwachung

Überwachen Sie Ihren bereitgestellten Worker:

1. Cloudflare-Dashboard: Aufrufe, Fehler und Leistung anzeigen

2. Wrangler Tail: Echtzeitprotokolle (wrangler tail)

3. Health-Endpunkt: Regelmäßige Health-Checks unter /health

Mitwirken

Beiträge sind willkommen! Bitte:

1. Forken Sie das Repository

2. Erstellen Sie einen Feature-Branch

3. Nehmen Sie Ihre Änderungen mit Tests vor

4. Reichen Sie einen Pull-Request ein