ShapeShyft API MCP Server

MCP (Model Context Protocol) server that describes and drives the ShapeShyft API — the LLM structured-output platform where each configured endpoint becomes a REST URL that returns schema-conformant JSON.

It gives an AI assistant four things:

• 61 инструмент, охватывающий каждый маршрут ShapeShyft API — сущности, ключи LLM-провайдеров, проекты, endpoints, аналитику, лимиты скорости, хранилище, пользователей и вызов ИИ.

• 6 ресурсов документации, описывающих сам API (обзор, маршруты, модель данных, примеры, ошибки, провайдеры) — читаются без учётных данных и без сетевых вызовов.

• 3 шаблона промптов для типовых задач: настроить endpoint, отладить его, провести аудит сущности.

• Навык /shapeshyft-endpoint — управляемый процесс для создания, вызова, отладки и аудита endpoints, поставляемый как плагин Claude Code.

Пакет: @sudobility/shapeshyft_api_mcp (BUSL-1.1)

Установка

bun install

Related MCP server: Swagger MCP Server

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

Получение ключа

Создайте персональный API-ключ один раз на shapeshyft.ai → Панель управления → Настройки → Персональные API-ключи → дайте ему имя → Создать ключ. Он начинается с shyft_ и не истекает. Передайте его серверу и позвольте ему запомнить:

set_credentials({ apiKey: "shyft_...", persist: true })
// or, for an unattended agent that should act as the workspace:
set_credentials({ entityApiKey: "shyftent_...", persist: true })

Это записывает ~/.shapeshyft/config.json (режим 0600), так что последующие сеансы начинаются аутентифицированными, и больше ничего настраивать не нужно.

Разрешение учётных данных

Сначала наивысший приоритет:

1. Явный аргумент инструмента (например, apiKey в invoke_endpoint)

2. Переменные окружения

3. ~/.shapeshyft/config.json

Сервер запускается вообще без учётных данных — ресурсы документации, каталог провайдеров и проверки работоспособности являются публичными. Инструменты, которым нужны учётные данные, возвращают понятную ошибку с объяснением, как их получить.

Два типа ключей, разные задачи. shyft_... — это персональный ключ, который аутентифицирует вас в административных маршрутах. sk_live_... — это проектный ключ, который позволяет вызывающим обращаться к AI endpoints одного проекта. Создание и раскрытие персональных ключей — единственное, что персональный ключ не может сделать — для этого нужен Firebase ID токен, чтобы утёкший ключ не мог создавать новые.

Вариант A: Установка как плагин Claude Code (рекомендуется)

Это делает MCP-инструменты, ресурсы документации и навык /shapeshyft-endpoint доступными в любом проекте.

# Register this repo as a marketplace, then install the plugin from it
claude plugin marketplace add /path/to/shapeshyft_api_mcp
claude plugin install shapeshyft@shapeshyft

Проверьте с помощью claude plugin details shapeshyft@shapeshyft, который перечисляет навык и MCP-сервер.

Плагин устанавливается как копия в ~/.claude/plugins/cache/shapeshyft/, поэтому изменения в этом репозитории не вступают в силу, пока вы не обновите и маркетплейс, и плагин:

claude plugin marketplace update shapeshyft
claude plugin update shapeshyft@shapeshyft

Копия включает node_modules, поэтому запустите bun install здесь перед установкой или обновлением — сервер запускается прямо из src/index.ts.

Плагин определяется:

• .claude-plugin/plugin.json — метаданные плагина

• .claude-plugin/marketplace.json — запись маркетплейса

• .mcp.json — объявление MCP-сервера (читает SHAPESHYFT_* из вашего окружения)

• skills/shapeshyft-endpoint/ — навык /shapeshyft-endpoint

Вариант B: Добавление MCP-сервера вручную

Добавьте в .claude/settings.json (или .mcp.json):

{
  "mcpServers": {
    "shapeshyft-api": {
      "command": "bun",
      "args": ["run", "/path/to/shapeshyft_api_mcp/src/index.ts"]
    }
  }
}

В конфигурации не нужны учётные данные: запустите set_credentials({ apiKey, persist: true }) один раз, и ключ будет храниться в ~/.shapeshyft/config.json вместо файла настроек, который может быть закоммичен. Переменные окружения по-прежнему работают и имеют приоритет.

Инструменты

Документация и работоспособность

Идентификация и персональные API-ключи

Провайдеры (публичные)

list_providers, get_provider, list_provider_models

Записи моделей содержат возможности (ввод изображений/аудио/видео, вывод медиа, веб-поиск) и цены в центах — проверяйте их перед установкой model на endpoint.

Вызов ИИ (проектный API-ключ)

Сущности, участники, приглашения (Firebase аутентификация)

list_entities, get_entity, create_entity, update_entity, delete_entity, list_entity_members, update_member_role, remove_entity_member, list_entity_invitations, invite_member, renew_invitation, cancel_invitation, list_my_invitations, accept_invitation, decline_invitation

Ключи LLM-провайдеров

list_llm_keys, get_llm_key, create_llm_key, update_llm_key, delete_llm_key

Проекты

list_projects, get_project, create_project, update_project, delete_project, get_project_api_key, refresh_project_api_key

Endpoints

list_endpoints, get_endpoint, create_endpoint, update_endpoint, delete_endpoint

Аналитика, лимиты скорости, хранилище, пользователи

get_analytics · get_rate_limits, get_rate_limit_history · get_storage_config, set_storage_config, update_storage_config, delete_storage_config · get_user_info, get_user_subscription, get_user_settings, update_user_settings

Ресурсы

Промпты

setup_structured_endpoint · debug_endpoint · audit_entity

Пример сеанса

describe_shapeshyft_api({ section: "examples" })
list_entities()                                  -> entitySlug "acme"
create_llm_key({ key_name: "Prod Anthropic", provider: "anthropic", api_key: "sk-ant-..." })
create_project({ project_name: "support-tools", display_name: "Support Tools" })
create_endpoint({ projectId, endpoint_name: "classify-ticket", llm_key_id,
                  model: "claude-sonnet-4-6-20260217",
                  instructions: "Classify the ticket and judge sentiment.",
                  output_schema: { type: "object", properties: {
                    category:  { type: "string", enum: ["billing", "bug", "feature", "other"] },
                    sentiment: { type: "string", enum: ["positive", "neutral", "negative"] }
                  }, required: ["category", "sentiment"] } })
get_project_api_key({ projectId })
invoke_endpoint({ projectName: "support-tools", endpointName: "classify-ticket",
                  input: { text: "You billed me twice this month." } })
  -> { output: { category: "billing", sentiment: "negative" },
       usage: { tokens_input: 312, tokens_output: 18, latency_ms: 940,
                estimated_cost_cents: 0.11 } }

Навык /shapeshyft-endpoint

Устанавливаемый вместе с плагином, навык направляет запрос в один из четырёх процессов и проверяет учётные данные перед тем, как что-либо делать:

Использование:

/shapeshyft-endpoint

Или просто опишите, что вы хотите:

"Превратите этот промпт классификации в API" "Мой endpoint продолжает возвращать неправильную категорию" "Сколько стоят мои ShapeShyft endpoints в этом месяце?"

Встроенные справочники:

• skills/shapeshyft-endpoint/references/creating-endpoints.md — справочник по полям create_endpoint и шесть готовых рецептов, каждый из которых связывает входные данные с его схемами и ответом

• skills/shapeshyft-endpoint/references/schema-design.md — схемы вывода, которым модели действительно удовлетворяют

• skills/shapeshyft-endpoint/references/model-selection.md — выбор провайдера и модели на основе возможностей и цен

Разработка

bun run dev        # Run the server over stdio
bun run build      # Bundle to dist/index.js
bun run typecheck  # TypeScript check
bun run verify     # typecheck + build
bun run start      # Run the production bundle

Проверьте плагин и навык после их редактирования:

claude plugin validate .        # marketplace + plugin manifests
claude plugin validate skills   # skill frontmatter and structure

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

src/
├── index.ts            # Entry: env config, registration, stdio transport
├── client.ts           # HTTP client: auth-mode routing, envelope unwrapping
├── prompts.ts          # Prompt templates
├── resources/          # Embedded API documentation (resources + describe_shapeshyft_api)
└── tools/              # One module per route family

skills/
└── shapeshyft-endpoint/
    ├── SKILL.md                        # The /shapeshyft-endpoint skill
    └── references/
        ├── creating-endpoints.md       # create_endpoint recipes with payload examples
        ├── schema-design.md            # Output schema design guide
        └── model-selection.md          # Provider and model selection guide

.claude-plugin/         # plugin.json + marketplace.json
.mcp.json               # MCP server declaration used by the plugin

Архитектура

AI assistant (Claude Code / Claude Desktop)
    ↕ stdio (MCP protocol)
ShapeShyft API MCP server (this project)
    ↕ HTTP / REST
ShapeShyft API (Hono on Bun, PostgreSQL)
    ↕
10 LLM providers (OpenAI, Anthropic, Gemini, Groq, Mistral, xAI, DeepSeek,
                  Perplexity, Cohere, LM Studio)

Сервер — это тонкий HTTP-клиент. Каждый инструмент сопоставляется с одним REST-маршрутом, и правильный заголовок Authorization выбирается из семейства маршрутов: Firebase ID токен для административных маршрутов, проектный API-ключ для /api/v1/ai/*, ничего для публичных маршрутов. Ответы извлекаются из обёртки { success, data, timestamp }; сбои возвращаются как ошибки MCP-инструментов с HTTP-статусом и любыми details провайдера.

Связанные проекты

• shapeshyft_api — бэкенд Hono, который оборачивает этот сервер

• shapeshyft_types — общие определения типов TypeScript

• shapeshyft_client — хуки API-клиента для веб/нативных приложений

• shapeshyft_lib — хранилища бизнес-логики

• shapeshyft_app — веб-фронтенд на React

Лицензия

BUSL-1.1