mcp-server-builder

Design and ship production-ready MCP (Model Context Protocol) servers from OpenAPI contracts instead of hand-written tool wrappers. Python and TypeScript support, schema validation, safe evolution. Use when exposing an existing API as an MCP server, building tool integrations for Claude or Codex or Cursor, or scaffolding an MCP project from scratch.

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is actionable and well-organized with real bundle files backing its references, but minor conciseness padding, a missing inline validation feedback loop, and one broken link (README.md) hold it just below the top anchor.

Suggestions

Remove the Overview's restatement of the frontmatter description; jump straight to capabilities or workflow to save tokens.

Fold an explicit validate step into the OpenAPI-to-MCP workflow (e.g. "5. Run mcp_validator.py --strict; if errors, fix the manifest and re-run") so the feedback loop is inline rather than a separate section.

Either create the referenced README.md or drop the [README.md](README.md) link to avoid a dead reference.

Dimension	Reasoning	Score
Conciseness	Mostly lean with concrete commands and lists, but the Overview repeats the frontmatter description ("design and ship production-ready MCP servers from API contracts instead of hand-written one-off tool wrappers") and "It focuses on..." could be trimmed.	4 / 5
Actionability	Fully executable copy-paste bash commands with all flags ("--input openapi.json --server-name billing-mcp --language python --output-dir ./out --format text"), a stdin variant, the validator invocation, and --help pointers covering the common cases.	5 / 5
Workflow Clarity	Four numbered workflows with clear sequencing and a dedicated validation step (mcp_validator.py --strict, non-zero exit on error); however the main scaffold workflow lacks an explicit validate→fix→retry feedback loop and validation is separated from generation rather than inline.	4 / 5
Progressive Disclosure	Well-structured overview with one-level-deep, clearly signaled reference links (all five references/*.md files verified to exist); docked one point because the referenced README.md does not exist and the Reference Material list is a flat dump.	4 / 5
	Total	17 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is concrete, triggers naturally, and explicitly pairs what-it-does with when-to-use guidance. It is concise and free of vague fluff or over-claims.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "Design and ship production-ready MCP servers from OpenAPI contracts", "schema validation", "safe evolution", plus Python/TypeScript support — giving comprehensive coverage rather than a single generic verb.	5 / 5
Completeness	Explicitly answers both what ("Design and ship production-ready MCP servers...") and when via a concrete "Use when..." clause with three trigger scenarios.	5 / 5
Trigger Term Quality	Natural user phrases are present with synonyms across LLM clients — "exposing an existing API as an MCP server", "building tool integrations for Claude or Codex or Cursor", "scaffolding an MCP project from scratch".	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (OpenAPI → MCP server generation) with distinct triggers and minimal overlap with adjacent skills.	5 / 5
	Total	20 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: alirezarezvani/claude-skills
Path: engineering/skills/mcp-server-builder/SKILL.md
Commit: 19392f7

Reviewed: ~3 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

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.