ShapeShyft API MCP 서버

ShapeShyft API를 설명하고 구동하는 MCP(Model Context Protocol) 서버입니다. 구성된 각 엔드포인트가 스키마를 준수하는 JSON을 반환하는 REST URL이 되는 LLM 구조화 출력 플랫폼입니다.

AI 어시스턴트에게 네 가지를 제공합니다:

• 61개의 도구 — 엔티티, LLM 공급자 키, 프로젝트, 엔드포인트, 분석, 속도 제한, 스토리지, 사용자, AI 호출 등 모든 ShapeShyft API 라우트를 다룹니다.

• 6개의 문서 리소스 — API 자체를 설명합니다(개요, 라우트, 데이터 모델, 작업 예제, 오류, 공급자). 자격 증명이나 네트워크 호출 없이 읽을 수 있습니다.

• 3개의 프롬프트 템플릿 — 엔드포인트 설정, 디버깅, 엔티티 감사 등 일반적인 워크플로우용입니다.

• /shapeshyft-endpoint 스킬 — 엔드포인트 구축, 호출, 디버깅, 감사를 위한 안내 워크플로우로, Claude Code 플러그인으로 제공됩니다.

패키지: @sudobility/shapeshyft_api_mcp (BUSL-1.1)

설치

bun install

Related MCP server: Swagger MCP Server

구성

키 발급

shapeshyft.ai → 대시보드 → 설정 → 개인 API 키 → 이름 지정 → 키 생성에서 개인 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. 명시적 도구 인자(예: invoke_endpoint의 apiKey)

2. 환경 변수

3. ~/.shapeshyft/config.json

서버는 자격 증명 없이 시작됩니다. 문서 리소스, 공급자 카탈로그, 상태 확인은 공개되어 있습니다. 자격 증명이 필요한 도구는 자격 증명을 얻는 방법을 알려주는 명확한 오류를 반환합니다.

두 가지 키 유형, 서로 다른 역할. shyft_...는 관리자 라우트에 대해 사용자를 인증하는 개인 키입니다. sk_live_...는 호출자가 한 프로젝트의 AI 엔드포인트를 호출할 수 있게 하는 프로젝트 키입니다. 개인 키 생성 및 조회는 개인 키가 할 수 없는 유일한 작업입니다. 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을 설정하기 전에 확인하세요.

AI 호출(프로젝트 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

엔드포인트

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로 만들어 줘" "내 엔드포인트가 계속 잘못된 카테고리를 반환해" "이번 달 ShapeShyft 엔드포인트 비용은 얼마야?"

번들된 참조 자료:

• skills/shapeshyft-endpoint/references/creating-endpoints.md — create_endpoint 필드 참조와 6개의 작업 레시피. 각 레시피는 입력 페이로드와 스키마 및 응답을 짝지어 제공

• 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/v1/ai/*에는 프로젝트 API 키, 공개 라우트에는 아무것도 사용하지 않습니다. 응답은 { success, data, timestamp } 봉투에서 언랩되며, 실패는 HTTP 상태와 공급자 details를 포함한 MCP 도구 오류로 반환됩니다.

관련 프로젝트

• shapeshyft_api — 이 서버가 감싸는 Hono 백엔드

• shapeshyft_types — 공유 TypeScript 타입 정의

• shapeshyft_client — 웹/네이티브 앱용 API 클라이언트 훅

• shapeshyft_lib — 비즈니스 로직 저장소

• shapeshyft_app — React 웹 프론트엔드

라이선스

BUSL-1.1