da-mcp

Удалённый сервер Model Context Protocol (MCP) для управления документами (Document Authoring, DA). Этот сервер предоставляет LLM-ассистентам, таким как Claude или ChatGPT, прямой доступ к операциям управления DA.

Возможности

• 10 DA Admin Tools: Полный набор инструментов для управления репозиториями DA

• Удалённый доступ: Развёртывание на Cloudflare Workers с глобальным распределением на периферии

• Streamable HTTP: Современный транспортный протокол MCP для удалённых серверов

• Сквозная передача токена: Простая аутентификация путём передачи DA API-токенов через заголовок Authorization

• Готовность к продакшену: Обработка ошибок, логирование, поддержка CORS и проверки работоспособности

• TypeScript: Полностью типизированная кодовая база для надёжности и простоты сопровождения

Related MCP server: Core Content Services MCP Server

Архитектура

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

Структура проекта

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

Доступные инструменты

Предварительные требования

• Node.js 18+ и npm

• Аккаунт Cloudflare (подойдёт бесплатный тариф)

• Установленный Wrangler CLI (npm install -g wrangler)

• Токен DA Admin API

Установка

1. Клонируйте репозиторий и установите зависимости:

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

2. Настройте Wrangler:

При необходимости отредактируйте wrangler.toml, чтобы настроить параметры развёртывания.

Разработка

Локальная разработка

Запустите сервер локально с горячей перезагрузкой:

npm run dev

Сервер будет доступен по адресу http://localhost:8787

Тестовые эндпоинты

• Проверка работоспособности: http://localhost:8787/health

• MCP-эндпоинт: http://localhost:8787/mcp

Тестирование с помощью MCP Inspector

1. Запустите локальный сервер: npm run dev

2. Откройте MCP Inspector

3. Настройте подключение:

   • Тип: Streamable HTTP

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

   • Заголовки: Authorization: Bearer YOUR_DA_TOKEN

Развёртывание

Развёртывание на Cloudflare Workers

# Deploy to production
npm run deploy

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

Публичные URL-адреса

После развёртывания ваш MCP-сервер доступен по адресам:

• Прямой MCP-эндпоинт:
  https://da-mcp.adobeaem.workers.dev/mcp

• С аутентификацией IMS через AEM API Router:
  https://mcp.adobeaemcloud.com/adobe/mcp/da
  (Поддерживает вход через Adobe IMS. Подробнее см. в разделе Аутентификация ниже.)

Конфигурация клиентов

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или аналогичный файл:

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

Добавьте в .vscode/mcp.json или настройки 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"
    }
  }
}

Аутентификация

Сервер использует простую сквозную аутентификацию по токену:

1. Клиент отправляет токен DA Admin API в заголовке Authorization

2. Сервер извлекает токен и передаёт его в DA Admin API

3. Все запросы к DA Admin API используют этот токен

Формат заголовка Authorization:

Authorization: Bearer YOUR_DA_USER_IMS_TOKEN

или просто:

Authorization: YOUR_DA_USER_IMS_TOKEN

Примечание: Если вы обращаетесь к API через публичный (аутентифицированный) URL-адрес API-роутера, вход через IMS (Adobe Identity Management Service) автоматически обрабатывается AEM API router. В этом случае вам не нужно указывать токен DA Admin API в заголовке Authorization — поток входа IMS обеспечит аутентификацию за вас.

Примеры использования

После настройки вы можете попросить вашего ИИ-ассистента выполнять операции 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.

Эндпоинты API

GET /health

Эндпоинт проверки работоспособности, возвращающий статус сервера.

Ответ:

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

POST /mcp

Эндпоинт протокола MCP для выполнения инструментов. Требует заголовок Authorization с токеном DA Admin API.

Обработка ошибок

Все инструменты включают комплексную обработку ошибок:

• 401 Unauthorized: Отсутствует или недействителен токен DA Admin

• 404 Not Found: Неверный эндпоинт

• 408 Timeout: Запрос занял более 30 секунд

• 500 Internal Error: Ошибки на стороне сервера с подробностями

Ошибки форматируются так, чтобы их было легко понять LLM-клиентам.

Логирование

Сервер записывает важные события и ошибки в логи Cloudflare Workers:

# View logs in real-time
wrangler tail

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

Мониторинг

Отслеживайте состояние развёрнутого Worker:

1. Cloudflare Dashboard: просматривайте вызовы, ошибки и производительность

2. Wrangler Tail: логи в реальном времени (wrangler tail)

3. Health Endpoint: регулярные проверки работоспособности по адресу /health

Участие в разработке

Вклад приветствуется! Пожалуйста:

1. Сделайте форк репозитория

2. Создайте feature-ветку

3. Внесите изменения с тестами

4. Отправьте pull request