TypeScript SDK & MCP Client

ELI5

The TypeScript SDK is like a lightweight messenger that speaks to IRIS. Unlike the Python SDK which needs a toolkit (requests, Click, Rich), the TypeScript version uses only what your browser already has (the fetch API). It’s like the difference between sending a letter with a courier service versus just handing it to someone who was already going that way.

Technical Deep Dive

Package Information

File Structure

iris-sdk-typescript/
├── src/
│   ├── index.ts      # Main export
│   ├── client.ts     # IrisClient class
│   ├── types.ts      # TypeScript interfaces
│   └── errors.ts     # Error types
├── dist/             # Compiled output
├── package.json
└── tsconfig.json

IrisClient Class

import { IrisClient } from "@iris-hq/sdk";

const client = new IrisClient({
  baseUrl: "http://localhost:8000",  // or IRIS_SERVICE_URL env var
});

// Sprite operations
const sprite = await client.createSprite({
  name: "SOL-FORGE-01",
  version: "1.0.0",
  role: "architect",
  capabilities: [{ name: "generate_code", description: "..." }],
  system_prompt: "You are a senior software architect..."
});

// Fingerprint verification
const fingerprint = await client.getFingerprint(sprite.id);
console.log(fingerprint.verified); // true | false

// Chain execution
const result = await client.executeChain({
  council_id: council.id,
  chain_id: chain.id,
  input: { task: "Generate a REST API" }
});

Client Architecture

classDiagram
    class IrisClient {
        +string baseUrl
        +number timeout
        +boolean verifySsl
        +createSprite(SpriteCreate) Promise~Sprite~
        +getSprite(id) Promise~Sprite~
        +updateSprite(id, SpriteUpdate) Promise~Sprite~
        +deleteSprite(id, force?) Promise~void~
        +getFingerprint(id) Promise~Fingerprint~
        +createCouncil(CouncilCreate) Promise~Council~
        +executeChain(ChainExecuteRequest) Promise~ChainExecutionResult~
        +getChainHistory(chainId, options?) Promise~ChainHistory~
        +health() Promise~HealthCheck~
        -request(method, path, body?) Promise~T~
    }
    class IrisServiceError {
        +string code
        +number status
        +any details
        +string requestId
    }
    IrisClient --> IrisServiceError : throws

Error Handling

try {
  const sprite = await client.createSprite(data);
} catch (error) {
  if (error instanceof IrisServiceError) {
    console.error(error.code);      // "VALIDATION_ERROR"
    console.error(error.status);    // 400
    console.error(error.details);   // { field: "name", message: "..." }
    console.error(error.requestId); // "req-uuid"
  }
}

The client parses error responses from iris-service and converts them into typed IrisServiceError objects.

Type System

The SDK exports comprehensive TypeScript types matching the OpenAPI contract:

MCP Server Client

The iris-mcp-server contains its own IrisClient (self-contained, does not import from @iris-hq/sdk). This is intentional to keep the MCP server lightweight and avoid dependency issues in Cloudflare Workers.

Key difference: The MCP client’s request() method includes field name translation between MCP descriptive names (sprite_ids, gate_agent_ids) and REST concise names (sprites, gate_agents).

Comparison: Python vs TypeScript SDK

Key Terms

• ESM → ECMAScript Modules; the modern JavaScript module system using import/export
• Native fetch → The browser/Node.js built-in fetch() API; no external HTTP library needed
• IrisServiceError → Typed error class containing code, status, details, and request_id
• Zero runtime dependencies → The package has no dependencies in package.json; relies entirely on platform APIs
• Field name translation → Converting between MCP descriptive names and REST concise names

Q&A

Q: Can I use the TypeScript SDK in the browser? A: Yes. Since it uses native fetch with zero dependencies, it works in any modern browser supporting fetch and ESM.

Q: Why doesn’t the TypeScript SDK do client-side validation? A: To keep it lightweight. Runtime validation is delegated to iris-service, which returns structured errors. TypeScript’s compile-time type checking catches most issues during development.

Q: How do I set the base URL? A: Pass it to the constructor: new IrisClient({ baseUrl: "https://api.iris.dev" }), or set the IRIS_SERVICE_URL environment variable.

Q: Does the TypeScript SDK support fingerprint computation? A: No. Fingerprinting requires the Blake3 algorithm, which is not available in standard JavaScript. Use the Python SDK or call the server’s fingerprint verification endpoint.

Q: What’s the difference between @iris-hq/sdk and the MCP server’s client? A: @iris-hq/sdk is the public SDK for applications. The MCP server has its own internal client to avoid bundling the full SDK into Cloudflare Workers and to handle field name translation.

Examples

The TypeScript SDK is like a paper airplane versus the Python SDK’s delivery drone:

• Paper airplane (TS SDK) = Fold it from a single sheet (zero deps), throw it, and it glides to the destination using natural air currents (native fetch). Light, fast, works anywhere.
• Delivery drone (Python SDK) = Has cameras (Rich UI), GPS (schema validation), cargo bay (Blake3 engine), and a remote controller (CLI). More capable but needs batteries and maintenance.

Both get the message to the destination — you choose based on whether you need a quick toss or a full delivery service.