{"id":32722665,"url":"https://github.com/productdevbook/toonfetch","last_synced_at":"2025-11-02T22:01:58.581Z","repository":{"id":322085606,"uuid":"1088162261","full_name":"productdevbook/toonfetch","owner":"productdevbook","description":"Next-generation openapi MCP and fetch library.","archived":false,"fork":false,"pushed_at":"2025-11-02T14:21:36.000Z","size":193,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-02T14:31:09.310Z","etag":null,"topics":["mcp","mcp-server","ofetch","openai-api","openapi-spec","toon"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/productdevbook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["productdevbook"]}},"created_at":"2025-11-02T12:47:47.000Z","updated_at":"2025-11-02T14:21:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/productdevbook/toonfetch","commit_stats":null,"previous_names":["productdevbook/toonfetch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/productdevbook/toonfetch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/productdevbook%2Ftoonfetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/productdevbook%2Ftoonfetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/productdevbook%2Ftoonfetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/productdevbook%2Ftoonfetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/productdevbook","download_url":"https://codeload.github.com/productdevbook/toonfetch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/productdevbook%2Ftoonfetch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282365372,"owners_count":26657259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-02T02:00:06.609Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-server","ofetch","openai-api","openapi-spec","toon"],"created_at":"2025-11-02T22:01:11.285Z","updated_at":"2025-11-02T22:01:58.575Z","avatar_url":"https://github.com/productdevbook.png","language":"TypeScript","readme":"[![ToonFetch banner](./.github/assets/banner.svg)](https://github.com/productdevbook/toonfetch)\n\n# ToonFetch\n\n\u003cp\u003e\n  \u003ca href=\"https://www.npmjs.com/package/toonfetch\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/toonfetch.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/toonfetch\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/toonfetch.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/productdevbook/toonfetch/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/productdevbook/toonfetch.svg?style=flat\u0026colorA=18181B\u0026colorB=28CF8D\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.typescriptlang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/TypeScript-5.7-18181B?style=flat\u0026logo=typescript\u0026colorB=3178C6\" alt=\"TypeScript\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/productdevbook/toonfetch\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP%20Server-18181B?style=flat\u0026logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTIgMkw0IDdWMTdMMTIgMjJMMjAgMTdWN0wxMiAyWiIgc3Ryb2tlPSIjRkZGIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48L3N2Zz4=\u0026colorB=28CF8D\" alt=\"MCP Server\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e Type-safe OpenAPI clients with MCP server for AI-driven API exploration\n\n## Table of Contents\n\n- [Features](#features) · [Installation](#installation) · [Quick Start](#quick-start)\n- [MCP Server Setup](#mcp-server-setup) · [Supported APIs](#supported-apis)\n- [Development](#development) · [Contributing](#contributing)\n\n---\n\n## What is ToonFetch?\n\nToonFetch combines two powerful tools:\n\n1. **Type-Safe API Clients** - Generate fully-typed TypeScript clients from OpenAPI specifications\n2. **MCP Server** - Let AI assistants (like Claude) explore your APIs and generate code\n\nBuilt with [apiful](https://github.com/lisnote/apiful) and [TOON format](https://github.com/toon-format/toon) for efficient OpenAPI spec compression.\n\n## Features\n\n- ✨ **Fully Type-Safe** - Autocomplete and type checking for all API calls\n- 🤖 **MCP Integration** - AI assistants can explore and generate code for your APIs\n- 📦 **Compressed Specs** - TOON format reduces OpenAPI specs by 40-45%\n- 🔄 **Auto-Discovery** - Automatic service detection and type generation\n- 🛠️ **Modern Stack** - TypeScript 5.7, ESNext, strict mode\n- 🧪 **Well-Tested** - 76+ tests with \u003e60% coverage\n\n## Installation\n\n### For Using the API Client\n\n```bash\n# npm\nnpm install toonfetch\n\n# pnpm\npnpm add toonfetch\n\n# yarn\nyarn add toonfetch\n```\n\n### For MCP Server (Global)\n\n```bash\n# Install globally\nnpm install -g toonfetch\n\n# Verify installation\ntoonfetch-mcp --version\n```\n\n### For Development\n\n```bash\ngit clone https://github.com/productdevbook/toonfetch.git\ncd toonfetch\npnpm install\npnpm build\n```\n\n## Quick Start\n\n### Using the Type-Safe API Client\n\n```typescript\nimport { createClient, cloud } from 'toonfetch/hetzner'\n\n// Create a typed client\nconst client = createClient({\n  baseURL: 'https://api.hetzner.cloud/v1',\n  headers: {\n    'Authorization': 'Bearer your-api-token'\n  }\n}).with(cloud)\n\n// Fully typed requests and responses\nconst servers = await client('/servers', {\n  method: 'GET'  // ✅ Type-checked\n})\n\n// TypeScript knows the response type\nconsole.log(servers.servers)  // ✅ Autocomplete works\n```\n\nSee [Supported APIs](#supported-apis) for all available services.\n\n### Type Helpers for Advanced Type Safety\n\nExtract specific types from endpoints for maximum type safety:\n\n```typescript\nimport type { HetznerCloud } from 'toonfetch/hetzner'\n\n// Extract request body type\ntype CreateServerBody = HetznerCloud\u003c'/servers', 'post'\u003e['request']\n\n// Extract response type\ntype GetServerResponse = HetznerCloud\u003c'/servers/{id}', 'get'\u003e['response']\n\n// Extract query parameters\ntype ListServersQuery = HetznerCloud\u003c'/servers', 'get'\u003e['query']\n\n// Extract path parameters\ntype ServerPathParams = HetznerCloud\u003c'/servers/{id}', 'get'\u003e['path']\n\n// Use in functions for type safety\nfunction processServer(server: GetServerResponse) {\n  console.log(server.server.id)    // ✅ Full autocomplete\n  console.log(server.server.name)  // ✅ Type-checked\n}\n\nfunction createServer(body: CreateServerBody) {\n  // TypeScript enforces correct structure\n  return client('/servers', {\n    method: 'POST',\n    body  // ✅ Type-safe\n  })\n}\n```\n\n**Available properties:**\n- `['request']` - Request body type\n- `['response']` - Success response (200/201)\n- `['query']` - Query parameters\n- `['path']` - Path parameters\n- `['responses'][status]` - Specific status code response\n\nWorks with all APIs: `HetznerCloud`, `DigitalOcean`, `OryKaratos`, `OryHydra`.\n\n### Using with AI Assistants (MCP)\n\nSee the [MCP Server Setup](#mcp-server-setup) section below.\n\n## Supported APIs\n\nToonFetch currently includes:\n\n| API | Description | Endpoints | Import |\n|-----|-------------|-----------|--------|\n| **DigitalOcean** | Complete cloud platform API | 200+ | `toonfetch/digitalocean` |\n| **Hetzner Cloud** | Cloud infrastructure management | 100+ | `toonfetch/hetzner` |\n| **Ory Kratos** | Identity \u0026 user management | 50+ | `toonfetch/ory` |\n| **Ory Hydra** | OAuth 2.0 \u0026 OpenID Connect | 40+ | `toonfetch/ory` |\n\n**Want to add more?** See [Adding New APIs](#adding-new-apis).\n\n## MCP Server Setup\n\n### Quick Setup\n\n**1. Install (choose one):**\n```bash\nnpm install -g toonfetch  # Global\nnpx toonfetch-mcp         # No install\n```\n\n**2. Configure:**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\nEdit config file:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"toonfetch\": {\n      \"command\": \"toonfetch-mcp\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code CLI\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n```bash\nclaude mcp add --transport stdio --scope project toonfetch -- toonfetch-mcp\n```\n\nOr create `.mcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"toonfetch\": {\n      \"command\": \"toonfetch-mcp\"\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n**3. Test:**\nAsk Claude: \"List available APIs using toonfetch\"\n\n### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_apis` | List all available APIs |\n| `get_api_info` | Get API metadata |\n| `search_endpoints` | Search by path/method/description |\n| `get_endpoint_details` | Get full endpoint specs |\n| `get_schema_details` | Get data schemas |\n| `generate_code_example` | Generate TypeScript code |\n| `get_quickstart` | Get API quickstart guide |\n\n## Adding New APIs\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to see how to add your own OpenAPI specs\u003c/summary\u003e\n\n1. Create directory: `mkdir -p openapi-specs/myapi`\n2. Add your `myapi.json` OpenAPI spec\n3. Copy `apiful.config.ts` and `index.ts` from `openapi-specs/ory/` as template\n4. Run `pnpm build`\n\nDone! Your API is now available as `toonfetch/myapi` and in the MCP server.\n\nSee [CLAUDE.md](./CLAUDE.md) for detailed instructions.\n\u003c/details\u003e\n\n## Development\n\n```bash\npnpm install  # Install\npnpm build    # Build\npnpm test     # Test\npnpm lint:fix # Lint\n```\n\nSee [CLAUDE.md](./CLAUDE.md) for architecture, build pipeline, and contribution guide.\n\n## Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003eMCP Server not showing?\u003c/summary\u003e\n\n```bash\n# Test server works\ntoonfetch-mcp  # Should output: \"ToonFetch MCP server running on stdio\"\n\n# Check config\nclaude mcp list  # For Claude Code\ncat .mcp.json    # Check file exists\n\n# Restart Claude Desktop (if using Desktop)\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild issues?\u003c/summary\u003e\n\n```bash\nrm -rf node_modules pnpm-lock.yaml dist\npnpm install \u0026\u0026 pnpm build\n```\n\u003c/details\u003e\n\n**Still stuck?** [Open an issue](https://github.com/productdevbook/toonfetch/issues) with your Node version and error message.\n\n## Why TOON Format?\n\nTOON compresses OpenAPI specs by ~40-50%:\n\n| Spec | JSON | TOON | Savings |\n|------|------|------|---------|\n| Hetzner Cloud | 747k tokens | 374k tokens | **50%** |\n| Ory Kratos | 134k tokens | 73k tokens | **45%** |\n| Ory Hydra | 69k tokens | 40k tokens | **42%** |\n\n**Benefits:**\n- Fits more APIs in Claude's context\n- Faster loading\n- Lower token costs\n\nLearn more: [TOON Format](https://github.com/toon-format/toon)\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n```bash\ngit clone https://github.com/productdevbook/toonfetch.git\ncd toonfetch\npnpm install \u0026\u0026 pnpm build\n# Make changes, run `pnpm test \u0026\u0026 pnpm lint:fix`\n```\n\n## Links\n\n- [CLAUDE.md](./CLAUDE.md) - Architecture \u0026 development guide\n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP docs\n\n## License\n\nMIT © 2025\n\n---\n\nBuilt with [apiful](https://github.com/lisnote/apiful) · [TOON](https://github.com/toon-format/toon) · [MCP](https://modelcontextprotocol.io/)\n","funding_links":["https://github.com/sponsors/productdevbook"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproductdevbook%2Ftoonfetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproductdevbook%2Ftoonfetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproductdevbook%2Ftoonfetch/lists"}