# Spec Workbench - Complete LLM Documentation
> AI-first OpenAPI / MCP / JSON Schema / AsyncAPI workbench
> Version: 1.0.0
> Last Updated: 2026-04-09T02:25:41.052Z

## Service Identity

**Name:** Spec Workbench
**Subdomain:** spec
**Parent Domain:** platphormnews.com
**Canonical URL:** https://spec.platphormnews.com
**Category:** Developer Tools
**Tags:** api, openapi, mcp, json-schema, asyncapi, code-generation, validation

## What This Service Does

Spec Workbench is a comprehensive tool for API specification management. It addresses the critical problem of "spec drift" - when API implementations diverge from their specifications. Every AI/dev team building agent integrations faces this challenge.

### Primary Use Cases

1. **Spec Validation**: Validate OpenAPI, AsyncAPI, JSON Schema, and MCP specifications
2. **Spec Repair**: Automatically fix common spec issues
3. **Version Diffing**: Compare spec versions to identify breaking changes
4. **MCP Generation**: Generate complete Model Context Protocol servers
5. **Client Generation**: Generate typed clients, tests, and documentation

## API Reference

### Health Check
```
GET /api/health

Response:
{
  "status": "healthy",
  "service": "spec-workbench",
  "version": "1.0.0",
  "timestamp": "2024-01-01T00:00:00Z",
  "checks": {
    "database": { "status": "healthy", "latency_ms": 5 }
  }
}
```

### API Documentation
```
GET /api/docs

Response: OpenAPI 3.1 specification document
Query params:
  - format=json|yaml (default: json)
  - version=v1 (default: v1)
```

### Parse Spec
```
POST /api/v1/specs

Request:
{
  "content": "openapi: 3.0.0\ninfo:\n  title: My API...",
  "format": "yaml"
}

Response:
{
  "success": true,
  "spec": {
    "type": "openapi",
    "version": "3.0.0",
    "info": { "title": "My API", ... },
    "endpoints": [...],
    "schemas": {...}
  },
  "validation": {
    "valid": true,
    "errors": [],
    "warnings": []
  }
}
```

### Validate Spec
```
POST /api/v1/specs/validate

Request:
{
  "content": "...",
  "format": "yaml",
  "strict": true
}

Response:
{
  "valid": false,
  "errors": [
    {
      "path": "/paths/~1users/get/responses",
      "message": "Missing required response definition for 200",
      "severity": "error",
      "suggestion": "Add a 200 response with schema"
    }
  ],
  "warnings": [...]
}
```

### Repair Spec
```
POST /api/v1/specs/repair

Request:
{
  "content": "...",
  "format": "yaml",
  "autoFix": true
}

Response:
{
  "repaired": true,
  "content": "...(fixed spec)...",
  "changes": [
    {
      "path": "/info/version",
      "action": "added",
      "value": "1.0.0"
    }
  ]
}
```

### Diff Specs
```
POST /api/v1/specs/diff

Request:
{
  "base": { "content": "...", "format": "yaml" },
  "target": { "content": "...", "format": "yaml" }
}

Response:
{
  "breaking": [
    {
      "type": "endpoint_removed",
      "path": "DELETE /users/{id}",
      "severity": "breaking"
    }
  ],
  "nonBreaking": [
    {
      "type": "endpoint_added",
      "path": "GET /users/{id}/profile",
      "severity": "info"
    }
  ],
  "summary": {
    "totalChanges": 5,
    "breakingChanges": 1,
    "additions": 3,
    "removals": 1
  }
}
```

### Generate MCP Server
```
POST /api/v1/generate/mcp

Request:
{
  "spec": { "content": "...", "format": "yaml" },
  "config": {
    "serviceName": "my-service",
    "subdomain": "my-service",
    "parentDomain": "example.com",
    "version": "1.0.0",
    "category": "api",
    "tags": ["example"],
    "database": "neon"
  }
}

Response:
{
  "files": [
    { "path": "src/mcp/server.ts", "content": "..." },
    { "path": "src/mcp/http.ts", "content": "..." },
    { "path": "scripts/migrate.sql", "content": "..." },
    ...
  ],
  "downloadUrl": "/api/v1/generate/download/abc123"
}
```

### Generate Client
```
POST /api/v1/generate/client

Request:
{
  "spec": { "content": "...", "format": "yaml" },
  "outputFormat": "typescript|curl|tests-vitest|action-openai",
  "name": "my-api-client",
  "baseUrl": "https://api.example.com"
}

Response:
{
  "content": "// Generated TypeScript client...",
  "filename": "my-api-client.ts"
}
```

### List Templates
```
GET /api/v1/templates

Response:
{
  "templates": [
    {
      "id": "openapi-minimal",
      "name": "OpenAPI 3.1 Minimal",
      "description": "Minimal OpenAPI 3.1 template",
      "type": "openapi"
    },
    {
      "id": "mcp-server",
      "name": "MCP Server",
      "description": "Model Context Protocol server template",
      "type": "mcp"
    }
  ]
}
```

## MCP Generation Details

When generating an MCP server, the following components are created:

### 1. Core MCP
- Bootstrap and initialization
- Stdio transport (for CLI usage)
- HTTP transport at /api/mcp
- Capability negotiation
- Tool registration with input schemas
- Resource registration with URI patterns
- Prompt registration with arguments
- Schema validation using Zod
- Structured JSON-RPC errors
- Timeout, retry, and cancellation hooks
- MCP Inspector compatibility
- Conformance test suite

### 2. PlatPhorm Identity
- Service name and slug
- Canonical URLs
- Parent domain linkage
- Environment detection (dev/preview/prod)
- Version tracking
- Category and tag metadata
- Visibility controls
- Deprecation state handling

### 3. Traceability
- Request ID generation
- Trace ID propagation
- Session ID tracking
- Tool call IDs
- Resource access IDs
- Prompt execution IDs
- Deployment IDs
- Parent trace linkage

### 4. Fingerprint Context
- Request fingerprint header extraction
- Source detection (header/cookie/generated)
- Host and route tracking
- Service identification
- Transport type
- Timestamp
- Tag attachment

### 5. Cosmologically Unique IDs
All IDs use CUID2 with prefixes:
- request_cuid: req_xxxxx
- trace_cuid: trc_xxxxx
- tool_call_cuid: tcl_xxxxx
- resource_cuid: res_xxxxx
- artifact_cuid: art_xxxxx

### 6. Tagging System
Default tags applied:
- ecosystem:platphormnews
- service:<name>
- surface:mcp
- transport:stdio|http
- runtime:vercel
- db:neon
- env:dev|preview|prod
- tier:public|internal
- category:<type>

### 7. Policy Defaults
- Shared origin allowlist for platphormnews.com subdomains
- Subdomain family rules
- Local dev exceptions (localhost:3000)
- Preview deployment exceptions
- Common headers
- Deny-by-default for external origins

### 8. Observability
- Structured JSON logging
- Trace event emission
- Per-tool timing metrics
- Per-resource timing metrics
- Error codes and warnings
- Deployment metadata
- Fingerprint attachment
- Tag attachment

### 9. Persistence (Neon)
Tables created:
- {prefix}_traces
- {prefix}_events  
- {prefix}_tool_calls
- {prefix}_resources_accessed
- {prefix}_prompts_executed

### 10. Registry/Discovery
- Service manifest JSON
- Capability summary
- Transport summary
- Documentation links
- Health check endpoints
- Registration payload for mcp.platphormnews.com
- Indexing payload for docs.platphormnews.com

### 11. Standard Endpoints
- /api/mcp - MCP JSON-RPC endpoint
- /api/docs - OpenAPI documentation
- /api/health - Health check

### 12. Deployment Assets
- Environment validation
- Vercel-ready project structure
- .env.example
- README.md
- Local dev commands
- MCP Inspector commands
- Test commands
- CONTRIBUTING.md
- LICENSE
- CHANGELOG.md scaffold

## Supported Spec Types

### OpenAPI
- Versions: 3.0.x, 3.1.x
- Formats: YAML, JSON
- Features: paths, components, security, servers

### AsyncAPI
- Versions: 2.x
- Formats: YAML, JSON
- Features: channels, messages, servers

### JSON Schema
- Versions: Draft-07, 2019-09, 2020-12
- Formats: JSON
- Features: definitions, $ref resolution

### MCP (Model Context Protocol)
- Version: 2024-11-05
- Features: tools, resources, prompts, sampling

## Rate Limits

- Public API: 100 requests/minute
- Authenticated: 1000 requests/minute
- Generation endpoints: 10 requests/minute

## Error Codes

- PARSE_ERROR: Failed to parse spec content
- VALIDATION_ERROR: Spec validation failed
- UNSUPPORTED_TYPE: Spec type not supported
- GENERATION_ERROR: Code generation failed
- RATE_LIMITED: Too many requests
- INTERNAL_ERROR: Server error

## Network Integration

This service is part of the PlatPhorm News network:

| Service | URL | Description |
|---------|-----|-------------|
| Main | https://platphormnews.com | News platform |
| Docs | https://docs.platphormnews.com | Documentation |
| MCP Hub | https://mcp.platphormnews.com | MCP server registry |
| Monitor | https://monitor.platphormnews.com | System monitoring |
| Spec | https://spec.platphormnews.com | This service |

## Contact

- Website: https://platphormnews.com
- Email: hello@platphormnews.com
- GitHub: https://github.com/platphormnews

---
Generated by spec.platphormnews.com