jaicp-mcp

MCP-сервер для работы AI-агентов с JAICP и Tovie Platform

Русский · English

jaicp-mcp подключает MCP-клиенты — Cursor, Claude Code, Codex CLI и другие — к HTTP API JAICP и Tovie Platform.

Сервер строит запросы по официальным OpenAPI, проверяет параметры до обращения к сети и защищает mutating-операции. Один и тот же контракт содержит 160 операций для обоих облаков.

Возможности

• семь API: проекты, каналы, аналитика, асинхронные отчёты, текстовые рассылки, CAILA и Dialer;

• автоматическая подстановка required/default-параметров из OpenAPI;

• JSON, form-urlencoded, multipart-файлы из base64 и бинарные ответы;

• защита мутаций через confirm и глобальный режим JAICP_READ_ONLY;

• таймауты, запрет redirect, лимит ответа и редакция типичных секретов;

• одинаковый контракт для JAICP и Tovie Platform — меняются только хост и токены;

• полностью автономные тесты без запросов к реальным API.

Related MCP server: Open API MCP Server

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

1. Установите сервер

Требуются Git и Node.js 20 или новее.

git clone https://github.com/CryLeech/jaicp-mcp.git
cd jaicp-mcp
npm ci
cp .env.example .env

В PowerShell последняя команда выглядит так:

Copy-Item .env.example .env

2. Добавьте токен

Откройте .env и укажите как минимум unified-токен из раздела JAICP/Tovie «Доступ к API»:

JAICP_HOST=https://app.jaicp.com
JAICP_UNIFIED_TOKEN=your-unified-token
JAICP_PROJECT_SHORT_NAME=your-project-short-name

Для Tovie Platform используйте JAICP_HOST=https://platform.tovie.ai и токен, выпущенный этим облаком.

3. Подключите MCP-клиент

Добавьте сервер в ~/.cursor/mcp.json или .cursor/mcp.json, заменив путь на абсолютный:

{
  "mcpServers": {
    "jaicp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/jaicp-mcp/src/server.mjs"]
    }
  }
}

После перезапуска Cursor сервер предоставит три инструмента: jaicp_specs, jaicp_operations и jaicp_call.

claude mcp add --transport stdio jaicp -- node /absolute/path/to/jaicp-mcp/src/server.mjs

Подробнее: Claude Code MCP.

[mcp_servers.jaicp]
command = "node"
args = ["/absolute/path/to/jaicp-mcp/src/server.mjs"]
cwd = "/absolute/path/to/jaicp-mcp"

Подробнее: Codex MCP.

Примеры запросов

После подключения можно обращаться к API обычным языком:

• «Покажи список проектов JAICP».

• «Найди операции для получения статистики сессий».

• «Покажи текстовые рассылки проекта my-project».

• «Экспортируй интенты CAILA».

Перед вызовом сервер найдёт точную OpenAPI-операцию, проверит обязательные параметры и определит, изменяет ли она данные.

Инструменты

jaicp_specs

Показывает подключённые API, хост, версию сервера и наличие нужных токенов. Значения токенов не возвращаются.

jaicp_operations

Ищет операции одной спеки по operationId, пути, тегу или описанию. Возвращает required/default-параметры, форматы тела и ответа, а также признак мутации.

jaicp_call

Выполняет операцию по spec + operationId. При совпадающих operationId принимает точный OpenAPI path для дизамбигуации.

{
  "spec": "project",
  "operationId": "getByProjectShortName",
  "pathParams": {
    "projectShortName": "my-project"
  }
}

Поддерживаемые API

• bot-channel — JAICP · Tovie

• project — JAICP · Tovie

• reporter — JAICP · Tovie

• async — JAICP · Tovie

• text-campaign — JAICP · Tovie

• caila — JAICP · Tovie

• calls — JAICP · Tovie

Vendored-копии YAML находятся в vendor/specs/. npm run check-specs сравнивает их с файлами обоих облаков.

Конфигурация

Сервер ищет конфигурацию в ~/.cursor/secrets/jaicp.env, затем в .env проекта. Явные переменные окружения имеют приоритет.

JAICP_PROJECT_SHORT_NAME подставляется и в query, и в {projectShortName} path.

Безопасность

• мутации определяются по HTTP-методу и x-security-authority;

• Dialer addPhone* считается мутацией даже при использовании GET;

• path-параметры с /, \, dot-segments и управляющими символами отклоняются;

• автоматические HTTP-redirect запрещены;

• multipart принимает base64, но не читает произвольные локальные пути;

• сервер редактирует типичные токены, но не обещает удалять персональные данные;

• reporter-выгрузки могут содержать персональные данные.

HTTP без TLS разрешён только для localhost. Для явного dev-исключения существует JAICP_ALLOW_INSECURE_HOST=1.

Форматы данных

• JSON используется по умолчанию;

• application/x-www-form-urlencoded поддерживается для Dialer;

• multipart/form-data принимает { filename, mediaType, data }, где data — base64;

• JSON и text-ответы возвращаются как текст MCP;

• application/octet-stream возвращается как MCP embedded resource.

Разработка

npm test
npm run check
npm run check-specs
openspec validate --all --strict --no-interactive

Изменения проектируются через OpenSpec. Активные изменения находятся в openspec/changes/.

Лицензия

Исходный код распространяется по MIT. JAICP и связанные знаки принадлежат Just AI; Tovie AI Platform и связанные знаки — Tovie AI. Подробнее: NOTICE.md.