SuFetch

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 SuFetch?

SuFetch combines two powerful tools:

1. undefinedType-Safe API Clients - Generate fully-typed TypeScript clients from OpenAPI specifications
2. undefinedMCP Server - Let AI assistants (like Claude) explore your APIs and generate code

Built with apiful for type-safe OpenAPI clients.

Features

• ✨ Fully Type-Safe - Autocomplete and type checking for all API calls
• 🤖 MCP Integration - AI assistants can explore and generate code for your APIs
• 🔄 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 sufetch

# pnpm
pnpm add sufetch

# yarn
yarn add sufetch

For MCP Server (Global)

# Install globally
npm install -g sufetch

# Verify installation
sufetch-mcp --version

For Development

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

Quick Start

Using the Type-Safe API Client

import { createClient, cloud } from 'sufetch/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 'sufetch/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
  })
}

undefinedAvailable properties:undefined

• ['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

SuFetch currently includes:

undefinedWant to add more? See Adding New APIs.

MCP Server Setup

Quick Setup

undefined1. Install (choose one):undefined

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

undefined2. Configure:undefined

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

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

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

undefined3. Test:undefined
Ask Claude: “List available APIs using sufetch”

Available MCP Tools

Adding New APIs

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

# Test server works
sufetch-mcp  # Should output: "SuFetch 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)

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

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

Contributing

Contributions welcome! See CONTRIBUTING.md.

git clone https://github.com/productdevbook/sufetch.git
cd sufetch
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 · MCP