QUICKSTART.md

# DEAF-FIRST MCP Server Setup - Quick Start Guide

## What Has Been Created

This repository now contains a complete MCP (Model Context Protocol) server infrastructure for the DEAF-FIRST platform with 5 specialized services, a frontend, and a backend.

## Repository Structure

```
DEAF-FIRST-PLATFORM/
├── frontend/                    # React + Vite frontend
├── backend/                     # Express backend API
├── services/
│   ├── deafauth/               # Authentication service + MCP server
│   ├── pinksync/               # Real-time sync service + MCP server
│   ├── fibonrose/              # Optimization engine + MCP server
│   └── accessibility-nodes/    # Accessibility features + MCP server
├── ai/                         # AI services + MCP server
├── configs/deployment/         # Docker Compose configuration
├── package.json                # Root workspace configuration
├── mcp-config.json            # MCP servers configuration
├── README.md                   # Main documentation
├── MCP-SERVERS.md             # MCP server documentation
└── .env.example               # Environment variables template
```

## Quick Start

### 1. Install Dependencies
```bash
npm install
```

### 2. Set Up Environment
```bash
cp .env.example .env
# Edit .env with your configuration
```

### 3. Build All Services
```bash
npm run build
```

### 4. Run Development Environment
```bash
# Run all services
npm run dev

# Or run individual services
npm run dev:frontend
npm run dev:backend
npm run dev:deafauth
npm run dev:pinksync
npm run dev:fibonrose
npm run dev:a11y
```

## MCP Server Usage

### Running MCP Servers

Each service can be run as an MCP server:

```bash
# Build first
npm run build

# Run individual MCP servers
npm run mcp --workspace=services/deafauth
npm run mcp --workspace=services/pinksync
npm run mcp --workspace=services/fibonrose
npm run mcp --workspace=services/accessibility-nodes
npm run mcp --workspace=ai
```

### Testing MCP Servers

Use the included test script:

```bash
node test-mcp.mjs services/deafauth/dist/mcp-server.js
node test-mcp.mjs services/pinksync/dist/mcp-server.js
node test-mcp.mjs services/fibonrose/dist/mcp-server.js
node test-mcp.mjs services/accessibility-nodes/dist/mcp-server.js
node test-mcp.mjs ai/dist/mcp-server.js
```

### Claude Desktop Integration

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "deafauth": {
      "command": "node",
      "args": ["/absolute/path/to/DEAF-FIRST-PLATFORM/services/deafauth/dist/mcp-server.js"]
    },
    "pinksync": {
      "command": "node",
      "args": ["/absolute/path/to/DEAF-FIRST-PLATFORM/services/pinksync/dist/mcp-server.js"]
    },
    "fibonrose": {
      "command": "node",
      "args": ["/absolute/path/to/DEAF-FIRST-PLATFORM/services/fibonrose/dist/mcp-server.js"]
    },
    "accessibility-nodes": {
      "command": "node",
      "args": ["/absolute/path/to/DEAF-FIRST-PLATFORM/services/accessibility-nodes/dist/mcp-server.js"]
    },
    "ai": {
      "command": "node",
      "args": ["/absolute/path/to/DEAF-FIRST-PLATFORM/ai/dist/mcp-server.js"]
    }
  }
}
```

## Available Services

### 1. DeafAUTH (Port 3002)
**Purpose**: Accessible authentication and user management

**MCP Tools**:
- `authenticate_user`: Login with username/password
- `create_user`: Create new user with accessibility preferences
- `get_user`: Retrieve user profile

**REST API**:
- `POST /api/auth/login`: User authentication
- `POST /api/auth/register`: User registration
- `GET /api/users/:userId`: Get user info

### 2. PinkSync (Port 3003)
**Purpose**: Real-time data synchronization

**MCP Tools**:
- `sync_data`: Synchronize data across channels
- `subscribe_channel`: Subscribe to sync channel
- `get_sync_status`: Get sync status

**REST API**:
- `POST /api/sync`: Sync data
- `GET /api/sync/status`: Get sync status
- WebSocket endpoint for real-time updates

### 3. FibonRose (Port 3004)
**Purpose**: Mathematical optimization engine

**MCP Tools**:
- `optimize_schedule`: Optimize task scheduling
- `calculate_fibonacci`: Calculate Fibonacci numbers (optimized O(n) algorithm)
- `golden_ratio_analysis`: Golden ratio calculations

**REST API**:
- `POST /api/optimize/schedule`: Schedule optimization
- `GET /api/fibonacci/:n`: Calculate Fibonacci
- `POST /api/golden-ratio`: Golden ratio analysis

### 4. Accessibility Nodes (Port 3005)
**Purpose**: Modular accessibility features

**MCP Tools**:
- `get_sign_language_interpretation`: Sign language for text (ASL/BSL/ISL)
- `apply_high_contrast`: Apply high contrast mode
- `simplify_text`: Text simplification
- `get_accessibility_recommendations`: Get WCAG recommendations

**REST API**:
- `POST /api/sign-language`: Get sign language interpretation
- `POST /api/high-contrast`: Apply high contrast
- `POST /api/simplify-text`: Simplify text
- `GET /api/recommendations/:contentType`: Get recommendations

### 5. AI Services (Port 3006)
**Purpose**: AI-powered workflows

**MCP Tools**:
- `process_text`: Summarize, translate, or simplify text
- `generate_content`: Generate accessible content
- `analyze_accessibility`: Analyze accessibility issues

**REST API**:
- `POST /api/process/text`: Process text with AI
- `POST /api/generate`: Generate content
- `POST /api/analyze/accessibility`: Analyze accessibility

### 6. Backend (Port 3000)
**Purpose**: Main backend API

**REST API**:
- `GET /health`: Health check
- `GET /api/status`: Service status

### 7. Frontend (Port 5173)
**Purpose**: React-based user interface

**Features**:
- Service overview dashboard
- Accessibility-first design
- Responsive layout

## Docker Deployment

```bash
# Build Docker images
npm run build:docker

# Start all services
npm run docker:up

# View logs
npm run docker:logs

# Stop all services
npm run docker:down
```

## Development Commands

```bash
# Development
npm run dev                  # Run all services
npm run dev:frontend         # Frontend only
npm run dev:backend          # Backend only
npm run dev:deafauth         # DeafAUTH only
npm run dev:pinksync         # PinkSync only
npm run dev:fibonrose        # FibonRose only
npm run dev:a11y             # Accessibility nodes only

# Building
npm run build                # Build all workspaces

# Testing
npm run test                 # Run all tests
npm run test:e2e             # End-to-end tests

# Code Quality
npm run lint                 # Lint code
npm run format               # Format with Prettier
npm run type-check           # TypeScript type checking

# Database
npm run db:setup             # Setup databases
npm run db:migrate           # Run migrations
npm run db:seed              # Seed data

# Cleanup
npm run clean                # Clean all artifacts
```

## Environment Variables

Key environment variables (see `.env.example` for complete list):

```env
# Databases
DATABASE_URL=postgresql://user:password@localhost:5432/deafirst
DEAFAUTH_DATABASE_URL=postgresql://user:password@localhost:5432/deafauth

# Redis
REDIS_URL=redis://localhost:6379

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRY=7d

# Service Ports
BACKEND_PORT=3000
DEAFAUTH_PORT=3002
PINKSYNC_PORT=3003
FIBONROSE_PORT=3004
A11Y_PORT=3005
AI_PORT=3006

# AI Services
OPENAI_API_KEY=your-api-key
```

## Key Features

✅ **Complete Monorepo**: npm workspaces with all services
✅ **MCP Protocol**: 5 MCP servers for programmatic access
✅ **TypeScript**: Full type safety across all services
✅ **REST APIs**: HTTP endpoints for all services
✅ **WebSocket**: Real-time communication (PinkSync)
✅ **Docker Ready**: Complete Docker Compose setup
✅ **Accessibility First**: All services designed with accessibility in mind
✅ **Documentation**: Comprehensive docs for all components
✅ **Testing**: Test infrastructure included
✅ **Production Ready**: Linting, type-checking, building all working

## Architecture Highlights

1. **Deaf-First Design**: All services prioritize accessibility
2. **MCP Integration**: Programmatic access via Model Context Protocol
3. **Microservices**: Independent, scalable services
4. **Type Safety**: TypeScript with strict mode everywhere
5. **Input Validation**: Zod schemas for all inputs
6. **Performance**: Optimized algorithms (e.g., O(n) Fibonacci)
7. **Real-time**: WebSocket support for live updates
8. **AI-Powered**: Integration-ready for AI services

## Next Steps

1. **Configure Environment**: Update `.env` with your settings
2. **Start Database**: Run PostgreSQL and Redis (or use Docker)
3. **Install Dependencies**: Run `npm install`
4. **Build Services**: Run `npm run build`
5. **Start Development**: Run `npm run dev`
6. **Test MCP Servers**: Use test script or integrate with Claude

## Documentation

- `README.md`: Main project documentation
- `MCP-SERVERS.md`: Detailed MCP server documentation
- `infrastructure.md`: Architecture overview
- `.env.example`: Environment configuration template

## Support

For issues or questions:
- Review the documentation files
- Check service logs
- Open an issue on GitHub

## License

MIT License - See LICENSE file

---

**Built by 360 Magicians**  
**DEAF-FIRST Platform v2.0.0**