# Schema Guided MCP Server

A TypeScript-based Model Context Protocol (MCP) server that enforces structured output from agents using Schema Guided Reasoning principles. This server prevents context loss when transitioning between agents in a figma-to-code workflow.

## Overview

This MCP server provides tools for:
- **Context bridging** between agents with structured validation
- **Schema enforcement** for agent outputs using Zod schemas
- **In-memory context storage** (opt-in filesystem persistence available)
- **Debugging support** for agent interaction flows

## Architecture

### Agent Flow
1. `figma-component-mapper` → analyzes Figma designs → maps to @orchard/suite-components
2. `suite-component-analyzer` → enhances component analysis → provides detailed props
3. `main agent` → creates final implementation solution

### Schema Guided Reasoning
- Enforces structured templates that define exact steps agents must follow
- Validates all agent outputs against predefined schemas
- Ensures complete context preservation between agent transitions
- Provides error recovery when validation fails

## Installation

```bash
npm install
npm run build
```

## Environment Variables

The server requires configuration via environment variables. Create a `.env` file in the project root or set these variables in your environment:

### Required Variables

#### `ORCHARD_COMPONENTS_DIR`
**Required** - Path to the orchard-suite components directory.

```bash
export ORCHARD_COMPONENTS_DIR="/path/to/orchard-suite/packages/suite-components/src/components"
```

This variable is used by the components manifest tool to locate and read component manifests. The server will fail to start if this variable is not set.

### Optional Variables

#### `SCHEMA_STORAGE_DIR`
**Optional** - Custom directory for storing context data when persistence is enabled.

```bash
export SCHEMA_STORAGE_DIR="/custom/path/to/storage"
```

**Default**: `~/.claude/schema-guided-contexts`

This variable allows you to customize where context data is persisted when filesystem persistence is enabled.

### Example Configuration

```bash
# .env file
ORCHARD_COMPONENTS_DIR="/Users/yourusername/projects/orchard-suite/packages/suite-components/src/components"
SCHEMA_STORAGE_DIR="/Users/yourusername/.mcp-storage/contexts"
```

### Troubleshooting

**Error: `ORCHARD_COMPONENTS_DIR environment variable is not set`**
- Ensure you've set the `ORCHARD_COMPONENTS_DIR` environment variable
- Verify the path exists and points to the correct components directory
- Check that the path contains a `components.manifest.json` file

**Components not found**
- Verify the `ORCHARD_COMPONENTS_DIR` path is absolute, not relative
- Ensure the orchard-suite repository is cloned and built
- Check file permissions on the components directory

## Development

```bash
npm run watch    # Watch for changes and rebuild
npm run dev      # Build and run server
npm run inspector # Test with MCP inspector
```

## Tools Provided

### Context Bridge Tools
- `submit_figma_mapping_context` - Validates and stores figma-component-mapper output
- `submit_enhanced_analysis_context` - Validates and stores suite-component-analyzer output
- `get_context_bridge` - Retrieves structured context for agent handoffs

### Schema Enforcement Tools
- `validate_agent_output` - Real-time schema validation
- `get_schema_definition` - Returns schema requirements for agents
- `debug_context_flow` - Inspects context flow between agents

### Context Management
- `clear_context_cache` - Resets stored contexts
- `get_context_history` - Shows context transition history

## Usage with Claude Code

This server is designed to be used with Claude Code and integrates with the existing agent system defined in `.claude/agents/`.

## Schema Structure

The server enforces structured schemas for:
- Figma component mapping context
- Enhanced component analysis context
- Agent transition metadata
- Validation results

All schemas are defined using Zod for runtime validation and TypeScript type safety.

## Storage Configuration

By default, the server uses **in-memory storage only**. Context data is not persisted to disk and will be lost when the server restarts.

To enable filesystem persistence, modify [src/storage/index.ts](src/storage/index.ts:14):

```typescript
export const contextStorage = new FilesystemContextStorage({
  enablePersistence: true, // Enable filesystem persistence
  baseDir: undefined, // Uses SCHEMA_STORAGE_DIR env var, or ~/.claude/schema-guided-contexts by default
  cleanupIntervalMs: 24 * 60 * 60 * 1000, // 24 hours
  contextTtlMs: 30 * 24 * 60 * 60 * 1000, // 30 days
  enableAutoCleanup: true,
});
```

When persistence is enabled, context data is stored in the directory specified by the `SCHEMA_STORAGE_DIR` environment variable, or `~/.claude/schema-guided-contexts/` by default, with automatic cleanup after 30 days.