Mcp Server Builder

# MCP Server Builder

Generate and validate MCP servers from OpenAPI contracts with production-focused tooling. This skill helps teams bootstrap fast and enforce schema quality before shipping.

## Quick Start

```bash
# Generate scaffold from OpenAPI
python3 scripts/openapi_to_mcp.py \
  --input openapi.json \
  --server-name my-mcp \
  --language python \
  --output-dir ./generated \
  --format text

# Validate generated manifest
python3 scripts/mcp_validator.py --input generated/tool_manifest.json --strict --format text
```

## Included Tools

- `scripts/openapi_to_mcp.py`: OpenAPI -> `tool_manifest.json` + starter server scaffold
- `scripts/mcp_validator.py`: structural and quality validation for MCP tool definitions

## References

- `references/openapi-extraction-guide.md`
- `references/python-server-template.md`
- `references/typescript-server-template.md`
- `references/validation-checklist.md`

## Installation

### Claude Code

```bash
cp -R engineering/mcp-server-builder ~/.claude/skills/mcp-server-builder
```

### OpenAI Codex

```bash
cp -R engineering/mcp-server-builder ~/.codex/skills/mcp-server-builder
```

### OpenClaw

```bash
cp -R engineering/mcp-server-builder ~/.openclaw/skills/mcp-server-builder
```


# OpenAPI Extraction Guide

## Goal

Turn stable API operations into stable MCP tools with clear names and reliable schemas.

## Extraction Rules

1. Prefer `operationId` as tool name.
2. Fallback naming: `<method>_<path>` sanitized to snake_case.
3. Pull `summary` for tool description; fallback to `description`.
4. Merge path/query parameters into `inputSchema.properties`.
5. Merge `application/json` request-body object properties when available.
6. Preserve required fields from both parameters and request body.

## Naming Guidance

Good names:

- `list_customers`
- `create_invoice`
- `archive_project`

Avoid:

- `tool1`
- `run`
- `get__v1__customer___id`

## Schema Guidance

- `inputSchema.type` must be `object`.
- Every `required` key must exist in `properties`.
- Include concise descriptions on high-risk fields (IDs, dates, money, destructive flags).


# Python MCP Server Template

```python
from fastmcp import FastMCP
import httpx
import os

mcp = FastMCP(name="my-server")
API_BASE = os.environ["API_BASE"]
API_TOKEN = os.environ["API_TOKEN"]

@mcp.tool()
def list_items(input: dict) -> dict:
    with httpx.Client(base_url=API_BASE, headers={"Authorization": f"Bearer {API_TOKEN}"}) as client:
        resp = client.get("/items", params=input)
        if resp.status_code >= 400:
            return {"error": {"code": "upstream_error", "message": "List failed", "details": resp.text}}
        return resp.json()

if __name__ == "__main__":
    mcp.run()
```


# TypeScript MCP Server Template

```ts
import { FastMCP } from "fastmcp";

const server = new FastMCP({ name: "my-server" });

server.tool(
  "list_items",
  "List items from upstream service",
  async (input) => {
    return {
      content: [{ type: "text", text: JSON.stringify({ status: "todo", input }) }],
    };
  }
);

server.run();
```


# MCP Validation Checklist

## Structural Integrity
- [ ] Tool names are unique across the manifest
- [ ] Tool names use lowercase snake_case (3-64 chars, `[a-z0-9_]`)
- [ ] `inputSchema.type` is always `"object"`
- [ ] Every `required` field exists in `properties`
- [ ] No empty `properties` objects (warn if inputs truly optional)

## Descriptive Quality
- [ ] All tools include actionable descriptions (≥10 chars)
- [ ] Descriptions start with a verb ("Create…", "Retrieve…", "Delete…")
- [ ] Parameter descriptions explain expected values, not just types

## Security & Safety
- [ ] Auth tokens and secrets are NOT exposed in tool schemas
- [ ] Destructive tools require explicit confirmation input parameters
- [ ] No tool accepts arbitrary URLs or file paths without validation
- [ ] Outbound host allowlists are explicit where applicable

## Versioning & Compatibility
- [ ] Breaking tool changes use new tool IDs (never