# Spec Workbench
> AI-first OpenAPI / MCP / JSON Schema / AsyncAPI workbench

## Overview
Spec Workbench is a developer tool for working with API specifications. It helps teams fight spec drift by providing validation, repair, diffing, and code generation capabilities.

## Core Features

### Paste & Parse
- Paste any OpenAPI 3.x, AsyncAPI 2.x, JSON Schema, or MCP manifest
- Auto-detect spec type and version
- Parse YAML or JSON formats

### Validate & Repair
- Comprehensive validation against official schemas
- Semantic validation (e.g., referenced schemas exist)
- Automatic repair suggestions for common issues
- One-click repair application

### Diff Versions
- Compare two spec versions side-by-side
- Detect breaking changes vs non-breaking changes
- Highlight added, removed, and modified endpoints/tools
- Generate diff reports

### Generate MCP Servers
Full PlatPhorm-native MCP server generation including:
- Stdio and HTTP transports
- Tool, resource, and prompt handlers
- Capability negotiation
- Structured tracing and observability
- Neon database persistence
- Registry integration with mcp.platphormnews.com

### Generate Clients
- TypeScript SDK with full types
- Curl examples for every endpoint/tool
- Test suites (Vitest, Jest)
- Action manifests (OpenAI, Anthropic, LangChain)

### Explain for Agents
"Explain this API like I'm wiring it into an agent" - generates LLM-friendly documentation of capabilities.

## API Endpoints

### GET /api/health
Health check endpoint returning service status, database connectivity, and latency metrics.

### GET /api/docs
OpenAPI 3.1 documentation for the Spec Workbench API in JSON format.

### GET /status
Real-time system health dashboard showing all service components and network connectivity.

### GET /docs
Interactive API documentation with code examples in cURL, JavaScript, and Python.

### POST /api/v1/specs
Parse and validate a spec.
- Body: { "content": "spec content", "format": "yaml|json" }
- Returns: parsed spec, validation results, repair suggestions

### POST /api/v1/generate/mcp
Generate a full MCP server project from an OpenAPI or AsyncAPI spec.
- Body: { "spec": { "content": "..." }, "config": { "serviceName": "...", "subdomain": "..." } }
- Returns: complete project files ready for deployment

### POST /api/v1/generate/client
Generate typed clients from any spec.
- Body: { "spec": { "content": "..." }, "outputs": ["typescript", "curl", "tests"] }

### GET /api/v1/templates
List available spec templates (OpenAPI, AsyncAPI, JSON Schema, MCP).

### GET /api/v1/traces
List AI agent traces from the Trace Observatory.
- Query params: limit, status, agent, minHealth
- Returns: { traces: [...] }

### GET /api/v1/traces/{traceId}
Get detailed trace information including spans and tool calls.
- Returns: trace with spans, tool calls, and metadata

### GET /api/v1/network
Get Platphorm News MCP network status.
- Returns: network info with all federated servers and their status

## Network
Part of the PlatPhorm News network:
- Main: https://platphormnews.com
- Docs: https://docs.platphormnews.com
- MCP Hub: https://mcp.platphormnews.com
- Monitor: https://monitor.platphormnews.com
- Trace Observatory: https://trace.platphormnews.com
- JSON Tree: https://json.platphormnews.com
- XML Tree: https://xml.platphormnews.com
- SVG Factory: https://svg.platphormnews.com
- Calendar: https://calendar.platphormnews.com
- Kanban: https://kanban.platphormnews.com

## Links
- Full LLM docs: https://spec.platphormnews.com/llms-full.txt
- API docs: https://spec.platphormnews.com/api/docs
- RSS feed: https://spec.platphormnews.com/feed.xml