mcp4openapi: Skill for Claude Code

CRUD MCP Profile Builder

Build a production-ready profile in profiles/<api>/ without rediscovering repository conventions.

Load This Context First

Read only these sources first, in this order:

1. AGENTS.md (canonical rules and workflow constraints)
2. IMPLEMENTATION.md (architecture intent)
3. docs/PROFILE-GUIDE.md (profile structure and patterns)
4. docs/PROFILE-TEST-GUIDE.md (schema-driven tests)
5. A strong local reference profile:
   • profiles/youtrack/profile.json for CRUD grouping style
   • profiles/github-security/profile.json for compact two-tool pattern
6. Target spec and folder:
   • profiles/<api>/openapi.* or equivalent file present in folder

Then inspect only relevant docs for updates:

• README.md profile lists/sections
• CHANGELOG.md ([Unreleased])
• TODO.md only if you are implementing an existing backlog item

For repeatable command snippets, use references/discovery-and-validation.md.

Expected Output

Create or update these files:

1. profiles/<api>/profile.json
2. profiles/<api>/profile.test.json
3. README.md (profile list and profiles section)
4. CHANGELOG.md (single-line user-facing entry in Unreleased)

Optional:

• Fix invalid OpenAPI syntax in the bundled spec if parser/validator fails (for example invalid items shape).

Workflow

1. Inventory the target spec.
2. Build operation map from operationId + HTTP method + path.
3. Decide CRUD grouping based on available methods:
   • retrieve_content for GET-like reads
   • create_content for POST creates
   • update_content for PATCH/PUT/POST updates
   • delete_content for DELETE removes
   • If API is read-heavy, keep only meaningful groups (do not add empty tools).
4. Define action names that are explicit and stable (for example list_*, get_*, create_*, update_*, delete_*).
5. Generate parameter model from OpenAPI:
   • required: true for parameters required by all actions in a tool
   • required_for for action-specific required parameters
   • include useful optional filters
   • add parameter_aliases for common ergonomic names (owner, repo, project_id, etc.)
6. Set interceptors:
   • bearer auth with API-specific env var name (for example CODECOV_TOKEN)
   • base URL env var + sane default when known
   • retry policy aligned with existing profiles when applicable
7. Build profile.test.json with schema-driven scenarios:
   • one scenario per action minimum
   • coverage.require_all_actions: true
   • add request assertions when behavior is non-trivial (aliases, metadata params, response field forwarding, proxy download)
8. Validate and test.
9. Update docs (README.md, CHANGELOG.md).