ShapeShyft API MCP 服务器

MCP（模型上下文协议）服务器，用于描述并驱动 ShapeShyft API —— LLM 结构化输出平台，其中每个配置的端点都会成为一个 REST URL， 返回符合 schema 的 JSON。

它为 AI 助手提供四样东西：

• 61 个工具，覆盖 ShapeShyft API 的每一条路由 —— 实体、LLM 提供商密钥、 项目、端点、分析、速率限制、存储、用户和 AI 调用。

• 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/ 下，因此本仓库中的编辑在刷新 marketplace 和插件之前不会生效：

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 —— marketplace 条目

• .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 字段参考和六个实用配方，每个配方都将输入负载与其 schema 和响应配对

• skills/shapeshyft-endpoint/references/schema-design.md —— 模型实际满足的输出 schema

• 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 } 封装中解包；失败以 MCP 工具错误形式返回，携带 HTTP 状态和任何提供商 details。

相关项目

• shapeshyft_api —— 本服务器包装的 Hono 后端

• shapeshyft_types —— 共享的 TypeScript 类型定义

• shapeshyft_client —— 用于 Web/原生应用的 API 客户端钩子

• shapeshyft_lib —— 业务逻辑存储

• shapeshyft_app —— React Web 前端

许可证

BUSL-1.1