使用说明

项目简介

speakeasy-code-samples-ts 仓库提供了一个基于 Model Context Protocol (MCP) 的服务器实现，该服务器允许 LLM 客户端通过标准化的 MCP 协议，调用工具来获取代码示例。这些代码示例来源于 OpenAPI 规范文档，可以帮助 LLM 理解和生成代码。

主要功能点

提供代码示例检索工具: 通过 'code-samples_get' 工具，LLM 客户端可以根据 OpenAPI 规范的 registry URL、Operation ID、方法路径和编程语言等条件，检索并获取代码示例片段。
MCP 服务器: 仓库包含可运行的 MCP 服务器代码，能够处理来自 MCP 客户端的 JSON-RPC 请求，并返回符合 MCP 协议的响应。
支持多种 MCP 传输协议: 服务器支持 Stdio 和 SSE 传输协议，可以与不同的 MCP 客户端集成。
基于 Speakeasy SDK 构建: 该 MCP 服务器是基于 Speakeasy 代码生成平台生成的 SDK 构建的，利用了 Speakeasy 平台的能力来提供代码示例服务。

安装步骤

安装 Node.js: 确保你的环境中安装了 Node.js v20 或更高版本。
安装 npm 包: 使用 npm, pnpm, bun 或 yarn 等包管理器安装 '@speakeasyapi/code-samples' 包。例如，使用 npm：
```
npm add @speakeasyapi/code-samples
```

服务器配置

MCP 服务器需要配置在 MCP 客户端中，以便客户端能够连接并调用服务器提供的工具。以下是针对 Claude 和 Cursor 两种 MCP 客户端的服务器配置示例。

Claude 配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "SpeakeasyCodeSamples": {
      "command": "npx",
      "args": [
        "-y", "--package", "@speakeasyapi/code-samples",
        "--",
        "mcp", "start",
        "--api-key", "YOUR_API_KEY",  // Speakeasy API Key，用于访问 Speakeasy API
        "--registry-url", "YOUR_REGISTRY_URL" // OpenAPI 规范文档的 Registry URL
      ]
    }
  }
}

Cursor 配置 (Cursor Settings > Features > MCP Servers > Add new MCP server):

Name: SpeakeasyCodeSamples
Type: 'command'

Command:

npx -y --package @speakeasyapi/code-samples -- mcp start --api-key YOUR_API_KEY --registry-url YOUR_REGISTRY_URL

参数说明:

'--api-key': (必需) 你的 Speakeasy API Key，用于进行身份验证并访问 Speakeasy API 服务。你需要替换 'YOUR_API_KEY' 为你实际的 API Key。
'--registry-url': (必需) OpenAPI 规范文档的 Registry URL。你需要替换 'YOUR_REGISTRY_URL' 为你的 OpenAPI 规范文档的 registry URL。

基本使用方法

启动 MCP 服务器: 根据你选择的 MCP 客户端 (Claude 或 Cursor) 配置并启动 MCP 服务器。服务器将会在后台运行，并监听来自客户端的请求。
在 LLM 客户端中调用工具: 在支持 MCP 协议的 LLM 客户端中（例如 Claude 或 Cursor），你可以通过自然语言指令或客户端提供的界面，调用 'code-samples_get' 工具。你需要提供工具所需的参数，例如 'registryUrl', 'operationIds', 'methodPaths', 'languages' 等，以指定你想要检索的代码示例。
获取代码示例: MCP 服务器将处理客户端的请求，并从指定的 OpenAPI 规范文档中检索代码示例。检索结果将以 JSON-RPC 响应的形式返回给客户端。LLM 客户端可以解析响应，并利用获取的代码示例进行后续操作，例如代码生成或代码理解。

请参考仓库的 README.md 文件获取更详细的参数说明和高级配置选项。

关键词

使用说明

信息