ShapeShyft API MCP Server

MCP-Server (Model Context Protocol), der die ShapeShyft-API beschreibt und steuert – die Plattform für strukturierte LLM-Ausgaben, auf der jeder konfigurierte Endpunkt zu einer REST-URL wird, die schema-konformes JSON zurückgibt.

Es bietet einem KI-Assistenten vier Dinge:

• 61 Tools, die jede ShapeShyft-API-Route abdecken – Entitäten, LLM-Provider-Schlüssel, Projekte, Endpunkte, Analysen, Rate Limits, Speicher, Benutzer und KI-Aufrufe.

• 6 Dokumentationsressourcen, die die API selbst beschreiben (Überblick, Routen, Datenmodell, Beispiele, Fehler, Provider) – lesbar ohne Anmeldedaten und ohne Netzwerkaufruf.

• 3 Prompt-Vorlagen für häufige Arbeitsabläufe: Endpunkt einrichten, einen debuggen, eine Entität prüfen.

• Der /shapeshyft-endpoint-Skill – ein geführter Arbeitsablauf zum Erstellen, Aufrufen, Debuggen und Prüfen von Endpunkten, geliefert als Claude-Code-Plugin.

Paket: @sudobility/shapeshyft_api_mcp (BUSL-1.1)

Installation

bun install

Related MCP server: Swagger MCP Server

Konfiguration

Einen Schlüssel erhalten

Erstellen Sie einmalig einen persönlichen API-Schlüssel unter shapeshyft.ai → Dashboard → Einstellungen → Persönliche API-Schlüssel → benennen Sie ihn → Schlüssel erstellen. Er beginnt mit shyft_ und läuft nicht ab. Übergeben Sie ihn dem Server und lassen Sie ihn ihn sich merken:

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

Das schreibt ~/.shapeshyft/config.json (Modus 0600), sodass spätere Sitzungen authentifiziert starten, ohne dass etwas weiteres konfiguriert werden muss.

Auflösung der Anmeldedaten

Höchste Priorität zuerst:

1. Ein explizites Tool-Argument (z. B. apiKey bei invoke_endpoint)

2. Umgebungsvariablen

3. ~/.shapeshyft/config.json

Der Server startet ohne jegliche Anmeldedaten – die Dokumentationsressourcen, der Provider-Katalog und die Health-Checks sind öffentlich. Tools, die eine Anmeldedaten benötigen, geben einen klaren Fehler zurück, der erklärt, wie man sie erhält.

Zwei Schlüsseltypen, verschiedene Aufgaben. shyft_... ist ein persönlicher Schlüssel, der Sie gegenüber den Admin-Routen authentifiziert. sk_live_... ist ein Projektschlüssel, der Aufrufern erlaubt, die KI-Endpunkte eines Projekts aufzurufen. Das Erstellen und Anzeigen persönlicher Schlüssel ist das Einzige, was ein persönlicher Schlüssel nicht kann – dafür ist ein Firebase-ID-Token erforderlich, sodass ein geleakter Schlüssel keine weiteren erstellen kann.

Option A: Als Claude-Code-Plugin installieren (empfohlen)

Dadurch werden die MCP-Tools, die Dokumentationsressourcen und die /shapeshyft-endpoint-Skill in jedem Projekt verfügbar.

# 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

Überprüfen Sie mit claude plugin details shapeshyft@shapeshyft, das die Skill und den MCP-Server auflistet.

Das Plugin wird als Kopie unter ~/.claude/plugins/cache/shapeshyft/ installiert. Änderungen in diesem Repository werden daher erst wirksam, wenn Sie sowohl den Marketplace als auch das Plugin aktualisieren:

claude plugin marketplace update shapeshyft
claude plugin update shapeshyft@shapeshyft

Die Kopie enthält node_modules. Führen Sie daher vor der Installation oder Aktualisierung bun install aus – der Server läuft direkt aus src/index.ts.

Das Plugin wird definiert durch:

• .claude-plugin/plugin.json – Plugin-Metadaten

• .claude-plugin/marketplace.json – Marketplace-Eintrag

• .mcp.json – MCP-Server-Deklaration (liest SHAPESHYFT_* aus Ihrer Umgebung)

• skills/shapeshyft-endpoint/ – die /shapeshyft-endpoint-Skill

Option B: Den MCP-Server manuell hinzufügen

Fügen Sie zu .claude/settings.json (oder .mcp.json) hinzu:

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

In der Konfiguration sind keine Anmeldedaten erforderlich: Führen Sie einmalig set_credentials({ apiKey, persist: true }) aus, und der Schlüssel liegt in ~/.shapeshyft/config.json statt in einer Einstellungsdatei, die möglicherweise eingecheckt wird. Umgebungsvariablen funktionieren weiterhin und haben Vorrang.

Tools

Dokumentation und Health

Identität und persönliche API-Schlüssel

Provider (öffentlich)

list_providers, get_provider, list_provider_models

Modelleinträge enthalten Fähigkeiten (Bild-/Audio-/Videoeingabe, Medienausgabe, Websuche) und Preise in Cent – prüfen Sie sie, bevor Sie ein model auf einem Endpunkt festlegen.

KI-Aufruf (Projekt-API-Schlüssel)

Entitäten, Mitglieder, Einladungen (Firebase-Authentifizierung)

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-Provider-Schlüssel

list_llm_keys, get_llm_key, create_llm_key, update_llm_key, delete_llm_key

Projekte

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

Endpunkte

list_endpoints, get_endpoint, create_endpoint, update_endpoint, delete_endpoint

Analysen, Rate Limits, Speicher, Benutzer

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

Ressourcen

Prompts

setup_structured_endpoint · debug_endpoint · audit_entity

Beispielsitzung

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

Der /shapeshyft-endpoint-Skill

Mit dem Plugin installiert, leitet die Skill eine Anfrage in einen von vier Abläufen und prüft Anmeldedaten, bevor sie etwas anfasst:

Verwendung:

/shapeshyft-endpoint

Oder beschreiben Sie einfach, was Sie möchten:

„Machen Sie aus diesem Klassifizierungs-Prompt eine API" „Mein Endpunkt gibt immer wieder die falsche Kategorie zurück" „Was kosten meine ShapeShyft-Endpunkte in diesem Monat?"

Gebündelte Referenzen:

• skills/shapeshyft-endpoint/references/creating-endpoints.md – create_endpoint-Feldreferenz und sechs ausgearbeitete Rezepte, die jeweils eine Eingabe-Payload mit ihren Schemas und der Antwort kombinieren

• skills/shapeshyft-endpoint/references/schema-design.md – Ausgabeschemas, die Modelle tatsächlich erfüllen

• skills/shapeshyft-endpoint/references/model-selection.md – Auswahl eines Providers und Modells anhand von Fähigkeiten und Preisen

Entwicklung

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

Validieren Sie das Plugin und die Skill nach der Bearbeitung:

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

Projektstruktur

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

Architektur

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)

Der Server ist ein schlanker HTTP-Client. Jedes Tool ist einer REST-Route zugeordnet, und der richtige Authorization-Header wird aus der Routenfamilie gewählt: ein Firebase-ID-Token für Admin-Routen, der Projekt-API-Schlüssel für /api/v1/ai/*, nichts für öffentliche Routen. Antworten werden aus der { success, data, timestamp }-Hülle entpackt; Fehler werden als MCP-Tool-Fehler zurückgegeben, die den HTTP-Status und alle Provider-details enthalten.

Verwandte Projekte

• shapeshyft_api – das Hono-Backend, das dieser Server umschließt

• shapeshyft_types – gemeinsame TypeScript-Typdefinitionen

• shapeshyft_client – API-Client-Hooks für Web-/Native-Apps

• shapeshyft_lib – Business-Logik-Stores

• shapeshyft_app – React-Web-Frontend

Lizenz

BUSL-1.1