Add or wire a REST data-plane endpoint (GET or POST /api/v1/*) in this repo — the curl-able passthrough surface documented in docs/REST_ENDPOINTS.md. Adds the entry to src/restCatalog.ts (the single source of truth), registers the Express handler in src/website/webServer.ts with the right service auth middleware, adds the auth-gate test, and regenerates docs/REST_ENDPOINTS.md + public/openapi.json + docs/MCP_TOOLS.md. Use whenever the user wants to add, wire, expose, or promote a REST endpoint, give an MCP tool a curl/HTTP sibling, flip a `planned` catalog entry to `live`, ship the whole REST surface for a service, or expose a write/mutation tool over HTTP POST. Also invoked automatically by `add-mcp-server` (its step 6e) to wire a newly scaffolded service's endpoints, which ship as their own pull request. Also use when invoked as `/add-rest-endpoint <mcpToolName|service> [service]`.
91%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Critical
Do not install without reviewing
The REST data plane exists so a shell-capable client can curl | jq bulk payloads without the bytes crossing the LLM context window. Endpoints are passthroughs for existing MCP tools.
Reads (GET) are the default and the well-trodden path. Writes (POST) are supported but gated: a write earns a REST sibling only when its request body is large or it belongs in a shell pipeline, and it widens what the permanent dashboard API key can mutate. The one-time type and test widening is already done (peopleforce, hubspot, redmine, sheets and calendar all have live POSTs), so a new write is steps 1–8 plus the per-endpoint rules. See Write endpoints before starting one.
Also check Four jobs before writing any code: the most common surprise is that webServer.ts already serves the route, uncatalogued, as ChatGPT Custom Actions compat.
Adding an endpoint touches six files, three of them generated. This SKILL.md is the procedure; references/route-pattern.md is the canonical handler shape; references/write-endpoints.md covers the write-specific rules.
<mcpToolName> — the MCP tool getting a REST sibling (e.g. getEmployee), or a scope phrase ("wire all the hubspot endpoints"), or a bare service slug. A scope phrase expands to every planned catalog entry for that service; a bare slug is how add-mcp-server invokes this skill and means the service's whole tool surface — every implemented read, plus every write that passes the gate. On that path expect some tools to be declined, and say which and why in the report.[service] — one of the RestService union values in src/restCatalog.ts: docs, sheets, calendar, drive, gmail, slides, clickup, slack, outline, peopleforce, hubspot. Infer from the tool's home server; ask only if genuinely ambiguous.If neither is given, ask which service.
planned → live — the catalog entry already exists, which is the normal state for a service freshly scaffolded by add-mcp-server (its step 6a writes the read entries at planned). Skip step 2 except to flip status; do steps 3–8. Check src/restCatalog.ts first — this is the most common case.webServer.ts already serves the path. The ChatGPT Custom Actions compat routes are uncatalogued and invisible in every generated doc, and they hand-roll their validation. Do steps 1–8, but keep the path, the response shape, AND the body shape (see step 1). That last one is the trap: an old route's body may be the provider's native field names while the MCP tool's parameters are a camelCase translation of them, in which case "validate with the tool's own schema" would reject every existing caller. Diff them before assuming they agree.Grep src/<provider>/server.ts for name: '<mcpToolName>'. Note three things:
readOnlyHint: true → GET, readOnlyHint: false → POST (the write path, with its extra rules), destructiveHint: true → stop and read the destructive-ops section of references/write-endpoints.md before going further. But readOnlyHint: true is not by itself a licence to use GET: if the call creates server-side work — queues a job, starts an export, sends something — it is neither safe nor idempotent, and GET is fair game for a proxy or retry middleware to repeat after a timeout. Outline's exportCollection/exportAllCollections are annotated read-only and each call queues another export; shipped as GETs, a single dropped connection would have queued a second whole-workspace export. POST them to an action path regardless of the annotation. Read the annotation as "does this mutate the user's records", not as "is this free to retry".execute. The REST handler makes the same call and returns raw upstream JSON instead of a formatted string.parameters schema. For reads this tells you the query params. For writes the tool's parameters are the source for validating req.body — that's the mechanism that stops the REST and MCP surfaces from drifting. Two caveats the ClickUp pass established:
Share the FIELDS, not the whole schema. The two surfaces compose the same fields differently — the tool takes the resource id as a parameter, the route takes it from the path — and the REST side usually adds .refine() guards the tool only states in prose. So export a plain field object and spread it (z.object({ taskId: …, ...taskUpdateFields }) in the tool, z.object(taskUpdateFields).refine(…) in the route) rather than trying to reuse one z.object.
It is only free on a NEW path. On an already-served route, check what the published spec promises first:
python3 -c "import json;d=json.load(open('public/openapi-<service>.json'));[print(m.upper(),p,list(o.get('requestBody',{}).get('content',{}).get('application/json',{}).get('schema',{}).get('properties',{}))) for p,ops in d['paths'].items() for m,o in ops.items() if m in ('post','patch','put')]"If the published body uses the provider's native names (due_date, custom_item_id, comment_text, tid) while the tool takes camelCase, the route has its own contract and reusing the tool's schema would 400 every generated client. Leave that path's body alone and put the camelCase version on a separate action path — one path, one body shape.
Check the tool is actually implemented. NOT_IMPLEMENTED in e2e/tools.ts lists tools that exist and throw — editTableCell, fixListFormatting, findElement today. An endpoint for one of those advertises a 500, so exclude it and say so in the report rather than shipping it for completeness.
grep -n "NOT_IMPLEMENTED" e2e/tools.tsAlso check what is already live before promising a count: on a mature service the reads may all be wired already, so "every tool" can turn out to be a writes-only pass (Docs: 8 of 9 reads live, the 9th unimplemented).
Then check whether the route already exists, before designing a path:
grep -nE -A1 "app\.(get|post|patch|delete)\(" src/website/webServer.ts | grep "api/v1/<service>"The -A1 is not decoration: some registrations put the path on the next line (app.post(\n '/api/v1/images', …), and a pipeline expecting app.post( and the path to share a line silently reports no route where one exists — the single failure this step exists to prevent.
A hit that is absent from restCatalog.ts is job 2 above, and it changes what you do: the ChatGPT Custom Actions compat routes have been served for a long time, clients parse their response bodies, and they typically validate with if (!field) presence checks. Keep the path and the response keys exactly as they are and change only the validation, or you break a live integration to gain a tidier URL. Three of the eight endpoints in the Sheets/Calendar write pass were already there this way.
A hit that is also in the catalog means somebody already did this — stop and re-read, rather than registering a second handler Express will never reach.
src/restCatalog.tsOne line, appended to the service's block. Field order is not stylistic — three build scripts parse this file with a regex that hardcodes it:
{ service: 'peopleforce', method: 'GET', path: '/api/v1/peopleforce/employees/{employeeId}', summary: 'Get a single PeopleForce employee', mcpToolName: 'getEmployee', openapiOperationId: 'getPeopleForceEmployee', status: 'live' },Hard rules (violations fail silently — the entry just vanishes from every generated doc):
Exact field order: service, method, path, summary, mcpToolName, openapiOperationId, status[, notes].
Single quotes, one line per entry.
No apostrophes in summary or notes — the parser matches '([^']+)' and an apostrophe truncates the field mid-string.
openapiOperationId must be globally unique (restCatalog.test.ts enforces it). Prefix the service when the bare tool name collides: getComment → getOutlineComment, listEmployees → listPeopleForceEmployees.
If public/openapi-<service>.json already describes that path + method, use ITS operationId verbatim. buildRootOpenapi.mjs only stub-fills what no per-service spec covers (if (root.paths[pathOnly]?.[method]) continue), so the per-service id wins and a different catalog id is silently never emitted — leaving the catalog and docs/REST_ENDPOINTS.md naming an operation that nothing in the published spec answers to, and a generated client calling the other name. Check before inventing one:
python3 -c "import json;d=json.load(open('public/openapi-<service>.json'));[print(m.upper(),p,o.get('operationId')) for p,ops in d['paths'].items() for m,o in ops.items()]"Observed: the catalog wanted writeSpreadsheet / appendSpreadsheetRows / createCalendarEvent while the specs publish writeRange / appendRows / createEvent. The specs won.
A new method on a path whose other verb is already in the spec needs its own id. One operationId cannot name two operations, so a POST added beside a legacy PATCH that already publishes updateEvent becomes updateCalendarEvent; a /cancel action path beside a published deleteEvent becomes cancelCalendarEvent.
path uses {braces} for params (OpenAPI style), not Express :colons. Query templates go in the path string for documentation (?q={query}); the builders strip everything after ? when emitting OpenAPI paths.
status: 'live' only once the Express route exists — planned entries are excluded from public/openapi.json and from the REST column of docs/MCP_TOOLS.md precisely so the docs never advertise a 404.
If the service is new to the union, add it to RestService, to SERVICE_SERVER_PATH in src/restCatalog.ts (a total Record<RestService, string>, so this one is a compile error rather than silent drift), to SERVICE_VALUES in src/sharedTools/listRestEndpoints.ts (a service missing there is silently rejected by the z.enum — restCatalog.test.ts guards this drift), to SERVICE_TITLE/SERVICE_ORDER in scripts/buildRestEndpointsDoc.mjs, and to SERVICES in scripts/buildMcpToolsDoc.mjs.
The first time you flip any of a service's entries to status: 'live', its MCP server must also register the two shared tools:
registerMintRestBearerForCurl(<service>Server);
registerListRestEndpoints(<service>Server);src/__tests__/sharedToolsRegistration.test.ts enforces this and will fail the moment an entry goes live without them — a live REST surface that no MCP client can mint a bearer for, or discover, forces users onto the permanent dashboard API key instead of a 5-minute one.
In src/website/webServer.ts (~line 2602):
const requireApiKey = createServiceAuth('google-docs', 'docs');
const requireClickUpApiKey = createServiceAuth('clickup', 'clickup');
const requireSlackApiKey = createServiceAuth('slack-bot', 'slack');If your service has none, add one: createServiceAuth('<mcpSlug>', '<fallbackSubstring>').
The gotcha that will bite on outline/peopleforce/hubspot: createServiceAuth builds the session with a provider switch. It handles clickup, slack-bot, slack, outline explicitly and sends everything else to createUserSessionFromConnection, the Google OAuth path. A HubSpot or PeopleForce connection routed there yields a session with no provider token, and the handler fails confusingly at call time rather than at auth time. createHubSpotSession and createPeopleForceSession already exist in src/userSession.ts — add the matching else if (connection.provider === '<provider>') branch before wiring the first route for that service.
src/website/webServer.tsRead references/route-pattern.md first. Then generate from:
assets/templates/google-route.ts.tmpl — GET, googleapis clients off req.userSession.assets/templates/third-party-route.ts.tmpl — GET, a new XClient(token) imported dynamically.assets/templates/write-route.ts.tmpl — POST. Also read references/write-endpoints.md.First, check whether the provider's server module is safe to import. If src/<provider>/server.ts is the application entry point, webServer.ts cannot import it in either direction — not statically, and not with a dynamic await import() inside a handler, because in web-only mode that boots an entire MCP server to validate a request body:
grep -n "createWebApp\|startServer()" src/<provider>/server.tsA hit means the schemas and ops go in their own modules (writeSchemas.ts, writeOps.ts) that both surfaces import. src/google-docs/server.ts is the one today. When in doubt do it anyway — separate modules are never wrong here.
If the connector has per-connection access rules, THIS PLANE MUST ENFORCE THEM. Slack, Browserbase and Pinecone all store rules under providerTokens.accessRules and assert them inside the MCP tool bodies. A REST handler that calls the upstream client directly bypasses every one of them — which makes the rules a property of the transport rather than of the connection, so swapping one client for another becomes a way to read what the dashboard says is denied. It is not a theoretical gap: this plane accepts the permanent dashboard API key, so a connection the user set read-only has to refuse a curl exactly as it refuses a tool call.
Concretely, reuse the connector's own pure assert* functions rather than re-deriving the policy, and carry the rules into the handler the same way the MCP server does (re-read per call — a session-cached copy keeps serving rules the user has already changed). Two details worth copying from src/pinecone/restOps.ts:
sendUpstreamError.Add a route-level test that a restricted connection gets 403 where an unrestricted one gets 200. The auth-gate array in step 5 cannot show this: it only proves the endpoint is gated at all.
Placement rules:
Group with the service's other routes; don't append at the bottom of a 5000-line file.
Static paths before parameterized ones. /api/v1/docs/recent is registered before /api/v1/docs/:documentId or Express matches recent as a documentId. Same for any /search, /trash, /archived sibling.
Express uses :param; the catalog uses {param}. Keep the param names identical so the docs and the code read the same.
Never infer a provider's identifier convention from URL mechanics — read it from the spec. This one is here because it shipped broken. The Pinecone pass reasoned that encodeURIComponent('') yields '', so /records/namespaces//search must be "the correct address for the default namespace", and built a chain of decisions on it: the namespace moved into the body, a sentinel was rejected on principle, the rule normaliser was written to preserve "", and every tool description told callers to pass it. All of it was wrong. Pinecone requires a namespace to be 1-512 characters and refuses "" with a 400 naming its reserved __default__ — which describe_index_stats had been reporting all along, so the connector's own read path was already showing the right answer while its write path documented the wrong one. Three operations were unusable for anyone who followed the docs.
Two things to take from it. The spec answers this and inference does not: grep the provider's OpenAPI for the parameter's constraints (minLength, a reserved-name note) before designing around a value you have not sent. And when a conversion like this turns out to be needed, put it at the single wire boundary — one wireNamespace() in the client, not at each call site — so the MCP tools, the REST routes and whatever is added next cannot disagree. Keep accepting the old spelling and translate it, rather than refusing the callers who followed your own documentation.
In src/__tests__/restRoutes.auth.test.ts, push the concrete path (placeholder ids, plus any required query string) into NEW_REST_ENDPOINTS:
'/api/v1/peopleforce/employees/emp-123',That array drives a cheap no-mocking test asserting 401 for a missing header and 401 for an unknown bearer. It is the only thing between a typo'd route path and a silent 404 in production, so never skip it.
The loop is GET-only (request(app).get(path)). A POST endpoint needs the sibling array and loop described in references/write-endpoints.md — adding a POST path to NEW_REST_ENDPOINTS tests a route that doesn't exist and passes for the wrong reason (Express 404s unmatched methods, and the test only asserts 401… which it won't get, so it fails confusingly).
All three are marked "Do not edit by hand" and all three read src/restCatalog.ts:
node scripts/buildRestEndpointsDoc.mjs # docs/REST_ENDPOINTS.md
node scripts/buildRootOpenapi.mjs # public/openapi.json (skips `planned`)
node scripts/buildMcpToolsDoc.mjs # docs/MCP_TOOLS.md — its REST columnNo npm scripts wrap these; run them directly. buildRootOpenapi.mjs merges public/openapi-*.json and then stub-fills any live catalog entry no per-service spec covers, so a new endpoint gets a usable (if schema-less) OpenAPI entry for free. The stub has no requestBody — for POST endpoints it advertises a body-less operation, which is worse than useless to a client. Write endpoints should get a real per-service spec entry via /update-openapi <provider> in the same change, not later. Invoke that skill rather than hand-rolling a generator — it already does the Zod → OpenAPI translation (references/scaffold-rules.md), and a throwaway script reproduces that work in a form nobody maintains. For a brand-new service with no public/openapi-<slug>.json yet, it is still the right tool: there is nothing to diff against, so it scaffolds the file.
npm run typecheck
npm testThen eyeball the diff of docs/REST_ENDPOINTS.md — if your endpoint isn't in it, the catalog line broke the parser regex (step 2), which is the single most common failure here.
Then measure coverage of the new code, locally. CI does not check coverage, so nothing stops a PR that leaves its new lines untested; keep them at 80% or more, lines and branches together. A write-endpoint change is the hard case: the handler's success path cannot be covered by any test in this repo (see Coverage), so the op you extracted has to carry the ratio. A per-file line reading overstates it, because it ignores branches and counts old lines too; the recipe in that section measures only what the branch added.
Added <mcpToolName> → <METHOD> <path>
src/restCatalog.ts entry (status: live)
src/website/webServer.ts handler + <requireXApiKey>
src/__tests__/restRoutes.auth.test.ts auth-gate path
docs/REST_ENDPOINTS.md regenerated (N endpoints)
public/openapi.json regenerated
docs/MCP_TOOLS.md regenerated
src/<provider>/CLAUDE.md REST-plane note (if any)
Typecheck: <pass | N errors>
Tests: <pass | N failing>
New-code coverage: <N>% ← aim for 80%+, lines + branches (POST changes only)
Declined (if any):
<toolName> ← why: no large body, no pipeline / destructive, no sign-off
Next:
/update-openapi <provider> ← required for POST (the stub has no requestBody)
open a SEPARATE pull request for this pass ← never folded into a scaffold or feature PRRecord what the next reader cannot derive from the code — a forced verb or path choice, a destructive endpoint exposed with sign-off, a legacy uncatalogued route kept on its old body contract, an upstream status remapped (e.g. 401 → 502), a write deliberately left MCP-only. Add it as one terse bullet under a ### REST plane heading in src/<provider>/CLAUDE.md, never in the root CLAUDE.md, which loads into every session. A behaviour of webServer.ts itself (body parsing, error mapping shared by all routes) goes in src/website/CLAUDE.md; only a rule every service's REST routes must follow goes in the root's "Cross-cutting rules". Endpoint counts and the investigation story stay out — docs/REST_ENDPOINTS.md and the PR carry those.
Name the declined tools explicitly. Silence reads as "every tool is covered", and the gap is then found by whoever reaches for the missing endpoint rather than by the person who could have overruled the gate.
Writes are legitimate but they are not the reason the data plane exists. The read rationale — keep large responses off the LLM context — doesn't transfer, because a write's response is small. So apply the gate before writing any code.
Ship it when at least one holds:
curl … | jq … | curl -X POST … where forcing a hop through the LLM to perform the write is pure overhead.Push back when neither holds. A one-field update is cheaper and safer as an MCP tool call: Zod validation, the destructiveHint annotation the e2e readonly connector keys off, and no new auth surface. Say so plainly rather than mirroring all 40 write tools by reflex.
Worked example, from the Sheets and Calendar pass — of eleven write tools, eight shipped and three did not:
| Tool | Verdict |
|---|---|
writeSpreadsheet, appendSpreadsheetRows, batchUpdateSpreadsheet, createSpreadsheet | Ship — values / operations / initialData are the large body the plane exists for |
createEvent, updateEvent | Ship — bulk event creation from an external feed is a shell pipeline |
clearSpreadsheetRange, deleteEvent | Ship, with sign-off — destructiveHint, so they needed an explicit decision first |
addSpreadsheetSheet, updateCellByFieldName | Decline — one field each, no body, no pipeline. They stay MCP-only |
When a destructive tool is in scope, ask in one question that lists the candidates and says what the sign-off buys the caller (no confirmation affordance behind a curl, and the permanent API key is in scope), then record the answer in the catalog notes. Note the question is broader than the destructiveHint flag: batchUpdateSpreadsheet carries no such annotation, yet its operation list reaches deleteSheet, which destroys a tab and every value on it. Read what the schema can express, not just the annotation.
These four were needed before the repo's first write endpoint and are all in place now; the list stays so a reviewer can confirm nothing regressed:
src/restCatalog.ts — the interface reads method: 'GET' | 'POST'; and the header comment describes the gate rather than claiming writes stay MCP-only.src/__tests__/restCatalog.test.ts — asserts the method is one of ['GET', 'POST'] rather than exactly GET. The assertion must stay: it is what keeps PATCH/DELETE out until someone decides deliberately.src/__tests__/restRoutes.auth.test.ts — has the NEW_REST_WRITE_ENDPOINTS array and its POST loop (shape in references/write-endpoints.md). Add your path to that array, not the GET one.src/sharedTools/listRestEndpoints.ts — the tool description covers both directions ("GET fetches large responses straight to disk, and POST sends a large request body"), not the read-only framing it started with.The three build scripts need no change — their regexes capture method generically and buildRootOpenapi.mjs already lowercases it into the OpenAPI object.
Scope stays 'GET' | 'POST'. PATCH/DELETE are a separate decision; the legacy PATCH/DELETE routes in webServer.ts are ChatGPT Custom Actions compat and are not catalogued.
Full detail in references/write-endpoints.md. The load-bearing ones:
req.body with the MCP tool's own Zod schema via safeParse, returning 400 with the flattened issues. The legacy POST routes hand-roll if (!summary) … checks — do not copy that; it's the drift the schema reuse exists to prevent.destructiveHint: true tool without explicit user sign-off in the conversation, recorded in the catalog notes.createServiceAuth accepts the permanent dashboard API key alongside the 5-minute bearer. A key that could only read yesterday can mutate once you ship a write endpoint. State that consequence when proposing the first one.references/write-endpoints.md — do this before the endpoint exists, not after review finds it.For "wire the hubspot endpoints": step 3 once (middleware + session branch — the expensive, easy-to-miss part), then step 4 once as a table (below), step 5 one line per endpoint, then steps 6–7 once. Flip each status to live only as its route lands, so a partial batch never advertises endpoints that 404.
Prefer wiring a whole service in one pass — the session-branch work dominates, and the auth test grows by one line per route.
A brand-new service, chained from add-mcp-server, is the batch case by default. It arrives with read entries already written at planned (that skill's step 6a), so it is job 1 for the reads and job 3/4 for anything else. Two extras on that path:
registerMintRestBearerForCurl / registerListRestEndpoints, so step 2's registration requirement always applies — without them the service's first live entry fails sharedToolsRegistration.test.ts.public/openapi-<slug>.json yet, so every POST would get only the body-less stub. Write the per-service spec in the same change (see step 6), and add the file to SERVICE_PREFIX in scripts/buildRootOpenapi.mjs or the merge step skips it with a warning.Ship the result as its own PR — see One pass, one PR.
Hand-writing N handlers that differ only in schema, op, status code and response shape is the wrong shape: nineteen Docs write handlers came out 23% duplicated (88 of 384 new lines), nineteen copies of the same catch block.
Write it as a table of route descriptors plus one generic handler:
type Ops = typeof import('../<provider>/writeOps.js');
type BodySchema = { safeParse(v: unknown): { success: boolean; data?: any; error?: any } };
interface WriteRoute {
path: string; // Express path; array order IS registration order
status?: 200 | 201; // 201 where a resource is created
notFound: string;
fallback: string;
schema?: (m: Ops) => BodySchema; // omit for a body-less route
run: (m: Ops, client: Client, args: any, p: Record<string, string>) => Promise<unknown>;
}
for (const route of WRITE_ROUTES) {
app.post(route.path, requireApiKey, async (req: ApiAuthenticatedRequest, res) => {
const ops = await import('../<provider>/writeOps.js'); // once, not per row
/* one handler: safeParse 400, route.run(ops, …), status, error branch */
});
}Inject the ops module; do not give each row its own load: async () => { const m = await import(…); … }. That wrapper is 4 lines of identical ceremony per route — 24 copies were 7.5% of webServer.ts's new lines, and importing the module once and passing it in removed 85 lines. Type safety is unchanged: typeof import(...) still makes a renamed export a compile error, and the per-row as string casts on path params disappear with it.
Three things get better, not just the duplication number:
webServer's new lines fell from 374 to 283 with 86% of them covered.{...req.body, ...req.params}), the safeParse 400, the UserError-versus-upstream-status branch. Nineteen copies of a catch block is nineteen places a later fix can fail to be applied.Static paths still have to come first — put them at the top of the array, since array order is registration order.
A REST pass ships as its own pull request, never folded into a larger change. That applies whether this skill was invoked directly or chained from add-mcp-server step 6e.
The reason is what the diff contains. A REST pass is where two decisions live that a reviewer must actually see:
createServiceAuth accepts the permanent dashboard API key, so every write endpoint enlarges what a long-lived credential can mutate.notes.Both get rubber-stamped when they arrive inside a 10k-line scaffold. Separately, the generated artifacts (public/openapi.json, the two docs/*.md) are large and noisy, which is another reason not to mix them with hand-written code a reviewer needs to read closely.
Practicalities, in the order they bite:
When chained from a scaffold, branch off the scaffold's branch, not main. The routes import the provider's server module, so main cannot typecheck them until the scaffold lands. The REST PR is therefore stacked — rebase or retarget it onto main after the scaffold merges.
After any merge, verify nothing was stranded. A PR that merges at an older commit silently drops whatever was pushed afterwards, and the branch still looks merged. Check each commit you expected to ship:
git fetch origin
for c in <sha> <sha>; do git merge-base --is-ancestor $c origin/main && echo "$c in" || echo "$c NOT in"; doneThis is not hypothetical: a pass ended with a data-loss fix and a skill update both pushed after the merge point, and both were left behind on a branch GitHub reported as merged.
Keep a follow-up fix in its own PR too when the original has already merged — especially a correctness fix, which should not wait on a docs review.
npm test passes, docs/REST_ENDPOINTS.md diff is empty. Cause: reordered fields, double quotes, a line break, or an apostrophe in summary.openapiOperationId — restCatalog.test.ts fails loudly. Prefix with the service.status: 'live' with no route — the docs promise an endpoint that 404s. Only flip after the handler exists./docs/recent 404s or returns garbage because :documentId matched first. Order the app.get calls, not the catalog rows.requestBody and can't call it. Chain /update-openapi.openapiOperationId differs from the per-service spec's id for the same path + method — no test catches it; the catalog simply names an operation the published spec does not have. Check the spec (step 2).express.json({ limit }) next to the handler — never runs, and the endpoint 413s at 100 kb anyway. The limit belongs in REST_LARGE_BODY_PREFIXES; see references/write-endpoints.md.UserError that drops err.code, which is what sendUpstreamError reads. Check before reusing a helper.UserError mapped straight to 400 — those helpers raise UserError for the provider's own 404s too, so a missing record gets reported as "fix your request". Branch on whether a numeric status survived.NOT_IMPLEMENTED in e2e/tools.ts (step 1).oauthServer.ts's getRedis() leaves an ioredis client retrying, so auth/exchangeAuthCode and auth/oauthProxy print ok for every assertion and then hold the event loop open — node --test waits on them indefinitely. Two things disguise it: stdout is block-buffered when redirected, so a dead run sits at a plausible ~67 lines and looks like slow progress; and the giveaway is the parent at 0% CPU with no child workers. Before suspecting your change, reproduce on unmodified main (git checkout --detach origin/main) — if it reproduces there, it is the environment, not the diff. To get a verdict anyway, run each file separately with a hard timeout and treat a not ok line as the only failure signal.data/*.json grows without bound and widens the corruption race. Every run appends to data/mcp-connections.json and nothing prunes it; at 1340 entries / 652 KB, ~120 concurrent test processes read-modify-writing it reliably interleave into Unexpected non-whitespace character after JSON, or hang. It is gitignored scratch — truncate to [] rather than debugging a handler.add-rest-endpoint/
├── SKILL.md
├── references/
│ ├── route-pattern.md ← canonical Express handler shape + helpers
│ └── write-endpoints.md ← POST rules: Zod body validation, body-size prefixes,
│ op extraction, upstream status, coverage
└── assets/
├── scripts/
│ └── new-code-coverage.py ← coverage of the lines this branch added (lines + branches)
└── templates/
├── google-route.ts.tmpl
├── third-party-route.ts.tmpl
└── write-route.ts.tmpladd-mcp-server hard-chains into this skill at its step 6e, with the new service's slug as the scope phrase, right after it writes the catalog entries at planned. So the common way this skill runs is not one tool at a time but a whole new service at once — see Batch mode, and note that the scaffold templates do not include registerMintRestBearerForCurl / registerListRestEndpoints, so step 2's registration requirement always applies on that path. That chain's output belongs in its own PR, separate from the scaffold — see One pass, one PR.add-mcp-tool creates the MCP tool — the prerequisite for an endpoint here. Its step 9 offers /update-openapi but not this skill, because a single new tool rarely needs a REST sibling; only bulk reads and large-body writes do. Whole-service coverage arrives via add-mcp-server instead.update-openapi upgrades the auto-generated stub into a spec with real request/response schemas. Optional for GET, required for POST.add-e2e-test covers MCP tools through a live client, not REST routes. The REST equivalent is the auth-gate array in step 5.boarlabsxyz/awesome-mcp
85cee7a
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.