Smithy MCP

Smithy MCP 扩展


@innFactory/smithy-mcp 是一个轻量级、开源的库，提供了一套 “Smithy”可以翻译为“铁匠铺”或“修理厂”，具体取决于上下文和语境。在一般情况下，如果没有特别的行业或专业背景，翻译为“铁匠铺”更为常见和易懂 特性用于为API操作添加注解 模型上下文协议（MCP）。

它允许您无缝地为Smithy API定义添加元数据，使其能够被MCP代理、AI模型或其他自动化系统作为“工具”发现并使用。

核心设计理念是 约定优于配置从单一特性开始，只有在需要覆盖合理默认值时才添加更多细节。

特点/功能

• 最小化开销将一个操作作为MCP工具以单一方式暴露出来 @mcpTool 特征。
• 约定优于配置该系统会自动从您的现有模型中推断出名称和描述。只有当您想要覆盖这些默认值时，才需要添加注释。
• 丰富的元数据可选择添加详细描述、类别、版本、参数示例以及完整的端到端使用示例。
• 清晰命名所有特征都以……为前缀 mcp 为了清晰起见，并避免冲突。
• 类型安全通过在Smithy IDL中定义元数据，您可以获得工具定义的编译时验证。

安装

要在你的Smithy项目中使用这些特性，你需要将这个仓库作为依赖项添加进来。在你的 smithy-build.json，在（某处）添加以下内容至 maven 依赖项部分。

*（注：一旦该包发布到Maven仓库，即可获取确切坐标。目前，您可以直接使用供应商提供的模型文件。）*

将一个Git仓库作为依赖项导入的典型设置如下所示（示例使用...） smithy-cli)：

{
  "version": "1.0.0",
  "sources": ["model"],
  "maven": {
    "dependencies": [
      // Dependency will be added here once published
    ]
  }
}

目前，您可以添加 model/ 将此仓库中的目录链接到您项目的 Smithy 源代码路径。

如何使用

1. 导入特性（或：导入特性类）

在你的 .smithy 文件，从（某个地方）导入你想要使用的特性 de.innfactory.mcp 命名空间。

$version: "2.0"

namespace com.example.api

use de.innfactory.mcp#mcpTool
use de.innfactory.mcp#mcpName
use de.innfactory.mcp#mcpDescription
use de.innfactory.mcp#mcpCategories
use de.innfactory.mcp#mcpParameter
use de.innfactory.mcp#mcpExamples

2. 为您的操作添加注释

最小示例（基于约定）

要将一个操作作为工具暴露出来，只需添加 @mcpTool 特征。该工具的名称将源自操作名称（GetUser)，其描述将取自标准 @documentation 特征。

/// This documentation will be used as the default tool description.
@mcpTool
@http(method: "GET", uri: "/users/{id}")
operation GetUser { /* ... */ }

完整示例（基于配置）

为了获得更多的控制权，你可以使用其他的 mcp* 特性以提供明确的元数据。

/// This is the fallback documentation.
@mcpTool
@mcpName("GetUserProfile") // Override the default name "GetUser"
@mcpDescription("Retrieves the full public profile for a user by their ID.")
@mcpCategories(["User Management", "Data Retrieval"])
@mcpVersion("1.1.0")
@mcpExamples([
  {
    title: "Retrieve a standard user",
    input: {
      userId: "usr_12345"
    },
    output: {
      body: {
        id: "usr_12345",
        name: "Jane Doe",
        email: "jane.doe@example.com"
      }
    }
  }
])
@http(method: "GET", uri: "/users/{userId}")
operation GetUser {
  input := {
    @required
    @httpLabel
    /// Default documentation for the parameter.
    @mcpParameter(
      example: "usr_12345" // Provide a concrete example value
    )
    userId: String
  },
  output := { /* ... */ }
}

可用特性

做出贡献

欢迎贡献！请随时提出问题或提交拉取请求。

许可证

这个项目遵循MIT许可证进行授权。详见 许可证 文件中详述。