toonfetch

ToonFetch

Type-safe OpenAPI clients with MCP server for AI-driven API exploration

Table of Contents

• Features · Installation · Quick Start
• MCP Server Setup · Supported APIs
• Development · Contributing

What is ToonFetch?

ToonFetch combines two powerful tools:

• Type-Safe API Clients - Generate fully-typed TypeScript clients from OpenAPI specifications
• MCP Server - Let AI assistants (like Claude) explore your APIs and generate code

Built with apiful and TOON format for efficient OpenAPI spec compression.

Features

• ✨ Fully Type-Safe - Autocomplete and type checking for all API calls
• 🤖 MCP Integration - AI assistants can explore and generate code for your APIs
• 📦 Compressed Specs - TOON format reduces OpenAPI specs by 40-45%
• 🔄 Auto-Discovery - Automatic service detection and type generation
• 🛠️ Modern Stack - TypeScript 5.7, ESNext, strict mode
• 🧪 Well-Tested - 76+ tests with >60% coverage

Installation

For Using the API Client

# npm
npm install toonfetch

# pnpm
pnpm add toonfetch

# yarn
yarn add toonfetch

For MCP Server (Global)

# Install globally
npm install -g toonfetch

# Verify installation
toonfetch-mcp --version

For Development

git clone https://github.com/productdevbook/toonfetch.git
cd toonfetch
pnpm install
pnpm build

Quick Start

Using the Type-Safe API Client

import { createClient, cloud } from 'toonfetch/hetzner'

// Create a typed client
const client = createClient({
  baseURL: 'https://api.hetzner.cloud/v1',
  headers: {
    'Authorization': 'Bearer your-api-token'
  }
}).with(cloud)

// Fully typed requests and responses
const servers = await client('/servers', {
  method: 'GET'  // ✅ Type-checked
})

// TypeScript knows the response type
console.log(servers.servers)  // ✅ Autocomplete works

See Supported APIs for all available services.

Type Helpers for Advanced Type Safety

Extract specific types from endpoints for maximum type safety:

import type { HetznerCloud } from 'toonfetch/hetzner'

// Extract request body type
type CreateServerBody = HetznerCloud<'/servers', 'post'>['request']

// Extract response type
type GetServerResponse = HetznerCloud<'/servers/{id}', 'get'>['response']

// Extract query parameters
type ListServersQuery = HetznerCloud<'/servers', 'get'>['query']

// Extract path parameters
type ServerPathParams = HetznerCloud<'/servers/{id}', 'get'>['path']

// Use in functions for type safety
function processServer(server: GetServerResponse) {
  console.log(server.server.id)    // ✅ Full autocomplete
  console.log(server.server.name)  // ✅ Type-checked
}

function createServer(body: CreateServerBody) {
  // TypeScript enforces correct structure
  return client('/servers', {
    method: 'POST',
    body  // ✅ Type-safe
  })
}

Available properties:

• ['request'] - Request body type
• ['response'] - Success response (200/201)
• ['query'] - Query parameters
• ['path'] - Path parameters
• ['responses'][status] - Specific status code response

Works with all APIs: HetznerCloud, DigitalOcean, OryKaratos, OryHydra.

Using with AI Assistants (MCP)

See the MCP Server Setup section below.

Supported APIs

ToonFetch currently includes:

API	Description	Endpoints	Import
DigitalOcean	Complete cloud platform API	200+	toonfetch/digitalocean
Hetzner Cloud	Cloud infrastructure management	100+	toonfetch/hetzner
Ory Kratos	Identity & user management	50+	toonfetch/ory
Ory Hydra	OAuth 2.0 & OpenID Connect	40+	toonfetch/ory

Want to add more? See Adding New APIs.

MCP Server Setup

Quick Setup

1. Install (choose one):

npm install -g toonfetch  # Global
npx toonfetch-mcp         # No install

2. Configure:

Claude Desktop (click to expand)

Edit config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "toonfetch": {
      "command": "toonfetch-mcp"
    }
  }
}

Restart Claude Desktop.

Claude Code CLI (click to expand)

claude mcp add --transport stdio --scope project toonfetch -- toonfetch-mcp

Or create .mcp.json:

{
  "mcpServers": {
    "toonfetch": {
      "command": "toonfetch-mcp"
    }
  }
}

3. Test: Ask Claude: "List available APIs using toonfetch"

Available MCP Tools

Tool	Description
list_apis	List all available APIs
get_api_info	Get API metadata
search_endpoints	Search by path/method/description
get_endpoint_details	Get full endpoint specs
get_schema_details	Get data schemas
generate_code_example	Generate TypeScript code
get_quickstart	Get API quickstart guide

Adding New APIs

Click to see how to add your own OpenAPI specs

• Create directory: mkdir -p openapi-specs/myapi
• Add your myapi.json OpenAPI spec
• Copy apiful.config.ts and index.ts from openapi-specs/ory/ as template
• Run pnpm build

Done! Your API is now available as toonfetch/myapi and in the MCP server.

See CLAUDE.md for detailed instructions.

Development

pnpm install  # Install
pnpm build    # Build
pnpm test     # Test
pnpm lint:fix # Lint

See CLAUDE.md for architecture, build pipeline, and contribution guide.

Troubleshooting

MCP Server not showing?

# Test server works
toonfetch-mcp  # Should output: "ToonFetch MCP server running on stdio"

# Check config
claude mcp list  # For Claude Code
cat .mcp.json    # Check file exists

# Restart Claude Desktop (if using Desktop)

Build issues?

rm -rf node_modules pnpm-lock.yaml dist
pnpm install && pnpm build

Still stuck? Open an issue with your Node version and error message.

Why TOON Format?

TOON compresses OpenAPI specs by ~40-50%:

Spec	JSON	TOON	Savings
Hetzner Cloud	747k tokens	374k tokens	50%
Ory Kratos	134k tokens	73k tokens	45%
Ory Hydra	69k tokens	40k tokens	42%

Benefits:

• Fits more APIs in Claude's context
• Faster loading
• Lower token costs

Learn more: TOON Format

Contributing

Contributions welcome! See CONTRIBUTING.md.

git clone https://github.com/productdevbook/toonfetch.git
cd toonfetch
pnpm install && pnpm build
# Make changes, run `pnpm test && pnpm lint:fix`

Links

• CLAUDE.md - Architecture & development guide
• Model Context Protocol - MCP docs

License

MIT © 2025

Built with apiful · TOON · MCP