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<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();

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/