Overview

Duckfly Proxy is a lightweight HTTP proxy that observes real API usage and sends only structural request metadata to the Duckfly platform.

This allows your API documentation and MCP (Model Context Protocol) servers to be continuously enriched based on how your application actually behaves, keeping everything aligned as the system evolves.

Why use Duckfly Proxy

• Continuously enriched API documentation
• MCP server generation for AI integrations
• Documentation aligned with real API usage
• No code changes required; just point your application to the proxy

Quick Start

Global install

npm install -g @duckfly/proxy

Or run directly with npx

npx @duckfly/proxy

Interactive mode

When you run the CLI without arguments, it will guide you through the setup:

| Prompt | Description | Default | |---|---|---| | Token | Your Duckfly application token | | | Proxy Port | Port where the proxy listens | 8080 | | Target URL | Your backend API address | App URL from token |

Configuration is saved locally in .duckfly-proxy.json so you don't need to enter it every time.

Command line mode

You can pass all options via CLI arguments. The CLI will only ask for what is missing.

# Full command line (no prompts)
duckfly-proxy --token abc123 --port 8080 --target http://localhost:3000

# Hybrid: pass what you know, it asks the rest
duckfly-proxy --token abc123

# With npx
npx @duckfly/proxy --token abc123 --port 8080 --target http://localhost:3000

All available flags:

| Flag | Description | |---|---| | --token <token> | Duckfly application token | | --port <N> | Proxy port (default: 8080) | | --target <url> | URL to forward requests to | | --help | Show help |

How It Works

┌─────────────┐        ┌──────────────┐        ┌──────────────┐
│ Application │ ───>   │ Duckfly Proxy│ ───>   │   Backend    │
└─────────────┘        └──────────────┘        └──────────────┘
                               │
              Sends API structure (with placeholders)
                               │
                               ▼
                       ┌─────────────────┐
                       │   Duckfly API   │
                       │ Documentation & │
                       │ MCP Generation  │
                       └─────────────────┘

1. Your application routes requests through Duckfly Proxy
2. The proxy forwards requests to your backend without changing behavior
3. Structural API information is sent to Duckfly
4. Documentation and MCP servers evolve continuously

Data Handling

Duckfly Proxy processes only technical and structural information such as HTTP methods, routes, headers, and payload formats.

Request and response values are replaced with placeholders before being sent, ensuring no sensitive or user specific data is transmitted.

What is sent

• HTTP methods and route paths
• Header names (values are redacted)
• Body structure and field names (values replaced with type appropriate placeholders)
• Status codes and content types

What is NOT sent

• Authentication tokens, passwords, or secrets
• Request/response body values
• Cookie values
• Query parameter values for sensitive fields

Host Alias

When your application domain (from the Duckfly token) differs from localhost, the proxy automatically adjusts the Host header so that observed requests are associated with the correct domain. This happens automatically; no configuration is needed.

License

MIT License

This license applies only to the Duckfly Proxy package. The Duckfly platform and services are governed by separate terms.