name: ts-agent-sdk description: | 为AI代理生成类型化的TypeScript SDK，以便与MCP服务器交互。将冗长的JSON-RPC curl命令转换为清洁的函数调用（例如docs.createDocument() vs curl）。自动从服务器模块检测MCP工具，生成TypeScript类型和客户端方法，创建可运行的示例脚本。

使用场景：构建支持MCP的应用程序，需要类型化的编程访问MCP工具，希望Claude Code通过脚本管理应用，消除手动JSON-RPC curl命令，验证MCP输入/输出，或创建可重用的代理自动化。

ts-agent-sdk

概述

此技能生成类型化的TypeScript SDK，允许AI代理（主要是Claude Code）通过MCP服务器与Web应用程序交互。它替代了冗长的JSON-RPC curl命令。

模板位置

核心SDK模板文件捆绑在此技能中，位于： templates/

复制这些文件到目标项目的scripts/sdk/目录作为起点：

cp -r ~/.claude/skills/ts-agent-sdk/templates/* ./scripts/sdk/

SDK生成工作流

步骤1：检测MCP服务器

扫描项目中的MCP服务器模块：

src/server/modules/mcp*/server.ts

每个server.ts文件包含工具定义，使用模式：

server.tool(
  'tool_name',
  'Tool description',
  zodInputSchema,
  async (params) => { ... }
)

步骤2：提取工具定义

对于每个工具，提取：

名称：工具标识符（例如’create_document’）
描述：工具描述，用于JSDoc
输入模式：定义输入参数的Zod模式
端点：MCP端点路径（例如’/api/mcp-docs/message’）

步骤3：生成TypeScript接口

将Zod模式转换为TypeScript接口：

// 从：z.object({ name: z.string(), email: z.string().email() })
// 转换为：
export interface CreateEnquiryInput {
  name: string;
  email: string;
}

步骤4：生成模块客户端

为每个工具创建客户端类和方法：

// scripts/sdk/docs/client.ts
import { MCPClient, defaultClient } from '../client';
import type { CreateDocumentInput, CreateDocumentOutput } from './types';

const ENDPOINT = '/api/mcp-docs/message';

export class DocsClient {
  private mcp: MCPClient;

  constructor(client?: MCPClient) {
    this.mcp = client || defaultClient;
  }

  async createDocument(input: CreateDocumentInput): Promise<CreateDocumentOutput> {
    return this.mcp.callTool(ENDPOINT, 'create_document', input);
  }

  async listDocuments(input: ListDocumentsInput): Promise<ListDocumentsOutput> {
    return this.mcp.callTool(ENDPOINT, 'list_documents', input);
  }

  // ... 每个工具一个方法
}

export const docs = new DocsClient();

步骤5：生成示例脚本

在scripts/sdk/examples/中创建可运行的示例：

#!/usr/bin/env npx tsx
// scripts/sdk/examples/create-doc.ts
import { docs } from '../';

async function main() {
  const result = await docs.createDocument({
    spaceId: 'wiki',
    title: 'Getting Started',
    content: '# Welcome

This is the intro.',
  });

  console.log(`Created document: ${result.document.id}`);
}

main().catch(console.error);

步骤6：更新索引导出

添加模块导出到scripts/sdk/index.ts：

export { docs } from './docs';
export { enquiries } from './enquiries';

输出结构

project/
└── scripts/sdk/
    ├── index.ts           # 主导出
    ├── config.ts          # 环境配置
    ├── errors.ts          # 错误类
    ├── client.ts          # MCP客户端
    │
    ├── docs/              # 生成模块
    │   ├── types.ts       # TypeScript接口
    │   ├── client.ts      # 类型化方法
    │   └── index.ts       # 模块导出
    │
    ├── enquiries/         # 另一个模块
    │   ├── types.ts
    │   ├── client.ts
    │   └── index.ts
    │
    └── examples/          # 可运行脚本
        ├── create-doc.ts
        ├── list-spaces.ts
        └── create-enquiry.ts

环境变量

SDK使用以下环境变量：

变量	描述	默认值
`SDK_MODE`	执行模式：‘local’, ‘remote’, ‘auto’	‘auto’
`SDK_BASE_URL`	目标Worker URL	http://localhost:8787
`SDK_API_TOKEN`	Bearer令牌用于认证	(无)

执行

运行生成的脚本：

SDK_API_TOKEN="your-token" SDK_BASE_URL="https://app.workers.dev" npx tsx scripts/sdk/examples/create-doc.ts

命名约定

模块名称：小写，来自MCP服务器名称（例如’mcp-docs’ → ‘docs’）
方法名称：驼峰命名，来自工具名称（例如’create_document’ → ‘createDocument’）
类型名称：帕斯卡命名（例如’CreateDocumentInput’, ‘CreateDocumentOutput’）

错误处理

SDK提供类型化错误：

AuthError - 401, 无效令牌
ValidationError - 无效输入
NotFoundError - 资源未找到
RateLimitError - 429, 请求过多
MCPError - MCP协议错误
NetworkError - 连接失败

重新生成

当MCP工具更改时，重新生成SDK：

重新扫描src/server/modules/mcp*/server.ts
使用新/更改的模式更新types.ts
更新client.ts中的新/更改方法
保留examples/中的任何自定义代码