da-mcp

Un servidor remoto de Model Context Protocol (MCP) para Document Authoring (DA). Este servidor proporciona a asistentes de LLM como Claude o ChatGPT acceso directo a las operaciones de gestión de DA.

Características

• 10 DA Admin Tools: Conjunto completo de herramientas para gestionar repositorios DA

• Acceso remoto: Desplegable en Cloudflare Workers con distribución global en el edge

• Streamable HTTP: Protocolo de transporte MCP moderno para servidores remotos

• Paso de tokens: Autenticación simple pasando tokens de la API de DA a través de la cabecera Authorization

• Listo para producción: Manejo de errores, registro, soporte CORS y comprobaciones de salud

• TypeScript: Base de código totalmente tipada para fiabilidad y mantenibilidad

Related MCP server: Core Content Services MCP Server

Arquitectura

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

Estructura del Proyecto

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

Herramientas Disponibles

Requisitos previos

• Node.js 18+ y npm

• Cuenta de Cloudflare (el plan gratuito funciona)

• CLI de Wrangler instalada (npm install -g wrangler)

• Token de la API de DA Admin

Instalación

1. Clona e instala las dependencias:

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

2. Configura Wrangler:

Edita wrangler.toml si es necesario para personalizar la configuración de tu despliegue.

Desarrollo

Desarrollo local

Ejecuta el servidor localmente con recarga automática:

npm run dev

El servidor estará disponible en http://localhost:8787

Endpoints de prueba

• Comprobación de salud: http://localhost:8787/health

• Endpoint MCP: http://localhost:8787/mcp

Pruebas con MCP Inspector

1. Inicia el servidor local: npm run dev

2. Abre MCP Inspector

3. Configura la conexión:

   • Tipo: Streamable HTTP

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

   • Cabeceras: Authorization: Bearer YOUR_DA_TOKEN

Despliegue

Desplegar en Cloudflare Workers

# Deploy to production
npm run deploy

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

URLs públicas

Tras el despliegue, tu servidor MCP está disponible en:

• Endpoint MCP directo:
  https://da-mcp.adobeaem.workers.dev/mcp

• Autenticado con IMS a través de AEM API Router:
  https://mcp.adobeaemcloud.com/adobe/mcp/da
  (Admite inicio de sesión de Adobe IMS. Consulta la sección Autenticación a continuación para más detalles.)

Configuración del cliente

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o equivalente:

{
  "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

Añade a .vscode/mcp.json o a la configuración de Cursor:

{
  "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"
    }
  }
}

Autenticación

El servidor utiliza una autenticación simple de paso de tokens:

1. El cliente envía el token de la API de DA Admin en la cabecera Authorization

2. El servidor extrae el token y lo pasa a la API de DA Admin

3. Todas las solicitudes a la API de DA Admin usan este token

Formato de la cabecera Authorization:

Authorization: Bearer YOUR_DA_USER_IMS_TOKEN

o simplemente:

Authorization: YOUR_DA_USER_IMS_TOKEN

Nota: Si estás accediendo a la API a través de la URL pública (autenticada) del enrutador de API, el inicio de sesión de IMS (Adobe Identity Management Service) se gestiona automáticamente mediante el enrutador de API de AEM. En este caso, no necesitas proporcionar un token de la API de DA Admin en la cabecera Authorization; el flujo de inicio de sesión de IMS proporcionará la autenticación por ti.

Ejemplos de uso

Una vez configurado, puedes pedir a tu asistente de IA que realice operaciones de DA:

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.

Endpoints de la API

GET /health

Endpoint de comprobación de salud que devuelve el estado del servidor.

Respuesta:

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

POST /mcp

Endpoint del protocolo MCP para la ejecución de herramientas. Requiere la cabecera Authorization con el token de la API de DA Admin.

Manejo de errores

Todas las herramientas incluyen un manejo integral de errores:

• 401 Unauthorized: Falta el token de DA Admin o no es válido

• 404 Not Found: Endpoint no válido

• 408 Timeout: La solicitud tardó más de 30 segundos

• 500 Internal Error: Errores del lado del servidor con detalles

Los errores están formateados para que los clientes de LLM los entiendan fácilmente.

Registro

El servidor registra eventos importantes y errores en los registros de Cloudflare Workers:

# View logs in real-time
wrangler tail

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

Monitorización

Monitoriza tu Worker desplegado:

1. Cloudflare Dashboard: Consulta invocaciones, errores y rendimiento

2. Wrangler Tail: Registros en tiempo real (wrangler tail)

3. Endpoint de salud: Comprobaciones de salud periódicas en /health

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haz un fork del repositorio

2. Crea una rama de características

3. Realiza tus cambios con pruebas

4. Envía una pull request