Tools Reference
Quick summary
Use this page as a lookup table, not a getting-started tutorial. Local protect tools operate on a trusted workspace; remote tools operate on seller or public backend resources.
Choose read-only inspection first, then check tool schema, authorization, side effects, and the returned receipt.
Every tool name and input schema below is quoted from the running registries: tools/devpay-mcp/server.mjs TOOL_DEFS (6 local tools) and mcp/gateway/worker.js TOOL_DEFS (20 remote tools). All input schemas are {"type":"object","additionalProperties":false}.
Result shape on every server: {content:[{type:"text",text:<json>}],isError} plus a receipt {"receipt":{"tool","request_id","action":"read|write","at","ok"}} inside the payload.
Local protect tools (yp-mcp)
Annotations come from the server: RO = read-only, EXEC = executes workspace code (non-destructive, idempotent, open-world), RW = the approval-gated write stage (also executes code).
Shared argument: project (string) — project directory containing devpay.json, relative to the workspace root or absolute inside it; defaults to the workspace root.
yetdapay_project_analyze
Runs yp protect plan (the CLI has no standalone analyze command) and embeds the parsed .devpay/*.analysis.json. Writes .devpay/ staging only — but executes project code (driver import). EXEC.
| Arg | Type | Maps to |
|---|---|---|
target | string (path, must exist in workspace) | --target |
driver | string (path) | --driver |
spec | string (path) | --spec |
overrides | string (path) | --overrides |
no_dynamic | boolean | --no-dynamic |
yetdapay_protection_plan
Same argv as analyze; writes .devpay/plan.json with per-asset AUTO/AGENT/MANUAL_REVIEW decisions. Plan-only — nothing applied. EXEC.
Args: project, target, driver, spec, overrides, no_dynamic (same mapping as above).
yetdapay_protection_review
Runs yp protect review — human-readable §6.1 plan summary. Requires a plan to exist. RO. Args: project only.
yetdapay_protection_apply
Runs yp protect apply --approve. Refused with a UNAUTHORIZED tool error before any spawn unless approved:true. The refusal payload includes the pending plan's plan_sha256/spec_sha256/target_sha256 when known, so the agent can show the user exactly what needs approval. RW.
| Arg | Type | Required | Maps to |
|---|---|---|---|
approved | boolean | must be exactly true | enables --approve |
vectors | string (path) | — | --vectors |
port | integer 1–65535 | — | --port |
auth | string enum dev-open | yp-license | — | --auth |
license_seed | string (path) | — | --license-seed |
The response adds approval.{approved_by_caller,plan_sha256,spec_sha256,target,target_sha256,driver_sha256} — additive on top of the verbatim CLI payload.
yetdapay_protection_verify
Runs yp protect verify. Executes project code — boots the generated partition server, imports the partitioned client. EXEC.
| Arg | Type | Maps to |
|---|---|---|
vectors | string (path) | --vectors |
port | integer 1–65535 | --port |
asset | string | --asset (restrict to one spec asset id) |
api_base | string | --api-base |
yetdapay_environment_doctor
Runs yp doctor. Any FAIL → CLI exit 1 → isError:true. RO.
| Arg | Type | Maps to |
|---|---|---|
api_base | string | --api-base |
Remote gateway tools (20)
Scope column: seller = Authorization: Bearer required, forwarded verbatim upstream; public = never carries credentials. ro/write = readOnlyHint/destructiveHint annotation.
Stores & integration (the original 10)
| Tool | Scope | Act | Args (required bold) | Upstream |
|---|---|---|---|---|
yetdapay_store_list | seller | ro | — | GET /projects → {stores:[…]} |
yetdapay_store_get | seller | ro | store_id | GET /projects/:id |
yetdapay_install_manifest_get | seller | ro | store_id | GET /projects/:id/integration → {integration,manifest}; 404 → tool error NOT_CONFIGURED |
yetdapay_integration_status | seller | ro | store_id | same GET; summarizes configured/donation_enabled/donation_mode/feedback_configured/public_id/hosted_path; never errors on 404 |
yetdapay_donation_config_get | seller | ro | store_id | same GET; donation config incl. parsed donation_amounts_krw |
yetdapay_donation_configure | seller | write | store_id, donation_enabled bool, donation_title, donation_description, donation_amounts_krw number[] (each >0 and <=1,000,000) | local validation → GET-merge (preserves unset fields incl. feedback_widget_id) → PUT; idempotent |
yetdapay_feedback_config_get | seller | ro | store_id | integration GET + GET /feedback-widgets?project_id= → {feedback_widget_id, widgets:[…]} |
yetdapay_feedback_configure | seller | write | store_id, feedback_widget_id | given id → else reuse existing is_public widget → else create default (support-*, FREE_OR_PAID) → PUT; idempotent |
yetdapay_integration_assets_get | public | ro | mode enum hosted|native, framework enum nuxt|react|vanilla, feature enum donation|feedback|both, store_id (optional; resolves public_id via seller API when a credential is configured) | none (or seller integration GET for public_id) — emits hosted <a> snippet or native component instructions |
yetdapay_integration_validate | seller | ro | store_id | seller integration GET + unauthenticated GET /public/integrations/:public_id + widget list → {checks:[…],ok} |
Seller read tools (the 10 added reads)
| Tool | Scope | Act | Args | Upstream |
|---|---|---|---|---|
yetdapay_project_list | seller | ro | — | GET /projects → {items} (raw upstream rows) |
yetdapay_project_get | seller | ro | project_id | GET /projects/:id → {project}; other tenants get NOT_FOUND |
yetdapay_product_list | seller | ro | — | GET /products → {items} |
yetdapay_license_list | seller | ro | — | GET /licenses → {items} (license keys are not exposed by the list endpoint) |
yetdapay_license_get | seller | ro | license_id | seller-scoped GET /licenses list + select (no single-GET route exists); absent → tool error NOT_FOUND |
yetdapay_license_bindings | seller | ro | license_id | GET /licenses/:id/bindings — PoP device bindings (jkt thumbprints + created_at) |
yetdapay_license_usage | seller | ro | license_id | GET /licenses/:id/usage — execution usage log + durable counters |
yetdapay_usage_counters | seller | ro | lic_id (optional filter) | GET /usage-counters[?lic_id=] — durable counters, tenant scope |
yetdapay_security_events | seller | ro | lic_id (optional filter) | GET /security-events[?lic_id=] — security events, tenant scope |
yetdapay_license_verify | public | ro | key, product_id, device_id (optional) | POST /licenses/verify — unauthenticated by contract |
Tenant scoping
All seller reads are upstream tenant-scoped — the backend enforces seller_id filtering (products.seller_id/projects.seller_id joins); the gateway never widens it. Upstream 4xx/5xx propagate as honest tool errors via mapUpstreamError — no fake success.
Local commerce tools (Rust mcp/)
The original 10 commerce tools (identical contract to the gateway's first ten) also exist on the Rust stdio server for local be/ targets, with env-var credentials instead of header passthrough:
| Variable | Default | Purpose |
|---|---|---|
YETDAPAY_API_BASE | http://127.0.0.1:8080/api/v1 | Axum REST base |
YETDAPAY_SITE_ORIGIN | http://127.0.0.1:3000 | Hosted-link origin |
YETDAPAY_DEV_USER | — | Dev auth X-Dev-User header |
YETDAPAY_MCP_TOKEN | — | Bearer token; takes precedence over YETDAPAY_DEV_USER |
YETDAPAY_REQUEST_TIMEOUT_MS | 10000 | Per-request timeout |
Build/run: cd mcp && cargo build && ./target/debug/yetdapay-mcp.