CDP MCP Server

MCP-сервер (Model Context Protocol), который предоставляет вашей LLM доступ к Customer Data Platform от Acquia. Подключите Claude, Copilot или любой другой клиент с поддержкой MCP к этому серверу, и он сможет считывать данные ваших арендаторов, запускать кампании, работать с рабочими процессами, запрашивать отчеты и в целом выполнять скучную административную работу за вас.

Создан, потому что кликать по экранам CDP в 2 часа ночи — сомнительное удовольствие.

Что вы получаете

• ~300 инструментов, охватывающих разрешения, хранилище данных, кампании, конфигурацию, коннекторы, отчеты, прогнозы, рассылки, страницы для email-рассылок, безопасность, кэш и API статусов — полный каталог см. в SUPPORTED_TOOLS.md

• 8 ресурсов-плейбуков, которые обучают LLM последовательности реальных многошаговых процессов (мастер кампаний, рендеринг профиля C360, создание рабочих процессов, подключение коннекторов, редактирование схемы UDMP и т. д.) — они были получены путем обратной разработки интерфейсов Vega и Config, чтобы модель перестала гадать

• Два режима аутентификации: OAuth2 password grant (автоматическое обновление, повтор при 401, сериализация блокировок) или статический токен bearer, если он у вас уже есть

• Переключение между Dev / QA / Prod с помощью одной переменной CDP_ENVIRONMENT

• Транспорт Stdio, поэтому он легко интегрируется в Claude Desktop, VS Code Copilot, Continue, mcphost, Open WebUI (через supergateway) или MCP Inspector

Если вышесказанное звучит как «алфавитный суп», просмотрите TUTORIAL.md — там пошагово описан каждый элемент с командами, которые можно копировать и вставлять. Полный список названий инструментов и описание функций каждого из них см. в SUPPORTED_TOOLS.md.

Быстрый старт

# 1. Clone and install
git clone https://github.com/atharva-joshi77/cdp-mcp.git
cd cdp-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Configure
cp .env.example .env
# edit .env: CDP_ENVIRONMENT, CDP_TENANT_ID, and either
#   CDP_CLIENT_ID/SECRET + CDP_USERNAME/PASSWORD  (OAuth2)
# or CDP_AUTH_TOKEN                                (static token)

# 3. Run
cdp-mcp

cdp-mcp использует JSON-RPC через stdio, поэтому при обычном запуске может показаться, что он завис — это нормально. Подключите его к MCP-клиенту (см. ниже), и он заработает.

Подключение к Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cdp": {
      "command": "/absolute/path/to/cdp-mcp/.venv/bin/cdp-mcp",
      "env": {
        "CDP_ENVIRONMENT": "dev",
        "CDP_TENANT_ID": "12345",
        "CDP_CLIENT_ID": "...",
        "CDP_CLIENT_SECRET": "...",
        "CDP_USERNAME": "...",
        "CDP_PASSWORD": "..."
      }
    }
  }
}

Перезапустите Claude, и вы увидите около 300 инструментов cdp_* в средстве выбора инструментов. Для настройки VS Code, Continue, Ollama/Open WebUI и MCP Inspector полные инструкции находятся в TUTORIAL.md §5.

Требования

Зависимости (устанавливаются автоматически):

• mcp>=1.13.0 — фреймворк FastMCP

• httpx>=0.27.0 — асинхронный HTTP

• pydantic + pydantic-settings — конфигурация + валидация

• python-dotenv — загрузка .env

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

src/cdp_mcp/
├── __main__.py           # entry point: `cdp-mcp` / `python -m cdp_mcp`
├── server.py             # FastMCP server, registers tools + resources
├── config.py             # env/.env loader
├── auth/                 # OAuth2 + static-token provider
├── utils/                # shared httpx client, error helpers
├── resources/            # MCP resource URIs (tenant/*, docs/*)
├── docs/                 # the eight playbooks, shipped as resources
├── types/                # pydantic request/response models
└── tools/                # one subpackage per CDP service area
    ├── permissions/      users, roles, clients
    ├── dw/               data warehouse, A360, audiences, offers, trackers
    ├── campaign/         defs, audiences, messages, dispatches, runs, exports
    ├── config_api/       tenants, workflows, schedules, UDMP, DQE, clusters…
    ├── connectors/       input + output connectors, templates
    ├── reports/          dashboards, widgets, cubes, QL
    ├── predictions/      prediction defs + content templates
    ├── mailer/           accounts, subusers, identifiers, batches
    ├── emailable_pages/  emailable-pages CRUD
    ├── security/         token, auth, SSO, password reset
    ├── cache/            cache ops
    ├── spam/             spam score
    ├── status/           status + orchestration/purge status
    ├── provisions/       self-service provisioning
    ├── global_actions/   platform-wide actions
    └── alerts/           stub (real Alerts API lives in a different stack)

Каждый инструмент использует общий HttpClient с пулом соединений httpx, общим кэшем токенов аутентификации, asyncio.Lock для обновлений, однократным повтором при 401, URL-кодированными ID арендаторов и трассировкой запросов/ответов через logger.info. Если что-то кажется неправильным, логи обычно говорят правду.

Плейбуки (секретный ингредиент)

Списка инструментов недостаточно — многие процессы CDP представляют собой «POST определения, затем POST ?action=publish, затем GET статуса, затем, возможно, POST ?action=schedule с отдельным ID расписания». LLM часто ошибается в этом, если оставить её без присмотра.

Поэтому сервер поставляет восемь плейбуков в формате Markdown в качестве ресурсов MCP:

MCP-клиенты автоматически обнаруживают их при подключении, а блок instructions сервера указывает модели на каждый из них.

Примечания по аутентификации

• OAuth2 (предпочтительно): провайдер выполняет POST {baseUrl}/token?action=create с учетными данными в заголовках, кэширует токен в памяти, сериализует одновременные обновления за asyncio.Lock и обновляет токен примерно за 60 секунд до истечения срока действия. Любая ошибка 401 от последующего вызова запускает однократное принудительное обновление + повтор.

• Статический токен: установите CDP_AUTH_TOKEN, и путь OAuth2 будет полностью пропущен. Вы сами отвечаете за ротацию.

Никогда не помещайте реальные секреты в этот репозиторий. .env добавлен в gitignore.

Разработка

# smoke test: should print the server's capabilities + tool list
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' | cdp-mcp

# interactive tool browser
npx @modelcontextprotocol/inspector cdp-mcp

# verify tool count
python3 -c "from cdp_mcp.server import create_server; import asyncio; \
  print(len(asyncio.run(create_server().list_tools())))"

Более полная матрица устранения неполадок (сервер не запускается, 401, клиент не может подключиться и т. д.) находится в TUTORIAL.md §9.

Статус

• Количество инструментов: 301 в 12 сервисах CDP

• Ресурсы-плейбуки: 8

• Инструменты оповещений (Alerts) намеренно заглушены — реальный API оповещений находится в отдельном стеке MuleSoft/Go, которому нужен свой базовый URL и аутентификация (PR приветствуются)

• Инструментарий интеграционного тестирования находится в процессе разработки (каркас присутствует, полное покрытие контрактов отслеживается как последующая задача)

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

1. Сделайте форк, создайте ветку, вносите изменения.

2. Запустите ./gradlew-equivalent — ладно, просто pip install -e . и дымовой тест выше.

3. Если вы добавляете инструмент, зарегистрируйте его в соответствующем tools/<area>/__init__.py.

4. Если вы добавляете многошаговый процесс, напишите для него плейбук в src/cdp_mcp/docs/ и зарегистрируйте ресурс в resources/resource_providers.py.

5. Откройте PR. Будьте вежливы в описании.

Лицензия

Внутренняя / проприетарная — проконсультируйтесь с Acquia перед использованием вне вашего арендатора.

Создано с равными долями httpx, pydantic и злости на глючные мастера CDP.