novahiz 0.1.0

package/bundled-skills/mcp-server-builder/SKILL.md

@@ -0,0 +1,100 @@
+---
+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
+
+1. Start from a valid OpenAPI spec.
+2. Generate tool manifest + starter server code.
+3. Review naming and auth strategy.
+4. Add endpoint-specific runtime logic.
+
+```bash
+python3 scripts/openapi_to_mcp.py \
+  --input openapi.json \
+  --server-name billing-mcp \
+  --language python \
+  --output-dir ./out \
+  --format text
+```
+
+Supports stdin as well:
+
+```bash
+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:
+
+```bash
+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](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
+- `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](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/openapi-extraction-guide.md)
+- [references/python-server-template.md](references/python-server-template.md)
+- [references/typescript-server-template.md](references/typescript-server-template.md)
+- [references/validation-checklist.md](references/validation-checklist.md)
+- [README.md](README.md)

package/bundled-skills/mcp-server-builder/references/openapi-extraction-guide.md

@@ -0,0 +1,34 @@
+# 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).

package/bundled-skills/mcp-server-builder/references/production-hardening-guide.md

@@ -0,0 +1,78 @@
+# Production Hardening Guide — Safety, Versioning, Quality Gates
+
+The advisory layer behind the mcp-server-builder workflows: read this when
+hardening a scaffolded server for production, designing auth, planning
+contract evolution, or reviewing a manifest before publishing.
+
+## Auth & Safety Design
+
+- Keep secrets in env, not in tool schemas.
+- Prefer explicit allowlists for outbound hosts.
+- Return structured errors (`code`, `message`, `details`) for agent recovery.
+- Avoid destructive operations without explicit confirmation inputs.
+
+## Versioning Strategy
+
+- Additive fields only for non-breaking updates.
+- Never rename tool names in-place.
+- Introduce new tool IDs for breaking behavior changes.
+- Maintain changelog of tool contracts per release.
+
+## Common Pitfalls
+
+1. Tool names derived directly from raw paths (`get__v1__users___id`)
+2. Missing operation descriptions (agents choose tools poorly)
+3. Ambiguous parameter schemas with no required fields
+4. Mixing transport errors and domain errors in one opaque message
+5. Building tool contracts that expose secret values
+6. Breaking clients by changing schema keys without versioning
+
+## Best Practices
+
+1. Use `operationId` as canonical tool name when available.
+2. Keep one task intent per tool; avoid mega-tools.
+3. Add concise descriptions with action verbs.
+4. Validate contracts in CI using strict mode.
+5. Keep generated scaffold committed, then customize incrementally.
+6. Pair contract changes with changelog entries.
+
+## Architecture Decisions
+
+Choose the server approach per constraint:
+
+- Python runtime: faster iteration, data pipelines, backend-heavy teams
+- TypeScript runtime: shared types with JS stack, frontend-heavy teams
+- Single MCP server: easiest operations, broader blast radius
+- Split domain servers: cleaner ownership and safer change boundaries
+
+## Contract Quality Gates
+
+Before publishing a manifest:
+
+1. Every tool has clear verb-first name.
+2. Every tool description explains intent and expected result.
+3. Every required field is explicitly typed.
+4. Destructive actions include confirmation parameters.
+5. Error payload format is consistent across all tools.
+6. Validator returns zero errors in strict mode.
+
+## Testing Strategy
+
+- Unit: validate transformation from OpenAPI operation to MCP tool schema.
+- Contract: snapshot `tool_manifest.json` and review diffs in PR.
+- Integration: call generated tool handlers against staging API.
+- Resilience: simulate 4xx/5xx upstream errors and verify structured responses.
+
+## Deployment Practices
+
+- Pin MCP runtime dependencies per environment.
+- Roll out server updates behind versioned endpoint/process.
+- Keep backward compatibility for one release window minimum.
+- Add changelog notes for new/removed/changed tool contracts.
+
+## Security Controls
+
+- Keep outbound host allowlist explicit.
+- Do not proxy arbitrary URLs from user-provided input.
+- Redact secrets and auth headers from logs.
+- Rate-limit high-cost tools and add request timeouts.

package/bundled-skills/mcp-server-builder/references/python-server-template.md

@@ -0,0 +1,22 @@
+# 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()
+```

package/bundled-skills/mcp-server-builder/references/typescript-server-template.md

@@ -0,0 +1,19 @@
+# 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();
+```

package/bundled-skills/mcp-server-builder/references/validation-checklist.md

@@ -0,0 +1,30 @@
+# 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 rename in-place)
+- [ ] Additive-only changes for non-breaking updates
+- [ ] Contract changelog is maintained per release
+- [ ] Deprecated tools include sunset timeline in description
+
+## Runtime & Error Handling
+- [ ] Error responses use consistent structure (`code`, `message`, `details`)
+- [ ] Timeout and rate-limit behaviors are documented
+- [ ] Large response payloads are paginated or truncated

package/bundled-skills/mcp-server-builder/scripts/mcp_validator.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""Validate MCP tool manifest files for common contract issues.
+
+Input sources:
+- --input <manifest.json>
+- stdin JSON
+
+Validation domains:
+- structural correctness
+- naming hygiene
+- schema consistency
+- descriptive completeness
+"""
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+TOOL_NAME_RE = re.compile(r"^[a-z0-9_]{3,64}$")
+
+
+class CLIError(Exception):
+    """Raised for expected CLI failures."""
+
+
+@dataclass
+class ValidationResult:
+    errors: List[str]
+    warnings: List[str]
+    tool_count: int
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Validate MCP tool definitions.")
+    parser.add_argument("--input", help="Path to manifest JSON file. If omitted, reads from stdin.")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when errors are found.")
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Output format.")
+    return parser.parse_args()
+
+
+def load_manifest(input_path: Optional[str]) -> Dict[str, Any]:
+    if input_path:
+        try:
+            data = Path(input_path).read_text(encoding="utf-8")
+        except Exception as exc:
+            raise CLIError(f"Failed reading --input: {exc}") from exc
+    else:
+        if sys.stdin.isatty():
+            raise CLIError("No input provided. Use --input or pipe manifest JSON via stdin.")
+        data = sys.stdin.read().strip()
+        if not data:
+            raise CLIError("Empty stdin.")
+
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise CLIError(f"Invalid JSON input: {exc}") from exc
+
+    if not isinstance(payload, dict):
+        raise CLIError("Manifest root must be a JSON object.")
+    return payload
+
+
+def validate_schema(tool_name: str, schema: Dict[str, Any]) -> Tuple[List[str], List[str]]:
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    if schema.get("type") != "object":
+        errors.append(f"{tool_name}: inputSchema.type must be 'object'.")
+
+    props = schema.get("properties", {})
+    if not isinstance(props, dict):
+        errors.append(f"{tool_name}: inputSchema.properties must be an object.")
+        props = {}
+
+    required = schema.get("required", [])
+    if not isinstance(required, list):
+        errors.append(f"{tool_name}: inputSchema.required must be an array.")
+        required = []
+
+    prop_keys = set(props.keys())
+    for req in required:
+        if req not in prop_keys:
+            errors.append(f"{tool_name}: required field '{req}' is not defined in properties.")
+
+    if not props:
+        warnings.append(f"{tool_name}: no input properties declared.")
+
+    for pname, pdef in props.items():
+        if not isinstance(pdef, dict):
+            errors.append(f"{tool_name}: property '{pname}' must be an object.")
+            continue
+        ptype = pdef.get("type")
+        if not ptype:
+            warnings.append(f"{tool_name}: property '{pname}' has no explicit type.")
+
+    return errors, warnings
+
+
+def validate_manifest(payload: Dict[str, Any]) -> ValidationResult:
+    errors: List[str] = []
+    warnings: List[str] = []
+
+    tools = payload.get("tools")
+    if not isinstance(tools, list):
+        raise CLIError("Manifest must include a 'tools' array.")
+
+    seen_names = set()
+    for idx, tool in enumerate(tools):
+        if not isinstance(tool, dict):
+            errors.append(f"tool[{idx}] is not an object.")
+            continue
+
+        name = str(tool.get("name", "")).strip()
+        desc = str(tool.get("description", "")).strip()
+        schema = tool.get("inputSchema")
+
+        if not name:
+            errors.append(f"tool[{idx}] missing name.")
+            continue
+
+        if name in seen_names:
+            errors.append(f"duplicate tool name: {name}")
+        seen_names.add(name)
+
+        if not TOOL_NAME_RE.match(name):
+            warnings.append(
+                f"{name}: non-standard naming; prefer lowercase snake_case (3-64 chars, [a-z0-9_])."
+            )
+
+        if len(desc) < 10:
+            warnings.append(f"{name}: description too short; provide actionable purpose.")
+
+        if not isinstance(schema, dict):
+            errors.append(f"{name}: missing or invalid inputSchema object.")
+            continue
+
+        schema_errors, schema_warnings = validate_schema(name, schema)
+        errors.extend(schema_errors)
+        warnings.extend(schema_warnings)
+
+    return ValidationResult(errors=errors, warnings=warnings, tool_count=len(tools))
+
+
+def to_text(result: ValidationResult) -> str:
+    lines = [
+        "MCP manifest validation",
+        f"- tools: {result.tool_count}",
+        f"- errors: {len(result.errors)}",
+        f"- warnings: {len(result.warnings)}",
+    ]
+    if result.errors:
+        lines.append("Errors:")
+        lines.extend([f"- {item}" for item in result.errors])
+    if result.warnings:
+        lines.append("Warnings:")
+        lines.extend([f"- {item}" for item in result.warnings])
+    return "\n".join(lines)
+
+
+def main() -> int:
+    args = parse_args()
+    payload = load_manifest(args.input)
+    result = validate_manifest(payload)
+
+    if args.format == "json":
+        print(json.dumps(asdict(result), indent=2))
+    else:
+        print(to_text(result))
+
+    if args.strict and result.errors:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except CLIError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(2)