Model Gateway

Model discovery, cataloging, and agent→provider contracting harness. Beckn Protocol v2-aligned (catalog + contract layer) and MCP-native.

Scope (v1): catalog + discovery + contract lifecycle over your generative-model providers (OpenRouter, Google Vertex, Runway, …). Transaction-sandbox / live-network participation (DeDi broadcast, signed callbacks) is a deferred phase.

What it answers for an agent

• "What models can generate video (or image/audio/text)?" — modality search
• "What does model X cost, what are its terms?" — pricing + ToU
• "Block this model for my use, track my usage, and let me rate it / get support" — contract lifecycle

Quick start

npm install
npm run migrate
npm run seed        # seeds OpenRouter, Google Vertex, Runway + representative models
npm start           # REST on :8090  (PORT to override)
npm run mcp         # MCP stdio server (tools for agents)
npm test            # 25/25 E2E (catalog + contract lifecycle + MCP)

REST API (Beckn verb → endpoint)

Beckn v2	Endpoint	Purpose
search	GET /api/search?out=video&cap=video-generation	search models by modality/capability/provider/price
—	GET /api/models?any=video&io=output	models supporting modality(ies)
—	GET /api/models/:id	model detail (Beckn Item: pricing, capabilities, ToU)
—	GET /api/providers / GET /api/providers/:id/catalog	providers + Beckn catalog
select	POST /api/contracts/quote	quote a contract
init	POST /api/contracts	create contract (agent blocks a model)
—	POST /api/contracts/:id/block	activate/block for use
status	GET /api/contracts/:id	contract + Beckn order view
track	POST /api/contracts/:id/usage / GET .../usage	record/aggregate usage
update	PATCH /api/contracts/:id	update quota/terms/notes
cancel	POST /api/contracts/:id/cancel	cancel
rating	POST /api/contracts/:id/rate	rate the model
support	POST /api/contracts/:id/support	request support

MCP tools (stdio)

list_providers, list_models, models_by_modality, get_model, get_catalog, quote, create_contract, block_model, update_contract, cancel_contract, track_usage, contract_status, rate_model, request_support

Add to an MCP client:

{ "mcpServers": { "model-gateway": { "command": "node", "args": ["/path/to/src/mcp/server.js"], "env": { "DB_PATH": "/path/to/model-gateway.sqlite" } } } }

Beckn v2 mapping

See docs/ARCHITECTURE.md. Provider→BPP, Model→Item, Catalog→Beckn Catalog, Contract→Order/Fulfillment, Rating/Support/Track→respective Beckn actions. Payloads are Beckn-shaped so they validate against v2 catalog/contract semantics.

Contract state machine

draft → quoted → active → (paused) → completed | cancelled | failed (+ support overlay).