Skip to main content
Glama
ShapeShyft API MCP Server

ShapeShyft API MCP Server

by johnqh

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: RationalBloks 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

变量

必需

描述

SHAPESHYFT_API_URL

否

API 的基础 URL。默认 https://api.shapeshyft.ai;本地开发使用 http://localhost:3000

SHAPESHYFT_API_KEY

管理工具需要

个人 API 密钥(shyft_...)—— 首选,永不过期

SHAPESHYFT_AUTH_TOKEN

仅创建/显示密钥时需要

已登录用户的 Firebase ID 令牌

SHAPESHYFT_PROJECT_API_KEY

AI 工具需要

项目 API 密钥(sk_live_...)

SHAPESHYFT_ENTITY_SLUG

否

默认实体 slug,使工具可以省略 entitySlug

SHAPESHYFT_ORG_PATH

否

AI URL 中的默认组织路径(默认为实体 slug)

SHAPESHYFT_CONFIG_PATH

否

覆盖配置文件位置

服务器启动时没有任何凭据 —— 文档资源、提供商目录和健康检查是公开的。需要凭据的工具会返回明确的错误,说明如何获取。

两种密钥类型,职责不同。 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 中,而不是可能被提交的设置文件中。环境变量仍然有效,并且优先。

工具

文档与健康

工具

用途

describe_shapeshyft_api

读取捆绑的 API 文档(overview、routes、data-model、examples、errors、providers)

get_configuration

显示有效的 API URL、默认值以及哪些凭据存在(已脱敏)

set_credentials

设置 API 密钥、令牌、项目密钥、URL 或默认值 —— 使用 persist 保存它们

clear_stored_credentials

从配置文件中移除已保存的机密,保留偏好设置

check_api_health

GET /health,或 /health/ready 用于数据库检查

get_api_info

GET / —— 名称、版本、状态

身份与个人 API 密钥

工具

用途

get_current_user

GET /users/me —— 当前凭据属于谁,以及它是如何认证的

list_api_keys、get_api_key

密钥元数据(绝不包含机密)

create_api_key、reveal_api_key

铸造或重新读取密钥 —— 需要 Firebase 令牌

update_api_key

重命名,或使用 is_active: false 可逆地暂停密钥

delete_api_key

永久撤销

提供商(公开)

list_providers、get_provider、list_provider_models

模型条目携带能力(视觉/音频/视频输入、媒体输出、网络搜索)和以美分计的价格 —— 在端点上设置 model 之前请先检查。

AI 调用(项目 API 密钥)

工具

用途

invoke_endpoint

执行端点 → { output, usage, generated_media? }

preview_endpoint_prompt

在不调用 LLM 的情况下构建提示 —— 免费,非常适合调试

实体、成员、邀请(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

资源

URI

内容

shapeshyft://api/overview

架构、对象层次结构、认证方案、调用生命周期、限制

shapeshyft://api/routes

每条路由的方法、认证、参数和响应

shapeshyft://api/data-model

对象形状、速率限制层级、数据库表

shapeshyft://api/examples

端到端设置、curl/TypeScript/Python、schema 模式、多模态

shapeshyft://api/errors

错误封装、状态码、故障排除

shapeshyft://api/providers

提供商列表、模型选择、多模态流水线、转录

提示

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 技能

随插件安装,该技能将请求路由到四个流程之一,并在接触任何内容之前检查凭据:

流程

覆盖范围

A — 构建

任务 → 输出 schema → 提供商密钥 → 模型 → 项目 → 端点 → 已验证的调用

B — 调用

解析名称,将输入通过端点运行,报告输出以及成本和延迟

C — 调试

将 401/404/405/429 映射到原因;修复 schema 一致性和质量问题

D — 审计

盘点密钥、项目和端点;审查支出、失败和配额余量

用法:

/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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers