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:

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:

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/