KeeperHub / KeeperHub/keeperhub

OpenAPI: MCP workflow request-body schemas carry no example values

Open
#2,106 1 comment 0 reactions 0 assignees View on GitHub
confirmed needs-discussion
Dominant language
TypeScript
Stars
24
Forks
93
Avg merge
1d 4h
Merged PRs (30d)
253

Description

Split from #2099 (credit: @kramer-hans for the original finding).

`app/api/openapi/route.ts`, `buildPathEntry`, sets the request-body schema to `workflow.inputSchema` verbatim - the JSON Schema authored per-workflow through the marketplace listing UI. That schema has no `example` property on any field: `SchemaField` and `fieldsToJsonSchema()` in `components/overlays/listing-overlay.tsx` only carry `type`, `description`, `itemType`/nested `fields`, and `required`. There is no UI affordance for a listing author to supply one, so this is a full gap rather than a backfill problem.

Confirmed: for `POST /api/mcp/workflows/liquidation-watcher-base/call`, the required field `wallet` has no example anywhere in the live spec.

Unresolved: where the example should come from -

- an opt-in `example` property added to `SchemaField` and the listing-overlay authoring UI, so listing authors can supply one - accurate, but every existing listing needs a backfill before it shows anything, or
- a generic type/name-based placeholder synthesized automatically in `buildPathEntry` (e.g. `"0x..."` for a string field whose name looks like an address) - zero backfill, but generic and can misdescribe a field whose real shape a synthesized guess gets wrong.

I'm discussing the approach with the core team now and will come back with a verdict shortly. Nothing here is blocked on you.

Contributor guide

Open the contributing guide

Research direction

Start with app/api/openapi/route.ts and buildPathEntry, then inspect SchemaField and fieldsToJsonSchema() in components/overlays/listing-overlay.tsx. First wait for the core team's verdict on author-supplied examples versus synthesized placeholders. Done means the chosen approach produces example values for workflow request-body fields in the live OpenAPI spec, including the required wallet field.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.