使用说明

史密斯到mcp

从Smithy API模型生成MCP（模型上下文协议）服务器。

它的作用

此工具解析Smithy JSON AST文件并生成TypeScript MCP服务器，包括：

每个API操作的工具
带有验证和描述的Zod模式
具有路径/查询/正文参数处理的HTTP客户端
从Smithy特征中自动检测AWS端点
AWS SigV4身份验证（从Smithy模型自动检测）

安装

npm install
npm run build

用法

直接运行（动态服务器）

从Smithy模型运行MCP服务器的最快方法-不需要生成代码：

# From a local file
npx smithy-to-mcp serve ./my-model.json

# Auto-download AWS service models
npx smithy-to-mcp serve aws:bedrock-agent-runtime
npx smithy-to-mcp serve aws:s3

选项：

-u, --base-url <url> -API调用的基本URL（默认值：来自模型或 API_BASE_URL env）
-k, --api-key <key> -用于身份验证的API密钥（默认值： API_KEY env）
-t, --timeout <ms> -请求超时（毫秒）（默认值：30000）
-r, --region <region> -SigV4签名的AWS区域（默认： AWS_REGION env或us-east-1）
--no-cache -跳过缓存并重新下载AWS模型

生成MCP服务器

生成一个独立的TypeScript MCP服务器：

npx smithy-to-mcp generate <smithy-model.json> -o <output.ts>

选项：

-o, --output <file> -输出文件路径（默认：mcp-server.ts）
-u, --base-url <url> -覆盖基本URL（自动检测AWS服务）
-n, --name <name> -覆盖服务器名称
-v, --version <version> -覆盖服务器版本
--stdout -输出到stdout而不是文件

检查史密斯模型

npx smithy-to-mcp inspect <smithy-model.json>

显示服务信息、操作和输入/输出形状。

创建Smithy模型示例

npx smithy-to-mcp init

创造 weather-service.json 作为一个起点。

例子

快速入门：AWS基岩代理核心

配置AWS凭据 （如果尚未设置）

aws configure
# Or set environment variables:
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

运行MCP服务器 （自动下载并缓存模型）
```
npx smithy-to-mcp serve aws:bedrock-agent-runtime
```
添加到您的MCP客户端 -请参阅 MCP客户端集成在......下面

MCP客户端集成

克劳德代码

添加到您的Claude Code MCP设置文件(~/.claude/settings.json):

{
  "mcpServers": {
    "bedrock-agent-runtime": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:bedrock-agent-runtime"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

或者添加多个AWS服务：

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:s3"]
    },
    "dynamodb": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:dynamodb"]
    },
    "lambda": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:lambda"]
    }
  }
}

Kiro命令行界面

添加到Kiro MCP配置文件(~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "bedrock-agent-runtime": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:bedrock-agent-runtime"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "bedrock-agent-runtime": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "aws:bedrock-agent-runtime"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

定制史密斯模型

对于本地Smithy文件，请使用绝对路径：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["smithy-to-mcp", "serve", "/path/to/my-model.json"],
      "env": {
        "API_BASE_URL": "https://api.example.com"
      }
    }
  }
}

其他AWS服务

使用 aws:<service-name> 要自动下载任何AWS服务模型：

npx smithy-to-mcp serve aws:s3
npx smithy-to-mcp serve aws:dynamodb
npx smithy-to-mcp serve aws:lambda
npx smithy-to-mcp serve aws:ec2

模型下载自 aws/api模型aws 并缓存在 ~/.smithy-to-mcp/cache/.

生成独立的MCP服务器

如果你更喜欢生成代码而不是动态服务：

# Generate TypeScript MCP server
npx smithy-to-mcp generate bedrock-agentcore.json -o bedrock-mcp-server.ts

# Run the generated server
npx tsx bedrock-mcp-server.ts

环境变量

生成的服务器支持：

变量	描述
`API_BASE_URL`	覆盖基本URL
`AWS_REGION`	AWS服务的AWS区域（默认：us-east-1）
`API_KEY`	授权标头的API密钥（非AWS）
`API_TIMEOUT`	请求超时（毫秒）（默认值：30000）

AWS SigV4身份验证

对于AWS服务，该工具会自动检测Smithy模型中的SigV4要求，并：

用途 @smithy/signature-v4 用于请求签名
用途 @aws-sdk/credential-provider-node AWS凭据
从环境、~/.aws/凭据、IAM角色等读取凭据。

包含所有AWS依赖项，无需额外安装。

生成的输出

生成的MCP服务器包括：

// Each Smithy operation becomes an MCP tool
server.registerTool(
  "create-agent-runtime",
  {
    description: "Creates an Amazon Bedrock AgentCore Runtime.",
    inputSchema: z.object({
      agentRuntimeName: z.string()
        .regex(/^[a-zA-Z][a-zA-Z0-9_]{0,47}$/)
        .describe("The name of the AgentCore Runtime."),
      description: z.string()
        .optional()
        .describe("The description of the AgentCore Runtime."),
    }),
  },
  async (params) => {
    // HTTP call to the API
  }
);

支持的Smithy功能

形状

service -与运营和资源
resource -CRUD生命周期（创建、读取、更新、删除、列表）+操作+集合操作+嵌套资源
operation -输入/输出/错误
structure, list, map, union, enum, intEnum
原始类型： string, boolean, byte, short, integer, long, float, double, bigInteger, bigDecimal, timestamp, blob, document

特质

特性	目的
`@documentation`	工具和字段说明
`@required`	Zod模式中的必填字段
`@http`	HTTP方法和URI模板
`@httpLabel`	路径参数
`@httpQuery`	查询字符串参数
`@httpQueryParams`	稀疏地图展开查询参数
`@httpHeader`	请求标头
`@httpPrefixHeaders`	标头前缀映射
`@httpPayload`	请求车身有效载荷
`@httpChecksum`	校验和要求（如工具说明所示）
`@length`	字符串最小/最大长度验证
`@pattern`	字符串正则表达式验证
`@range`	最小/最大验证数
`@default`	Zod模式中的默认值
`@jsonName`	JSON序列化的线名
`@paginated`	分页配置（如工具说明所示）
`@waitable`	生成 `wait-for-*` 轮询工具
`@enumValue`	枚举导线值
`@sensitive`	标记敏感字段（如字段描述所示）
`@deprecated`	工具/字段描述中的弃用警告
`@idempotencyToken`	如果未提供，则自动生成UUID
`@streaming`	流媒体主体（在字段描述中注明）
`@hostLabel`	主机标签字段（已解析）
`@mediaType`	字段描述中的内容类型提示
`@examples`	使用示例（如工具说明所示）
`@externalDocumentation`	工具描述中的外部文档链接
`@tags`	资源标签（如工具描述所示）
`@unstable`	API标记不稳定
`@internal`	API内部标记
`@idempotent`	临时操作标记
`@readonly`	只读操作标记
`aws.api#service`	AWS端点前缀检测
`aws.auth#sigv4`	AWS SigV4签名检测
`aws.protocols#restJson1`	协议检测

尚未支持

以下Smithy特征尚未解析：

特质

特性	目的
`@httpResponseCode`	响应代码绑定
`@xmlName`, `@xmlAttribute`, `@xmlNamespace`	XML格式
`@eventPayload`, `@eventHeader`	事件流
`@retryable`	重试提示（已解析但未在生成的代码中使用）

特性

混合物（形状组成）
应用语句（外部特征应用）
自动分页（目前仅在描述中显示分页字段）
流媒体主体（目前仅在描述中显示为标记）
事件流

预先生成的示例

看 examples/ 目录：

weather-mcp-server.ts -简单天气API示例
aws/bedrock-agentcore-mcp-server.ts -AWS基岩代理核心（35次操作）
aws/bedrock-agentcore-control-mcp-server.ts -AWS基岩代理核心控制（79次操作）