Servidor MCP de ShapeShyft API

Servidor MCP (Model Context Protocol) que describe y maneja la API de ShapeShyft — la plataforma de salida estructurada para LLM donde cada endpoint configurado se convierte en una URL REST que devuelve JSON conforme al esquema.

Proporciona a un asistente de IA cuatro cosas:

• 61 herramientas que cubren todas las rutas de la API de ShapeShyft — entidades, claves de proveedor de LLM, proyectos, endpoints, analíticas, límites de tasa, almacenamiento, usuarios e invocación de IA.

• 6 recursos de documentación que describen la propia API (visión general, rutas, modelo de datos, ejemplos prácticos, errores, proveedores) — legibles sin credenciales y sin llamada de red.

• 3 plantillas de prompt para flujos de trabajo comunes: configurar un endpoint, depurarlo, auditar una entidad.

• La habilidad /shapeshyft-endpoint — un flujo de trabajo guiado para construir, invocar, depurar y auditar endpoints, distribuido como un plugin de Claude Code.

Paquete: @sudobility/shapeshyft_api_mcp (BUSL-1.1)

Instalación

bun install

Related MCP server: Swagger MCP Server

Configuración

Obtener una clave

Crea una clave de API personal una vez, en shapeshyft.ai → Panel de control → Configuración → Claves de API personales → asígnale un nombre → Crear clave. Empieza con shyft_ y no caduca. Entrégasela al servidor y deja que la recuerde:

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

Eso escribe ~/.shapeshyft/config.json (modo 0600), de modo que las sesiones posteriores comienzan autenticadas sin nada más que configurar.

Resolución de credenciales

Mayor prioridad primero:

1. Un argumento de herramienta explícito (p. ej. apiKey en invoke_endpoint)

2. Variables de entorno

3. ~/.shapeshyft/config.json

El servidor arranca sin credenciales en absoluto — los recursos de documentación, el catálogo de proveedores y las comprobaciones de salud son públicos. Las herramientas que necesitan una credencial devuelven un error claro que indica cómo obtenerla.

Dos tipos de clave, trabajos diferentes. shyft_... es una clave personal que te autentica en las rutas de administración. sk_live_... es una clave de proyecto que permite a los llamadores invocar los endpoints de IA de un proyecto. Crear y revelar claves personales es lo único que una clave personal no puede hacer — eso necesita un token de ID de Firebase, para que una clave filtrada no pueda acuñar más.

Opción A: Instalar como plugin de Claude Code (recomendado)

Esto hace que las herramientas MCP, los recursos de documentación y la habilidad /shapeshyft-endpoint estén disponibles en cualquier proyecto.

# 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

Verifica con claude plugin details shapeshyft@shapeshyft, que lista la habilidad y el servidor MCP.

El plugin se instala como una copia en ~/.claude/plugins/cache/shapeshyft/, por lo que las ediciones en este repositorio no surten efecto hasta que actualices tanto el marketplace como el plugin:

claude plugin marketplace update shapeshyft
claude plugin update shapeshyft@shapeshyft

La copia incluye node_modules, así que ejecuta bun install aquí antes de instalar o actualizar — el servidor se ejecuta directamente desde src/index.ts.

El plugin está definido por:

• .claude-plugin/plugin.json — metadatos del plugin

• .claude-plugin/marketplace.json — entrada del marketplace

• .mcp.json — declaración del servidor MCP (lee SHAPESHYFT_* de tu entorno)

• skills/shapeshyft-endpoint/ — la habilidad /shapeshyft-endpoint

Opción B: Añadir el servidor MCP manualmente

Añade a .claude/settings.json (o .mcp.json):

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

No se necesitan credenciales en la configuración: ejecuta set_credentials({ apiKey, persist: true }) una vez y la clave vive en ~/.shapeshyft/config.json en lugar de un archivo de configuración que podría ser confirmado. Las variables de entorno siguen funcionando y tienen prioridad.

Herramientas

Documentación y salud

Identidad y claves de API personales

Proveedores (públicos)

list_providers, get_provider, list_provider_models

Las entradas de modelos llevan capacidades (entrada de visión/audio/video, salida de medios, búsqueda web) y precios en céntimos — compruébalas antes de establecer un model en un endpoint.

Invocación de IA (clave de API de proyecto)

Entidades, miembros, invitaciones (autenticación de 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

Claves de proveedor de LLM

list_llm_keys, get_llm_key, create_llm_key, update_llm_key, delete_llm_key

Proyectos

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

Analíticas, límites de tasa, almacenamiento, usuarios

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

Recursos

Prompts

setup_structured_endpoint · debug_endpoint · audit_entity

Sesión de ejemplo

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 } }

La habilidad /shapeshyft-endpoint

Instalada con el plugin, la habilidad enruta una solicitud a uno de cuatro flujos y comprueba las credenciales antes de tocar nada:

Uso:

/shapeshyft-endpoint

O simplemente describe lo que quieres:

"Convierte este prompt de clasificación en una API" "Mi endpoint sigue devolviendo la categoría incorrecta" "¿Cuánto me están costando mis endpoints de ShapeShyft este mes?"

Referencias incluidas:

• skills/shapeshyft-endpoint/references/creating-endpoints.md — referencia de campos de create_endpoint y seis recetas prácticas, cada una emparejando una carga útil de entrada con sus esquemas y respuesta

• skills/shapeshyft-endpoint/references/schema-design.md — esquemas de salida que los modelos realmente satisfacen

• skills/shapeshyft-endpoint/references/model-selection.md — elegir un proveedor y modelo según capacidades y precios

Desarrollo

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

Valida el plugin y la habilidad después de editarlos:

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

Estructura del proyecto

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

Arquitectura

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)

El servidor es un cliente HTTP ligero. Cada herramienta se asigna a una ruta REST, y la cabecera Authorization correcta se elige según la familia de rutas: un token de ID de Firebase para rutas de administración, la clave de API de proyecto para /api/v1/ai/*, nada para rutas públicas. Las respuestas se extraen de la envoltura { success, data, timestamp }; los fallos vuelven como errores de herramienta MCP que llevan el estado HTTP y cualquier details del proveedor.

Proyectos relacionados

• shapeshyft_api — el backend Hono que este servidor envuelve

• shapeshyft_types — definiciones de tipos TypeScript compartidas

• shapeshyft_client — hooks de cliente de API para aplicaciones web/nativas

• shapeshyft_lib — almacenes de lógica de negocio

• shapeshyft_app — frontend web React

Licencia

BUSL-1.1