Sync the OpenAPI specs in public/openapi*.json with the actual MCP tool surface defined in src/<provider>/server.ts. Diffs tools against operationIds, scaffolds new operation entries from each tool's Zod parameter schema, flags missing or stale entries, and updates descriptions that drifted. Used to keep the ChatGPT Custom Actions surface in sync with the MCP tools — these specs are how the REST clients discover what tools exist, so drift causes silent breakage downstream. Use this skill whenever the user wants to update, regenerate, sync, or audit OpenAPI specs after adding or modifying MCP tools, or invokes `/update-openapi [provider]`.
96%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
Sync public/openapi*.json with the tools actually defined in src/<provider>/server.ts. These specs are how ChatGPT Custom Actions and external REST consumers discover the tool surface; when they drift, downstream integrations silently break.
The mapping from MCP tool → OpenAPI operation is not 1:1 trivial — HTTP method and path are judgment calls. This skill diffs the two sides, scaffolds draft entries for what's missing, and surfaces what needs human review. It does not blindly regenerate the file from scratch; that would lose the manually-curated paths, request bodies, and response schemas that already work.
For the scaffold rules (HTTP method by tool name, path shape, Zod → OpenAPI translation, required fields per operation), read references/scaffold-rules.md.
[provider] — one of docs / sheets / calendar / gmail / drive / slides / clickup, or all. Default: all. Loose aliases accepted (google-sheets, google sheets → sheets).If [provider] is unrecognized, ask. Don't default to all when the user clearly meant one provider but typed a typo.
See the table in references/scaffold-rules.md for which server file maps to which OpenAPI file. Note that google-docs maps to public/openapi.json (the default name), not public/openapi-docs.json.
If the user picked all, iterate over every provider that has both a server file and an OpenAPI file. Skip providers with no OpenAPI file (e.g. Slack) and mention them in the report.
server.tsFor each target provider, read src/<provider>/server.ts and parse every addTool({ ... }) block. Collect:
name — the operationId in OpenAPI terms.description — the operation description.annotations.readOnlyHint — implies HTTP method GET.parameters — the Zod object schema.Be tolerant of formatting — multi-line description strings, nested Zod schemas, comments inside the addTool block.
Read the OpenAPI JSON and walk paths.<path>.<method> entries. Collect:
operationId — used to match against tool names.description — for drift detection.Produce three lists:
For each side, also list:
NOT_IMPLEMENTED (from e2e/tools.ts) — these probably shouldn't be in OpenAPI either; if they appear, flag.For each new tool, follow references/scaffold-rules.md to produce the OpenAPI operation:
$ref Error), 401 (unauthorized, $ref Error). Add 403/404/etc. only if the tool's failure modes warrant it.Important: the scaffold is a starting point. For non-trivial path choices (a tool that does something the existing path structure doesn't anticipate), leave the path as /api/v1/<resource>/TODO-<toolName> and flag in the report — that's the user's call.
For tools that return formatted strings (most read tools), use { "type": "string" } as the 200 response schema. For tools that return structured data the user wants typed, leave the response schema as { "type": "object", "description": "TODO: define response shape" } and flag — adding a new component to components.schemas should be deliberate.
When new operations are scaffolded, drifted descriptions are patched, or stale operations are flagged, print the diff first (or a compact summary if it's large) and ask the user to confirm before writing the file. Stale flags never trigger a write; they're surfaced for the user's judgment.
Concretely:
Provider: sheets (public/openapi-sheets.json)
New operations to add (4):
+ listSheetsTabs GET /api/v1/sheets/{spreadsheetId}/tabs
+ renameSheetsTab POST /api/v1/sheets/{spreadsheetId}/tabs/{tabId}/rename
+ ...
Drifted descriptions to patch (2):
~ readSpreadsheet
~ writeSpreadsheet
Stale operations (flagged, NOT auto-removed):
! deleteSheet — not in server.ts. Renamed to deleteSpreadsheet? Confirm.
Path TODOs (1):
? exportSheetsAsPdf — couldn't infer path; please confirm placement.
Apply these changes?Once confirmed, write the updated OpenAPI JSON. Preserve the existing key order — JSON has no semantic order, but minimizing diff noise matters for review. Use the same indentation as the existing file (most use 2 spaces).
Run jq . public/openapi-<file>.json > /dev/null (or jq empty) to confirm valid JSON. There is no schema validator wired into this repo, but if jq reports a parse error the file is unusable.
For a sanity check, also count: the number of operationId entries should equal the number of tools in the server file minus tools that are intentionally omitted (Slack-style server with no OpenAPI). Surface this count in the report.
Synced <N> OpenAPI files:
public/openapi-sheets.json
Added: <count> operations
Patched: <count> descriptions
Flagged stale: <count>
Path TODOs: <count>
public/openapi-calendar.json
...
Operations in OpenAPI vs tools in server.ts (after sync):
sheets: <opcount> / <toolcount>
calendar: <opcount> / <toolcount>
...
Manual follow-ups:
- Confirm path for <provider>.<tool> (TODO marker in the JSON)
- Decide whether to remove stale operation <provider>.<op> from OpenAPIDon't create it on the fly. New OpenAPI files are a design decision — they require server URL setup, security scheme config, and component schemas. If the user wants a new file for Slack or another provider, that's a separate ticket; surface the gap in the report and stop.
z.object({}) tool like ping). Generate an operation with an empty parameters array and a body that's null/empty.add-mcp-tool's uniqueness check, but if it shows up, flag it as a real bug, not just OpenAPI drift.update-openapi/
├── SKILL.md
└── references/
└── scaffold-rules.md ← HTTP-method table, path conventions, Zod → OpenAPI translationadd-mcp-tool is the natural upstream — it adds a tool but doesn't update OpenAPI. Run update-openapi <provider> after a session of tool additions, or wire /update-openapi into your pre-PR checklist.add-mcp-server doesn't create an OpenAPI file for new servers — see the "When the OpenAPI file is missing" note above. The user makes that call separately.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.