# Gravity Docs MCP

Gravity Docs MCP подключает публичную документацию Gravity Field к AI-ассистентам и IDE с поддержкой [Model Context Protocol](https://modelcontextprotocol.io/).

Сервер помогает находить инструкции по кампаниям, аудиториям, интеграциям, SDK, API, рекомендациям, A/B-тестам, отчётам, каталогам, Shopping Assistant и Retail Media.

## Возможности и ограничения

Gravity Docs MCP:

- работает только на чтение;
- использует публичную документацию Gravity Field;
- не требует API-ключа или bearer-токена;
- не получает доступ к аккаунту, секциям, кампаниям и отчётам клиента;
- не изменяет настройки и данные в Gravity Field.

Gravity Docs MCP не заменяет OpenAPI. Используйте его для поиска инструкций и объяснений, а OpenAPI — для проверки точных HTTP-контрактов, полей и схем.

## Адрес сервера

Подключите MCP-сервер по адресу:

```text
https://dashboard-ai.gravityfield.ai/api/mcp/gravity-docs/mcp
```

Сервер использует удалённое подключение Streamable HTTP. Дополнительные HTTP-заголовки не требуются.

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

| Инструмент | Назначение |
| :--- | :--- |
| `searchGravityFieldDocs` | Ищет информацию в документации и возвращает релевантные фрагменты со ссылками на `docs.gravityfield.ai`. За один запрос возвращается до восьми разных статей. |
| `getGravityFieldDoc` | Загружает статью в Markdown по точному пути из результата поиска. Большие статьи возвращаются постранично. |

Обычно сначала достаточно вызвать `searchGravityFieldDocs`. Используйте `getGravityFieldDoc`, если поискового фрагмента недостаточно или нужен полный контекст статьи.

## Подключение в Cursor

Добавьте сервер в проектный файл `.cursor/mcp.json` или в глобальный файл `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gravity-docs": {
      "url": "https://dashboard-ai.gravityfield.ai/api/mcp/gravity-docs/mcp"
    }
  }
}
```

После изменения конфигурации перезапустите Cursor.

## Подключение в Codex

Codex Desktop, CLI и расширение для IDE используют общий файл `config.toml`.

Добавьте сервер в глобальный файл `~/.codex/config.toml` или в `.codex/config.toml` внутри доверенного проекта:

```toml
[mcp_servers.gravity-docs]
url = "https://dashboard-ai.gravityfield.ai/api/mcp/gravity-docs/mcp"
```

После изменения конфигурации перезапустите Codex.

## Как использовать

После подключения можно задавать AI-ассистенту вопросы о Gravity Field, например:

- «Как передать событие покупки через API V2?»
- «Чем отличаются Web-, API- и Hybrid-интеграции?»
- «Как выбрать основную метрику A/B-теста?»
- «Найди ограничения для товарного фида и приведи ссылку на документацию».

Для сложного вопроса попросите ассистента выполнить несколько точных поисков: отдельно найти основной сценарий, ограничения, примеры и troubleshooting. В ответе следует использовать ссылки на `docs.gravityfield.ai`, возвращённые MCP-сервером.

## Чем отличается от SDK API MCP

`SDK API` MCP, описанный в [гайде по прямой API-интеграции для Flutter](./SDK/flutter_api_integration_guide.md), предназначен для просмотра актуальных endpoints и схем OpenAPI.

Gravity Docs MCP ищет по пользовательской документации и подходит для вопросов о возможностях продукта, настройке, интеграции и устранении проблем. При разработке API-интеграции можно использовать оба сервера:

- Gravity Docs MCP — чтобы понять сценарий и найти инструкцию;
- `SDK API` MCP — чтобы проверить точный API-контракт.