alirezarezvani/mcp-server-builder
engineering/skills/mcp-server-builder/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add alirezarezvani/claude-skills mcp-server-builderInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jun 13, 2026, 4:22 AM26.1s9 files scanned
SKILL.md
- name:
- mcp-server-builder
- description:
- 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.
MCP Server Builder
Tier: POWERFUL · Category: Engineering · Domain: AI / API Integration
Overview
Use this skill to design and ship production-ready MCP servers from API contracts instead of hand-written one-off tool wrappers. It focuses on fast scaffolding, schema quality, validation, and safe evolution.
The workflow supports both Python and TypeScript MCP implementations and treats OpenAPI as the source of truth.
Core Capabilities
- Convert OpenAPI paths/operations into MCP tool definitions
- Generate starter server scaffolds (Python or TypeScript)
- Enforce naming, descriptions, and schema consistency
- Validate MCP tool manifests for common production failures
- Apply versioning and backward-compatibility checks
- Separate transport/runtime decisions from tool contract design
When to Use
- You need to expose an internal/external REST API to an LLM agent
- You are replacing brittle browser automation with typed tools
- You want one MCP server shared across teams and assistants
- You need repeatable quality checks before publishing MCP tools
- You want to bootstrap an MCP server from existing OpenAPI specs
Key Workflows
1. OpenAPI to MCP Scaffold
- Start from a valid OpenAPI spec.
- Generate tool manifest + starter server code.
- Review naming and auth strategy.
- Add endpoint-specific runtime logic.
python3 scripts/openapi_to_mcp.py \
--input openapi.json \
--server-name billing-mcp \
--language python \
--output-dir ./out \
--format text
Supports stdin as well:
cat openapi.json | python3 scripts/openapi_to_mcp.py --server-name billing-mcp --language typescript
2. Validate MCP Tool Definitions
Run validator before integration tests:
python3 scripts/mcp_validator.py --input out/tool_manifest.json --strict --format text
Checks include duplicate names, invalid schema shape, missing descriptions, empty required fields, and naming hygiene.
3. Runtime Selection
- Choose Python for fast iteration and data-heavy backends.
- Choose TypeScript for unified JS stacks and tighter frontend/backend contract reuse.
- Keep tool contracts stable even if transport/runtime changes.
4. Harden for Production
Key items before publishing:
- Keep secrets in env vars, not tool schemas
- Prefer outbound host allowlists over open proxies
- Use additive-only changes; never rename tool names in-place
Full hardening guidance: references/production-hardening-guide.md.
Script Interfaces
python3 scripts/openapi_to_mcp.py --help- Reads OpenAPI from stdin or
--input - Produces manifest + server scaffold
- Emits JSON summary or text report
- Reads OpenAPI from stdin or
python3 scripts/mcp_validator.py --help- Validates manifests and optional runtime config
- Returns non-zero exit in strict mode when errors exist
Reference Material
- references/production-hardening-guide.md — auth & safety design, versioning strategy, common pitfalls, best practices, architecture decisions, contract quality gates, testing strategy, deployment practices, security controls
- references/openapi-extraction-guide.md
- references/python-server-template.md
- references/typescript-server-template.md
- references/validation-checklist.md
- README.md
Related Skills
alirezarezvani/weekly-review
development
VerifiedTrustedCommunity
Use when someone wants to run a weekly review, close open loops, audit stalled projects and commitments, get their system back to trusted, restart a lapsed review habit, or says "/cs:weekly-review". Walks David Allen's three-phase loop — GET CLEAR, GET CURRENT, GET CREATIVE — with deterministic scripts that inventory open loops, gate the checklist with named gaps, and score commitment health 0-100.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/meetings
development
VerifiedTrustedCommunity
Use when someone wants to decide whether a meeting is worth calling, price a meeting in dollars, build a timeboxed agenda with desired outcomes, or turn messy meeting notes into owned action items — or says "should this be a meeting", "/cs:meeting-prep", or "/cs:meeting-actions". Runs a cost gate (ASYNC / NOT-READY / MEET), builds a decision-first agenda, and extracts an owner + due-date checklist that flags every orphan.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/fable-goal
development
VerifiedTrustedCommunity
Convert a rambling description of a desired outcome into one polished, autonomous /goal prompt ready to paste into a fresh session. Use when the user says "/fable-goal", "turn this into a goal prompt", "write me a fable prompt", "write the prompt that builds X", or rambles about something they want made and asks for the prompt that makes it happen. The output is a single copy-paste prompt, never the build itself. Do NOT use when the user wants the thing built right now in this session — only when they want the PROMPT that will make it happen in a fresh session.
22,702SKILL.mdUpdated Jul 18, 2026
alirezarezvani/deep-work
development
VerifiedTrustedCommunity
Use when someone wants to plan a deep work day, time-block their calendar or task list, budget or cut shallow work, protect focus hours, track deep-work sessions and streaks, run an end-of-day shutdown ritual, or says "/deep-work" or "/time-block". Classifies tasks deep vs shallow, builds an energy-first time-blocked schedule that refuses deep demand past the 4-hour ceiling, batches shallow work into at most two windows, and logs focus sessions against a weekly target.
22,702SKILL.mdUpdated Jul 18, 2026