Skip to main content
Glama

SuFetch banner

SuFetch

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

Table of Contents


Related MCP server: apifable

What is SuFetch?

SuFetch combines two powerful tools:

  1. Type-Safe API Clients - Generate fully-typed TypeScript clients from OpenAPI specifications

  2. MCP 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
  })
}

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

SuFetch currently includes:

API

Description

Endpoints

Import

DigitalOcean

Complete cloud platform API

200+

sufetch/digitalocean

Hetzner Cloud

Cloud infrastructure management

100+

sufetch/hetzner

Ory Kratos

Identity & user management

50+

sufetch/ory

Ory Hydra

OAuth 2.0 & OpenID Connect

40+

sufetch/ory

Want to add more? See Adding New APIs.

MCP Server Setup

Quick Setup

1. Install (choose one):

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

2. Configure:

Edit config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Restart Claude Desktop.

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

Or create .mcp.json:

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

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

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

  1. Create directory: mkdir -p openapi-specs/myapi

  2. Add your myapi.json OpenAPI spec

  3. Copy apiful.config.ts and index.ts from openapi-specs/ory/ as template

  4. Run pnpm build

Done! Your API is now available as sufetch/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

# 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

Still 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`

License

MIT © 2025


Built with apiful · MCP

Available Tools

7 tools
generate_code_exampleB

Generate a complete TypeScript code example for an endpoint

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI name (e.g., "hetzner/cloud", "ory/kratos")
pathYesEndpoint path
methodYesHTTP method

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It mentions generating code but offers no details on side effects, authentication requirements, output format, or constraints (e.g., supported APIs). This is insufficient for an AI agent to understand behavioral implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core purpose concisely. It is front-loaded and contains no filler, though it could be expanded with usage tips without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description is incomplete. It does not explain what the generated code example looks like, how to interpret the output, or any prerequisites. For a code generation tool, this information is critical.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no extra meaning beyond the schema, providing no additional context or examples for parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Generate a complete TypeScript code example') and the target resource ('an endpoint'), distinguishing it from sibling tools like get_api_info or get_endpoint_details which return metadata or documentation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (when you need a code example) but provides no explicit guidance on when to use vs alternatives like search_endpoints or get_schema_details. No when-not-to-use or alternative names are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_api_infoC

Get detailed information about a specific API

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI name (e.g., "hetzner/cloud", "ory/kratos")

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full responsibility. It only states the purpose without revealing behavioral traits such as authentication needs, rate limits, or what constitutes 'detailed information.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no redundant information. It is concise and front-loaded, though it could benefit from additional structure or detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description is incomplete. It does not explain the return format, scope of information, or any constraints, leaving agents underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the schema already describes the api_name parameter with examples. The description adds no additional meaning beyond what the schema provides, warranting a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states "Get detailed information about a specific API," which clearly identifies the verb and resource. However, it does not distinguish this tool from siblings like get_endpoint_details or get_schema_details, as 'detailed information' is vague and could overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. The description does not provide context, exclusions, or mention of sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_endpoint_detailsA

Get complete details and usage example for a specific endpoint

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI name (e.g., "hetzner/cloud", "ory/kratos")
pathYesEndpoint path (e.g., "/users")
methodYesHTTP method

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It merely describes the action without mentioning side effects (e.g., read-only, no modifications). The description is adequate for a simple retrieval tool but lacks transparency about non-destructiveness or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is concise and directly describes the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (3 well-described parameters, no output schema, no annotations), the description provides sufficient context for an agent to understand its functionality. However, it could mention that the endpoint must exist, making it slightly more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get complete details and usage example for a specific endpoint'. The verb 'Get' and resource 'complete details and usage example' are specific. However, it does not explicitly distinguish from sibling tools like get_schema_details, which might cause confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description is generic and does not provide context for choosing it over siblings like search_endpoints or get_schema_details.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_quickstartA

Generate a quickstart guide with common operations for an API

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI name (e.g., "hetzner/cloud", "ory/kratos")

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It fails to mention that the operation is read-only, safe, or whether it requires authentication. The description only describes output, not side effects or constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that directly states the purpose. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers the basic purpose but lacks details on usage context and behavioral safety, leaving room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter. The description adds no extra meaning beyond the schema's 'e.g., examples', so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (generate) and the resource (quickstart guide with common operations for an API). This distinguishes it from sibling tools like generate_code_example or get_api_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for generating a quickstart guide but does not explicitly state when to use this tool vs alternatives like search_endpoints or list_apis. No when-not or prerequisite guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_schema_detailsC

Get details about a schema/model definition

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI name (e.g., "hetzner/cloud", "ory/kratos")
schema_nameYesSchema name from components/schemas

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states it gets details but does not indicate what 'details' entails, whether it is read-only, or any side effects or constraints. This is insufficient for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that immediately communicates the tool's purpose. It is front-loaded and efficient, though it could be slightly expanded for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and annotations, the description should provide more context about return values and behavior. It only states the action without explaining what is returned or any operational details, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with both parameters (api_name, schema_name) having clear descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get details about a schema/model definition', which identifies a specific verb and resource. However, it does not differentiate from sibling tools like get_endpoint_details or get_api_info, leaving potential ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Sibling tools exist for different purposes, but the description lacks explicit when-to-use, when-not-to-use, or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_apisA

List all available API specifications with their metadata

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must imply behavioral traits. 'List' suggests a read-only operation, but there is no explicit mention of safety, rate limits, or scope of data returned. Adequate for a simple tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with key information. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description is complete. It covers what the tool does (list APIs with metadata) and implies the result format. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters, so schema coverage is 100%. The description adds no additional parameter info, but none is needed. Baseline score of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists all available API specifications with metadata. The verb 'list' and resource are specific, and the tool's purpose is distinct from sibling tools that focus on code generation or detailed information retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. The description only states what it does, without any context on when not to use it or what prerequisites exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_endpointsC

Search for API endpoints by query, method, or tags

ParametersJSON Schema
NameRequiredDescriptionDefault
api_nameYesAPI to search (e.g., "hetzner/cloud", "ory/kratos")
queryNoSearch query for path/summary/operationId
methodNoFilter by HTTP method
limitNoMaximum results to return

TDQS

C2.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose whether the search is read-only, any rate limits, or pagination behavior. 'Search' implies a safe operation but no explicit confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Brief at one sentence, but includes inaccurate information ('tags'). Being concise is not helpful if inaccurate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should compensate with details on result format, required params, etc. It fails to do so, leaving the agent needing to infer behavior from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. However, the description adds 'tags' which is not a parameter, introducing confusion. This misdirection outweighs any benefit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Search for API endpoints by query, method, or tags', which identifies the action and resources, but the mention of 'tags' is inaccurate as no tags parameter exists in the schema. This reduces clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool over siblings like 'list_apis' or 'get_endpoint_details'. The description implies a generic search scenario but does not specify exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clear and distinct purpose: code generation, API info, endpoint details, quickstart, schema details, listing, and searching. No overlapping functionality that would confuse an agent.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using lowercase and underscores (e.g., generate_code_example, list_apis). The naming is predictable and easy to understand.

Tool Count5/5

With 7 tools, the server is well-scoped. It covers all necessary operations for exploring API documentation without being bloated or too minimal.

Completeness4/5

The tool surface covers listing, searching, and retrieving details for APIs, endpoints, schemas, code examples, and quickstarts. However, there is no tool to list all schemas directly, which is a minor gap.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/productdevbook/sufetch'

If you have feedback or need assistance with the MCP directory API, please join our Discord server