# MCP Trace Observatory - Technical Standards

## Protocol Standards

### MCP (Model Context Protocol)
- Version: 2024-11-05
- Transport: streamable-http
- Endpoint: POST /api/mcp
- Reference: https://modelcontextprotocol.io

### JSON-RPC
- Version: 2.0
- Used for MCP message format
- All requests include id for correlation

## API Standards

### REST Conventions
- GET for read operations
- POST for create/action operations
- JSON request/response bodies
- HTTP status codes per RFC 7231

### Versioning
- URL path versioning: /api/v1/*
- Breaking changes get new version
- Deprecation notices 6 months ahead

### Rate Limiting
- 100 requests per minute (anonymous)
- 1000 requests per minute (authenticated)
- X-RateLimit headers in responses

### Error Format
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  },
  "requestId": "abc123"
}

## Data Standards

### Trace Format
{
  "traceId": "uuid",
  "name": "string",
  "status": "running|completed|error|timeout",
  "agentName": "string",
  "startTime": "ISO8601",
  "endTime": "ISO8601",
  "durationMs": "number",
  "spans": [],
  "toolCalls": [],
  "aiHealthScore": "0-100"
}

### Timestamp Format
- ISO 8601 for all timestamps
- UTC timezone
- Millisecond precision

### ID Format
- UUIDs (v4) for trace IDs
- Base64 short IDs for display
- Cosmic signatures for correlation

## Security Standards

### Authentication
- Bearer tokens for API access
- JWT for session management
- API keys for server-to-server

### Encryption
- TLS 1.3 minimum
- HTTPS only (no HTTP)
- Sensitive data encrypted at rest

### Headers
- X-Request-Id for tracing
- X-Bot-Type for client detection
- X-MCP-* for protocol info

## Accessibility Standards

### WCAG 2.2 Level AA
- Color contrast 4.5:1 minimum
- Keyboard navigation support
- Screen reader compatibility
- Focus indicators visible

### Responsive Design
- Mobile-first approach
- Breakpoints: 640px, 768px, 1024px, 1280px
- Touch-friendly targets (44x44px minimum)

## Code Standards

### TypeScript
- Strict mode enabled
- No any types
- Explicit return types

### React/Next.js
- App Router (Next.js 16)
- Server Components by default
- Client Components when needed

### CSS
- Tailwind CSS v4
- CSS custom properties for theming
- No inline styles

## Performance Standards

### Core Web Vitals
- LCP < 2.5s
- INP < 200ms
- CLS < 0.1

### Response Times
- API < 500ms (p95)
- Page load < 3s
- Time to interactive < 5s

## Observability Standards

### Logging
- Structured JSON logs
- Log levels: debug, info, warn, error
- Request ID correlation

### Metrics
- Vercel Analytics integration
- SpeedInsights for performance
- Custom trace metrics

### Tracing
- Distributed trace correlation
- Cosmic signatures for uniqueness
- End-to-end request tracking

## Discovery Standards

### Files
- /robots.txt - Crawler directives
- /sitemap.xml - Site structure
- /llms.txt - LLM discovery
- /llms-full.txt - Complete context
- /feed.xml - RSS/Atom feed
- /api/docs - API documentation
- /api/mcp - MCP endpoint

### Metadata
- OpenGraph tags
- Twitter cards
- JSON-LD structured data
- Link rel headers

---

Version: 1.0
Last updated: 2026-04-08
Maintained by: Platphorm News