hanzo-tools-api

Generic API tools for Hanzo MCP:

• api: OpenAPI-first generic REST tool
• hanzo: Unified Hanzo platform router (auth, billing, commerce, iam, ingress, kms, mpc, paas, team, api)

Features

• Credential Management: Securely store and manage API keys with env var fallback
• OpenAPI Support: Parse OpenAPI 3.x specs to discover and call operations
• Auto-Detection: Automatically detects credentials from environment variables
• Multi-Provider: Built-in support for 30+ cloud providers
• Raw Requests: Make raw HTTP requests when you need more control

Installation

pip install hanzo-tools-api

Quick Start

Using Environment Variables (Recommended)

Set your API keys as environment variables:

export CLOUDFLARE_API_TOKEN=your-token
export GITHUB_TOKEN=ghp_xxx
export STRIPE_API_KEY=sk_xxx

The tool automatically detects these when you make calls.

Using the Tool

from hanzo_tools.api import APITool

tool = APITool()

# List available providers and their status
await tool.call(ctx, action="list")

# Configure a provider manually
await tool.call(ctx, 
    action="config",
    provider="cloudflare",
    api_key="your-key"
)

# Load OpenAPI spec for a provider
await tool.call(ctx, action="spec", provider="cloudflare")

# List available operations
await tool.call(ctx, action="ops", provider="cloudflare", search="zones")

# Call an operation
await tool.call(ctx,
    action="call",
    provider="cloudflare",
    operation="listZones"
)

# Make a raw request
await tool.call(ctx,
    action="raw",
    provider="github",
    method="GET",
    path="/user/repos"
)

Unified Hanzo Platform Tool

from hanzo_tools.api import HanzoTool

tool = HanzoTool()

# Discover available services
await tool.call(ctx, service="services")

# Route to service tools through one MCP surface
await tool.call(ctx, service="auth", action="status")
await tool.call(ctx, service="commerce", action="orders")
await tool.call(
    ctx,
    service="iam",
    action="enforce",
    args='{"owner":"hanzo","model":"rbac","resource":"/api/users","permission_action":"read"}',
)

MCP Tool Usage

When registered with hanzo-mcp, use like:

api                                    # List all providers
api --action config --provider github --api_key ghp_xxx
api --action ops --provider cloudflare --search zones
api --action call --provider cloudflare --operation listZones
api --action raw --provider github --method GET --path /user/repos

Supported Providers

Built-in configurations for:

API Reference

Actions

• list: Show all providers and their configuration status
• config: Set credentials for a provider
• delete: Remove credentials for a provider
• spec: Load/refresh OpenAPI spec for a provider
• ops: List available operations for a provider
• call: Call an API operation by operation ID
• raw: Make a raw HTTP request to any endpoint

Parameters

Credential Storage

Credentials are stored in ~/.hanzo/api/credentials.json with basic obfuscation. For production use, consider using system keyring or a secrets manager.

OpenAPI specs are cached in ~/.hanzo/api/specs/.

Adding Custom Providers

You can add any provider by providing a base URL and API key:

from hanzo_tools.api import get_credential_manager

cred_manager = get_credential_manager()
cred_manager.set_credential(
    provider="custom-api",
    api_key="your-key",
    base_url="https://api.custom.com/v1"
)

Then load a spec:

from hanzo_tools.api import get_client

client = await get_client(
    "custom-api",
    spec_url="https://api.custom.com/openapi.json"
)

Security Notes

• API keys are stored with basic base64 obfuscation (not encryption)
• Credentials file has restrictive permissions (0600)
• Environment variables are preferred for sensitive credentials
• Never commit credentials to version control

License

MIT