ts-agent-sdk

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:

1. name: The tool identifier (e.g., 'create_document')
2. description: Tool description for JSDoc
3. inputSchema: Zod schema defining input parameters
4. 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:

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:

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