ts-agent-sdk

ts-agent-sdk

概要

このスキルは、AI エージェント（主に Claude Code）が MCP サーバー経由でウェブアプリケーションとやり取りできる、型付きの TypeScript SDK を生成します。冗長な JSON-RPC の curl コマンドを、すっきりとした関数呼び出しに置き換えます。

テンプレートの場所

SDK のコアテンプレートファイルは、このスキルにバンドルされています： templates/

これらのファイルを出発点として、対象プロジェクトの scripts/sdk/ ディレクトリにコピーします：

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

SDK 生成ワークフロー

ステップ 1：MCP サーバーを検出する

プロジェクト内で MCP サーバーモジュールをスキャンします：

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

各 server.ts ファイルには、次のパターンを使用したツール定義が含まれています：

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

ステップ 2：ツール定義を抽出する

各ツールについて、次の項目を抽出します：

1. name：ツール識別子（例：'create_document'）
2. description：JSDoc 用のツール説明
3. inputSchema：入力パラメーターを定義する Zod スキーマ
4. endpoint：MCP エンドポイントのパス（例：'/api/mcp-docs/message'）

ステップ 3：TypeScript インターフェースを生成する

Zod スキーマを TypeScript インターフェースに変換します：

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

ステップ 4：モジュールクライアントを生成する

各ツールのメソッドを含むクライアントクラスを作成します：

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

ステップ 5：サンプルスクリプトを生成する

script/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);

ステップ 6：インデックスのエクスポートを更新する

script/sdk/index.ts にモジュールのエクスポートを追加します：

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

出力構成

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

環境変数

SDK は次の環境変数を使用します：

変数	説明	デフォルト
SDK_MODE	実行モード：'local'、'remote'、'auto'	'auto'
SDK_BASE_URL	対象 Worker の URL	http://localhost:8787
SDK_API_TOKEN	認証用の Bearer トークン	（なし）

実行

生成されたスクリプトを次の方法で実行します：

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

命名規則

• モジュール名：MCP サーバー名に基づく小文字（例：'mcp-docs' → 'docs'）
• メソッド名：ツール名を camelCase に変換（例：'create_document' → 'createDocument'）
• 型名：PascalCase（例：'CreateDocumentInput'、'CreateDocumentOutput'）

エラー処理

SDK は次の型付きエラーを提供します：

• AuthError - 401、無効なトークン
• ValidationError - 無効な入力
• NotFoundError - リソースが見つかりません
• RateLimitError - 429、リクエストが多すぎます
• MCPError - MCP プロトコルエラー
• NetworkError - 接続エラー

再生成

MCP ツールが変更された場合は、SDK を再生成します：

1. src/server/modules/mcp*/server.ts を再スキャンします
2. 新規または変更されたスキーマで types.ts を更新します
3. 新規または変更されたメソッドで client.ts を更新します
4. examples/ 内のカスタムコードは保持します