aspro-mcp

Сервер Model Context Protocol, который предоставляет REST API Aspro.Cloud для LLM-клиентов (Claude Desktop, Claude Code и др.). Сервер поставляется с упакованной спецификацией OpenAPI, поэтому модель может самостоятельно обнаруживать модули, сущности и методы и безопасно их вызывать.

Возможности

• Самоописание. Модель просматривает API через aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe, и только затем выполняет aspro_call — нет необходимости запоминать эндпоинты.

• Поиск по подстроке среди модулей / сущностей / методов / путей / описаний / тегов.

• Form-urlencoded POST-запросы по умолчанию (ожидаемый тип контента для Aspro), с поддержкой массивов и вложенных объектов.

• Подстановка параметров пути для /get/{id}, /update/{id}, /delete/{id} и аналогичных.

• Конфигурация для каждого арендатора через ASPRO_COMPANY (поддомен) или полный ASPRO_BASE_URL.

Установка

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

Требуется Node.js ≥ 18.

Настройка

Скопируйте пример файла окружения и заполните его:

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

Получите API-ключ в своем аккаунте Aspro.Cloud в разделе Настройки → Интеграции → API.

Подключение к клиенту

Claude Desktop / Claude Code

Добавьте сервер в свою конфигурацию MCP:

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

Сервер считывает свой файл .env из корня проекта независимо от рабочей директории, из которой его запускает клиент.

Другие MCP-клиенты

Любой клиент, поддерживающий MCP через stdio, может запустить node dist/index.js (или npm start).

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

Рекомендуемый порядок работы: search/list_* → describe → call.

Разработка

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

Дымовой тест не обращается к сети — он проверяет, что упакованная спецификация OpenAPI парсится, операции могут быть описаны, а построитель URL создает корректные URL.

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

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

Заметки по безопасности

• API-ключ считывается из окружения и добавляется к каждому запросу как ?api_key=.... Никогда не коммитьте .env.

• У сервера нет списка разрешенных адресов (allowlist) — после настройки он может вызвать любой эндпоинт, описанный в спецификации (включая деструктивные, такие как /delete/{id}). Используйте выделенный API-ключ с минимально необходимыми правами.

• Относитесь к выводу инструментов как к недоверенному: сущности Aspro (значения пользовательских полей, описания и т.д.) могут содержать контент, предоставленный пользователем.

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

Приветствуются сообщения об ошибках и PR. Пожалуйста, выполните npm run build && npm run smoke перед отправкой.

Лицензия

MIT — см. LICENSE.

aspro-mcp является неофициальным сторонним коннектором и не связан с Aspro.Cloud.