ts-agent-sdk

Name: ts-agent-sdk
Author: JezWeb

TypeScriptAI agentsSDK generationAPI clientMCP serversZodcode generationdeveloper tools

⭐ 860📄 MIT🕒 2026-06-11Source ↗

Install this skill

npx skills add jezweb/claude-skills

Works across Claude Code, Cursor, Codex, Copilot & Antigravity

The ts-agent-sdk transforms raw MCP server tool definitions into structured, type-safe TypeScript clients. Instead of managing manual JSON-RPC requests via curl or basic network calls, this skill automates the extraction of tool metadata and Zod schemas to generate dedicated SDK modules. By parsing source files following the mcp-server pattern, it creates clean, idiomatic interface classes that provide autocomplete and type checking for your AI agent interactions. This systematic approach ensures that project communication between AI agents and web-based MCP endpoints remains synchronized, reducing boilerplate while enforcing consistent naming conventions for methods, types, and input schemas. It serves as a glue layer between backend tool definitions and front-facing execution scripts, ensuring that every tool invocation within the agent workflow is strictly typed and documented.

When to Use This Skill

•Synchronizing backend tool changes with client-side interface types
•Building interactive CLI tools for internal development tasks
•Creating reliable automation for Claude Code tool invocation
•Reducing network-related runtime errors in agentic workflows

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

“generate a typed SDK for my existing MCP servers
“create typescript clients from my mcp server definitions
“scaffold an sdk directory structure for my agent tools
“update the ts-agent-sdk client with latest tool changes
“sync my mcp tool definitions with the project sdk

Pro Tips

💡Ensure your MCP server definitions use Zod consistently for reliable schema extraction and TypeScript generation.
💡Integrate the generated SDK into your agent's tool definitions to provide structured access to backend functions.
💡Utilize the skill to re-generate SDKs regularly as your MCP server's API evolves, keeping your agent's interactions up-to-date.

What this skill does

•Parses Zod schemas to auto-generate TypeScript interfaces
•Creates object-oriented client classes for specific MCP modules
•Standardizes naming conventions from MCP snake_case to camelCase
•Bundles pre-configured error handling classes for API integration
•Generates boilerplate execution scripts for rapid prototyping

When not to use it

✕Projects not using Zod for MCP server tool validation
✕Small projects where overhead of a full SDK outweighs manual fetch calls

Example workflow

Verify the project contains MCP server modules in src/server/modules/
Execute the SDK generation routine to scan tool definitions
Review generated types and client methods in scripts/sdk/
Create or update custom scripts in the examples folder
Run final integration tests using the generated client and environment variables

Prerequisites

–TypeScript project
–Existing MCP server implementation using Zod
–tsx installed for executing generated scripts

Pitfalls & limitations

!Custom logic inside generated client files may be overwritten during regeneration
!Strict dependency on specific project file paths for source scanning
!Requires manual maintenance of environment variables for different target environments

FAQ

Does this tool automatically detect new MCP servers?

Yes, it scans the project directory for modules matching the path pattern src/server/modules/mcp*/server.ts.

What happens to my manual edits in the examples folder?

The generation process focuses on types and client logic, but you should avoid editing core generated client classes directly as they may be overwritten.

Can I use this with non-Zod MCP implementations?

No, the current generation logic relies on Zod input schemas to define the TypeScript interface shapes.

How it compares

This tool replaces error-prone, manual JSON-RPC payload crafting with a predictable, type-safe library that acts as a formal interface to your MCP services.

Source & trust

⭐ 860 stars📄 MIT🕒 Updated 2026-06-11

View original skill on GitHub →

📄 Full skill instructions — original source: jezweb/claude-skills

# 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/

By JezWeb

How to Use This Skill Unit

Option A: Project-Specific (Recommended)

Click "Download" above
In your project, create the directory: .agent/skills/ts-agent-sdk/
Save the file as SKILL.md
The agent will automatically discover the skill based on its description.

Option B: Global Installation (All Agents)

Save the file to these locations to make it available across all projects:

Claude Code: ~/.claude/skills/jezweb/claude-skills/ts-agent-sdk/SKILL.md
Cursor: ~/.cursor/skills/jezweb/claude-skills/ts-agent-sdk/SKILL.md
Antigravity: ~/.gemini/antigravity/skills/jezweb/claude-skills/ts-agent-sdk/SKILL.md

🚀 Install with CLI:
npx skills add jezweb/claude-skills

Read the Master Guide: Mastering Agent Skills →

Recommended Rules

View more rules →

Recommended Workflows

View more workflows →

Generate TypeScript Types from API

TypeScriptAPICodegen

--- description: Auto-generate type-safe API client from OpenAPI/Swagger spec --- 1. **Get Your API Schema**: - Most APIs expose OpenAPI spec at `...

Debug TypeScript 'any' Proliferation

TypeScriptCode QualityTypes

--- description: Find and eliminate implicit 'any' types for better type safety --- 1. **Enable Strict Mode**: - Update `tsconfig.json` to catch i...

Debug 'Cannot Find Module' TypeScript Errors

TypeScriptDebuggingModules

--- description: Fix TypeScript module resolution issues --- 1. **Check tsconfig.json Paths**: - Verify path mappings are correct. ```json {...

Recommended MCP Servers

View more MCP servers →

it-tools-mcp

Community

A Model Context Protocol server that recreates [CorentinTh it-tools](https://github.com/CorentinTh/it-tools) utilities for AI agents, enabling access to a wide range of developer tools (encoding, decoding, conversions, and more) via MCP.