Tool Generation Methods - Quick Reference

OpenPets supports multiple automated tool generation methods for different API types.

Overview

Method	Best For	Command	Output
OpenAPI	REST APIs with OpenAPI/Swagger specs	`pets generate-openapi`	`openapi-client.ts` + `openapi-tools.ts`
SOAP/WSDL	Legacy SOAP web services	`pets generate-soap`	`soap-client.ts` + `soap-tools.ts`
GraphQL	GraphQL APIs	`pets generate-graphql`	`graphql-tools.ts`
JSON-RPC	JSON-RPC APIs	`pets generate-jsonrpc`	`jsonrpc-client.ts`
MCP	Services with MCP servers	`pets generate-mcp`	`mcp.ts`
README	Documentation-based APIs	`pets generate-readme`	Tool definitions from docs
Manual	Custom implementations	Write `index.ts`	Full control

Quick Start by API Type

REST APIs → OpenAPI

bash

# Create pet with OpenAPI generation
pets new my-api --type openapi --url https://api.example.com/openapi.json

# Or add to existing pet
cd pets/my-api
pets generate-openapi --url https://api.example.com/openapi.json --verbose

Requirements:

OpenAPI 3.0+ specification (JSON or YAML)
URL or local file path

Generated files:

openapi-client.ts - HTTP client with auth
openapi-tools.ts - Tool definitions

Usage in index.ts:

typescript

import openAPITools from "./openapi-tools"
return createPlugin(openAPITools)

SOAP Services → WSDL

bash

# Create pet
pets new my-soap-service
cd pets/my-soap-service

# Add soapSpec to package.json
{
  "soapSpec": {
    "url": "https://api.example.com/service?wsdl",
    "authType": "basic"
  }
}

# Generate SOAP tools
pets generate-soap --verbose

Requirements:

WSDL file or URL
wsdl-tsclient (auto-installed)
soap package (bun add soap)

Generated files:

soap-client.ts - SOAP client with auth
soap-tools.ts - Tool definitions

Usage in index.ts:

typescript

import soapTools from "./soap-tools"
return createPlugin(soapTools)

Auth types:

basic - Basic HTTP authentication
wssecurity - WS-Security UsernameToken
bearer - Bearer token
clientssl - Client SSL certificates
ntlm - NTLM authentication

GraphQL APIs

bash

cd pets/my-graphql-api
pets generate-graphql --url https://api.example.com/graphql --verbose

Requirements:

GraphQL endpoint with introspection enabled

Generated files:

graphql-tools.ts - Query/mutation tools

MCP Servers

bash

cd pets/my-mcp-pet
pets generate-mcp --verbose

Requirements:

mcpServer config in package.json:

json

{
  "mcpServer": {
    "url": "https://mcp.service.com/sse",
    "name": "service-name",
    "transport": "sse-remote"
  }
}

Generated files:

mcp.ts - Auto-generated MCP tools

JSON-RPC APIs

bash

cd pets/my-jsonrpc-api
pets generate-jsonrpc --url https://api.example.com/rpc --verbose

Requirements:

JSON-RPC 2.0 endpoint
Service discovery endpoint

Documentation-based APIs

bash

cd pets/my-api
pets generate-readme --registry "@example/v1#abc123" --verbose

Requirements:

ReadMe registry ID (--registry), e.g. @org/v1#hash
ReadMe-hosted API docs

Configuration Examples

package.json for OpenAPI

json

{
  "name": "@openpets/my-api",
  "openapiSpec": {
    "url": "https://api.example.com/openapi.json",
    "baseUrl": "https://api.example.com",
    "authType": "bearer",
    "authEnvVar": "MY_API_KEY",
    "responseFormat": "toon"
  }
}

package.json for SOAP

json

{
  "name": "@openpets/my-soap-service",
  "soapSpec": {
    "url": "https://api.example.com/service?wsdl",
    "authType": "basic",
    "authEnvVar": "MY_SERVICE_API_KEY"
  },
  "dependencies": {
    "openpets-sdk": "workspace:*",
    "soap": "^1.0.0"
  }
}

package.json for MCP

json

{
  "name": "@openpets/my-mcp-pet",
  "mcpServer": {
    "url": "https://mcp.service.com/sse",
    "name": "service-name",
    "transport": "sse-remote"
  }
}

CLI Options Reference

generate-openapi

bash

pets generate-openapi [options]

Options:
  --url <url>           URL to fetch OpenAPI spec from
  --file <path>         Local file path to OpenAPI spec
  --base-url <url>      Base URL for API calls (overrides spec servers)
  --output <file>       Output file name (default: openapi-client.ts)
  -n, --dry-run         Preview without writing files
  -v, --verbose         Show detailed output
  --dump-spec           Dump raw spec for debugging

generate-soap

bash

pets generate-soap [options]

Options:
  --url <url>              URL to fetch WSDL from
  --file <path>            Local file path to WSDL
  --auth-type <type>       Auth type (basic, wssecurity, bearer, clientssl, ntlm)
  --auth-env-var <var>     Environment variable name for credentials
  --output-client <file>   Output file for client (default: soap-client.ts)
  --output-tools <file>    Output file for tools (default: soap-tools.ts)
  --definitions-only       Generate only TypeScript definitions
  -n, --dry-run            Preview without writing files
  -v, --verbose            Show detailed output

generate-graphql

bash

pets generate-graphql [options]

Options:
  --url <url>           GraphQL endpoint URL
  --output <file>       Output file name (default: graphql-tools.ts)
  --dump-schema         Dump raw schema for debugging
  -n, --dry-run         Preview without writing files
  -v, --verbose         Show detailed output

generate-mcp

bash

pets generate-mcp [options]

Options:
  -v, --verbose         Show detailed output
  -n, --dry-run         Preview without writing files

Workflow Comparison

OpenAPI Workflow

bash

pets new my-api
cd pets/my-api
# Add openapiSpec to package.json
pets generate-openapi --verbose
# Edit index.ts to import openAPITools
bun test:pet my-api --query "test connection"
pets publish

SOAP Workflow

bash

pets new my-soap-service
cd pets/my-soap-service
# Add soapSpec to package.json
bun add soap
pets generate-soap --verbose
# Edit index.ts to import soapTools
bun test:pet my-soap-service --query "test connection"
pets publish

Manual Workflow

bash

pets new my-custom-pet
cd pets/my-custom-pet
# Write tools in index.ts manually
bun test:pet my-custom-pet --query "test connection"
pets publish

When to Use Each Method

Use OpenAPI when:

✅ Service has OpenAPI/Swagger spec
✅ REST API with JSON responses
✅ 10+ endpoints to implement
✅ Want automatic updates from spec changes

Use SOAP when:

✅ Service only provides SOAP/XML API
✅ Legacy enterprise systems
✅ Government or financial services
✅ WSDL file available

Use MCP when:

✅ Service has official MCP server
✅ OAuth-based authentication
✅ 20+ operations to implement
✅ Want to leverage existing MCP tooling

Use Manual when:

✅ API is not documented
✅ Custom business logic needed
✅ Non-standard protocols
✅ Simple APIs (< 5 endpoints)

Examples

OpenAPI Example

See: pets/replicate/, pets/anthropic/, pets/github/

SOAP Example

See: pets/intime/ (manual), docs/examples/soap-generation-example.md

MCP Example

See: pets/asana/, pets/sentry/, pets/slack/

Manual Example

See: pets/jira/, pets/postgres/, pets/hotels/

Troubleshooting

OpenAPI generation fails

bash

# Verify spec is valid
pets generate-openapi --url https://api.example.com/openapi.json --dump-spec

# Try with dry-run
pets generate-openapi --url https://api.example.com/openapi.json --dry-run

SOAP generation fails

bash

# Install wsdl-tsclient manually
npm install -g wsdl-tsclient

# Add soap dependency
bun add soap

# Try with verbose output
pets generate-soap --url https://api.example.com/service?wsdl --verbose

MCP generation fails

bash

# Verify mcpServer config in package.json
cat package.json | jq '.mcpServer'

# Try with verbose output
pets generate-mcp --verbose

Tool Generation Methods - Quick Reference ​

Overview ​

Quick Start by API Type ​

REST APIs → OpenAPI ​

SOAP Services → WSDL ​

GraphQL APIs ​

MCP Servers ​

JSON-RPC APIs ​

Documentation-based APIs ​

Configuration Examples ​

package.json for OpenAPI ​

package.json for SOAP ​

package.json for MCP ​

CLI Options Reference ​

generate-openapi ​

generate-soap ​

generate-graphql ​

generate-mcp ​

Workflow Comparison ​

OpenAPI Workflow ​

SOAP Workflow ​

Manual Workflow ​

When to Use Each Method ​

Use OpenAPI when: ​

Use SOAP when: ​

Use MCP when: ​

Use Manual when: ​

Examples ​

OpenAPI Example ​

SOAP Example ​

MCP Example ​

Manual Example ​

Troubleshooting ​

OpenAPI generation fails ​

SOAP generation fails ​

MCP generation fails ​

Resources ​

Tool Generation Methods - Quick Reference

Overview

Quick Start by API Type

REST APIs → OpenAPI

SOAP Services → WSDL

GraphQL APIs

MCP Servers

JSON-RPC APIs

Documentation-based APIs

Configuration Examples

package.json for OpenAPI

package.json for SOAP

package.json for MCP

CLI Options Reference

generate-openapi

generate-soap

generate-graphql

generate-mcp

Workflow Comparison

OpenAPI Workflow

SOAP Workflow

Manual Workflow

When to Use Each Method

Use OpenAPI when:

Use SOAP when:

Use MCP when:

Use Manual when:

Examples

OpenAPI Example

SOAP Example

MCP Example

Manual Example

Troubleshooting

OpenAPI generation fails

SOAP generation fails

MCP generation fails

Resources