ts-agent-sdk

ts-agent-sdk

概述

此技能可生成类型化的 TypeScript SDK，让 AI Agent（主要是 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：提取工具定义

对于每个工具，提取：

1. name：工具标识符（例如，'create_document'）
2. description：用于 JSDoc 的工具描述
3. inputSchema：定义输入参数的 Zod 架构
4. endpoint：MCP 端点路径（例如，'/api/mcp-docs/message'）

步骤 3：生成 TypeScript 接口

将 Zod 架构转换为 TypeScript 接口：

// From: z.object({ name: z.string(), email: z.string().email() })
// To:
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);
  }

  // ... one method per tool
}

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\n\nThis 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           # Main exports
    ├── config.ts          # Environment config
    ├── errors.ts          # Error classes
    ├── client.ts          # MCP client
    │
    ├── docs/              # Generated module
    │   ├── types.ts       # TypeScript interfaces
    │   ├── client.ts      # Typed methods
    │   └── index.ts       # Module exports
    │
    ├── enquiries/         # Another module
    │   ├── types.ts
    │   ├── client.ts
    │   └── index.ts
    │
    └── examples/          # Runnable scripts
        ├── 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'）
• 方法名称：根据工具名称使用 camelCase（例如，'create_document' → 'createDocument'）
• 类型名称：使用 PascalCase（例如，'CreateDocumentInput'、'CreateDocumentOutput'）

错误处理

SDK 提供类型化错误：

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

重新生成

MCP 工具发生变化时，重新生成 SDK：

1. 重新扫描 src/server/modules/mcp*/server.ts
2. 使用新增或变更的架构更新 types.ts
3. 使用新增或变更的方法更新 client.ts
4. 保留 examples/ 中的自定义代码