Spec: Add optional meta block for schema metadata

[a6b8]

Motivation

After researching 300+ public APIs for FlowMCP schema candidates, a clear pattern emerged: AI agents need structured context about an API beyond just endpoints and parameters. Rate limits, auth type, geographic coverage, and update frequency are critical for intelligent tool selection.

Currently, this information only exists in the schema description (free text), which agents cannot parse reliably.

Proposal

Add an optional meta block to the main export:

export const main = {
    namespace: 'usgs',
    name: 'earthquake',
    description: '...',
    version: '2.0.0',
    root: 'https://earthquake.usgs.gov',
    meta: {
        rateLimit: { requests: 20000, per: 'query' },
        auth: 'none',
        license: 'public-domain',
        coverage: 'global',
        updateFrequency: 'real-time'
    },
    routes: { /* ... */ }
}

Field Definitions

Field	Type	Values	Purpose
rateLimit	object	{ requests: number, per: string }	Helps agent pace requests
auth	string	none, apiKey, bearer, oauth2, basic	Agent knows if setup is needed
license	string	Free text (e.g. CC-BY-4.0, public-domain)	Legal context
coverage	string	global, us, eu, de, etc.	Geographic relevance
updateFrequency	string	real-time, hourly, daily, weekly, monthly	Data freshness

Design Principles

• Entirely optional — no existing schema breaks
• Lives in main — hashable, declarative, no code
• Validation: soft (warnings, not errors) — so schemas work even with incomplete meta
• AI-first: These fields are primarily consumed by AI agents, not by the FlowMCP runtime

Spec Work Required

• Define meta block structure in spec document
• Define allowed values and validation rules
• Define soft validation behavior (warnings, not errors)
• Add examples for different API types (free, keyed, OAuth, real-time vs static)

Priority

P2 — Not blocking, but significantly improves agent decision-making when 100+ tools are available.