ts-agent-sdk Overview

This skill generates typed TypeScript SDKs that allow AI agents (primarily Claude Code) to interact with web applications via MCP servers. It replaces verbose JSON-RPC curl commands with clean function calls.

Template Location

The core SDK template files are bundled with this skill at: templates/

Copy these files to the target project's scripts/sdk/ directory as a starting point:

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

SDK Generation Workflow Step 1: Detect MCP Servers

Scan the project for MCP server modules:

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

Each server.ts file contains tool definitions using the pattern:

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

Step 2: Extract Tool Definitions

For each tool, extract:

name: The tool identifier (e.g., 'create_document') description: Tool description for JSDoc inputSchema: Zod schema defining input parameters endpoint: The MCP endpoint path (e.g., '/api/mcp-docs/message') Step 3: Generate TypeScript Interfaces

Convert Zod schemas to TypeScript interfaces:

// From: z.object({ name: z.string(), email: z.string().email() }) // To: export interface CreateEnquiryInput { name: string; email: string; }

Step 4: Generate Module Client

Create a client class with methods for each tool:

// 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 { return this.mcp.callTool(ENDPOINT, 'create_document', input); }

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

// ... one method per tool }

export const docs = new DocsClient();

Step 5: Generate Example Scripts

Create runnable examples in 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);

Step 6: Update Index Exports

Add module exports to scripts/sdk/index.ts:

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

Output Structure 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

Environment Variables

The SDK uses these environment variables:

Variable Description Default SDK_MODE Execution mode: 'local', 'remote', 'auto' 'auto' SDK_BASE_URL Target Worker URL http://localhost:8787 SDK_API_TOKEN Bearer token for auth (none) Execution

Run generated scripts with:

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

Naming Conventions Module names: Lowercase, from MCP server name (e.g., 'mcp-docs' → 'docs') Method names: camelCase from tool name (e.g., 'create_document' → 'createDocument') Type names: PascalCase (e.g., 'CreateDocumentInput', 'CreateDocumentOutput') Error Handling

The SDK provides typed errors:

AuthError - 401, invalid token ValidationError - Invalid input NotFoundError - Resource not found RateLimitError - 429, too many requests MCPError - MCP protocol errors NetworkError - Connection failures Regeneration

When MCP tools change, regenerate the SDK:

Re-scan src/server/modules/mcp*/server.ts Update types.ts with new/changed schemas Update client.ts with new/changed methods Preserve any custom code in examples/

安装

!/usr/bin/env npx tsx