MCP-SERVERS.md

# MCP Server Documentation

## Overview

The DEAF-FIRST Platform includes five Model Context Protocol (MCP) servers that provide programmatic access to various services through a standardized interface.

## Available MCP Servers

### 1. DeafAUTH MCP Server
**Service**: Authentication and User Management  
**Location**: `services/deafauth/dist/mcp-server.js`

#### Tools

- **authenticate_user**: Authenticate a user with username and password
  - Input: `username` (string), `password` (string)
  - Output: Authentication token and user info

- **create_user**: Create a new user account with accessibility preferences
  - Input: `username` (string), `password` (string), `email` (string), `accessibilityPreferences` (object)
  - Output: User ID and profile

- **get_user**: Get user information by user ID
  - Input: `userId` (string)
  - Output: User profile with accessibility preferences

#### Usage Example
```bash
# Build and run
npm run build --workspace=services/deafauth
node services/deafauth/dist/mcp-server.js
```

---

### 2. PinkSync MCP Server
**Service**: Real-time Data Synchronization  
**Location**: `services/pinksync/dist/mcp-server.js`

#### Tools

- **sync_data**: Synchronize data across connected clients
  - Input: `channel` (string), `data` (object)
  - Output: Sync confirmation with timestamp

- **subscribe_channel**: Subscribe to a synchronization channel
  - Input: `channel` (string)
  - Output: Subscription ID

- **get_sync_status**: Get current synchronization status
  - Input: None
  - Output: Connection status and metrics

#### Usage Example
```bash
npm run build --workspace=services/pinksync
node services/pinksync/dist/mcp-server.js
```

---

### 3. FibonRose MCP Server
**Service**: Mathematical Optimization Engine  
**Location**: `services/fibonrose/dist/mcp-server.js`

#### Tools

- **optimize_schedule**: Optimize task scheduling using Fibonacci-based algorithms
  - Input: `tasks` (array of {id, duration, priority})
  - Output: Optimized schedule with efficiency score

- **calculate_fibonacci**: Calculate Fibonacci number for a given position
  - Input: `n` (number)
  - Output: Fibonacci value at position n

- **golden_ratio_analysis**: Perform golden ratio analysis for optimization
  - Input: `value` (number)
  - Output: Golden ratio calculations

#### Usage Example
```bash
npm run build --workspace=services/fibonrose
node services/fibonrose/dist/mcp-server.js
```

---

### 4. Accessibility Nodes MCP Server
**Service**: Modular Accessibility Features  
**Location**: `services/accessibility-nodes/dist/mcp-server.js`

#### Tools

- **get_sign_language_interpretation**: Get sign language interpretation for text
  - Input: `text` (string), `language` (ASL/BSL/ISL)
  - Output: Video URL and gesture sequence

- **apply_high_contrast**: Apply high contrast accessibility to content
  - Input: `content` (string), `level` (low/medium/high)
  - Output: Enhanced content with color scheme

- **simplify_text**: Simplify complex text for better accessibility
  - Input: `text` (string), `level` (1-5)
  - Output: Simplified text with readability score

- **get_accessibility_recommendations**: Get accessibility recommendations
  - Input: `contentType` (web/document/video)
  - Output: Recommendations and WCAG level

#### Usage Example
```bash
npm run build --workspace=services/accessibility-nodes
node services/accessibility-nodes/dist/mcp-server.js
```

---

### 5. AI MCP Server
**Service**: AI-Powered Workflows  
**Location**: `ai/dist/mcp-server.js`

#### Tools

- **process_text**: Process text using AI (summarize, translate, or simplify)
  - Input: `text` (string), `operation` (summarize/translate/simplify)
  - Output: Processed text with confidence score

- **generate_content**: Generate accessible content using AI
  - Input: `prompt` (string), `type` (text/image/video)
  - Output: Generated content URL

- **analyze_accessibility**: Analyze content for accessibility issues
  - Input: `content` (string), `contentType` (string)
  - Output: Accessibility analysis with recommendations

#### Usage Example
```bash
npm run build --workspace=ai
node ai/dist/mcp-server.js
```

---

## Configuration

### MCP Configuration File

The `mcp-config.json` file provides configuration for all MCP servers:

```json
{
  "mcpServers": {
    "deafauth": {
      "command": "node",
      "args": ["services/deafauth/dist/mcp-server.js"],
      "description": "DeafAUTH - Accessible authentication service"
    },
    // ... other servers
  }
}
```

### Environment Variables

Each MCP server may require specific environment variables:

**DeafAUTH**:
- `DEAFAUTH_DATABASE_URL`: PostgreSQL connection string

**PinkSync**:
- `REDIS_URL`: Redis connection string

**AI Services**:
- `OPENAI_API_KEY`: OpenAI API key for AI operations

## Running MCP Servers

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

### Run Individual MCP Server
```bash
# DeafAUTH
npm run mcp --workspace=services/deafauth

# PinkSync
npm run mcp --workspace=services/pinksync

# FibonRose
npm run mcp --workspace=services/fibonrose

# Accessibility Nodes
npm run mcp --workspace=services/accessibility-nodes

# AI Services
npm run mcp --workspace=ai
```

### Run with MCP Client

MCP servers communicate via stdio. To use them with an MCP client:

```javascript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['services/deafauth/dist/mcp-server.js']
});

const client = new Client({
  name: 'my-client',
  version: '1.0.0',
}, {
  capabilities: {}
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: 'authenticate_user',
  arguments: {
    username: 'user@example.com',
    password: 'password123'
  }
});
```

## Integration with Claude Desktop

To use these MCP servers with Claude Desktop, add the following to your Claude configuration:

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

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

## Development

### Adding a New Tool

To add a new tool to an MCP server:

1. Define the tool schema in the tools array
2. Implement the tool handler in the CallToolRequestSchema handler
3. Add input validation using Zod
4. Return properly formatted responses

Example:
```typescript
const tools: Tool[] = [
  {
    name: 'my_new_tool',
    description: 'Description of what this tool does',
    inputSchema: {
      type: 'object',
      properties: {
        param1: { type: 'string', description: 'Parameter description' }
      },
      required: ['param1']
    }
  }
];

// In the handler
case 'my_new_tool': {
  const { param1 } = MyToolSchema.parse(args);
  // Tool implementation
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify({ result: 'success' })
      }
    ]
  };
}
```

### Testing MCP Servers

Test MCP servers by running them and sending test inputs:

```bash
# Build the server
npm run build --workspace=services/deafauth

# Run in test mode (manual testing via stdio)
echo '{"method":"tools/list","id":1}' | node services/deafauth/dist/mcp-server.js
```

## Troubleshooting

### Server won't start
- Ensure all dependencies are installed: `npm install`
- Build the project: `npm run build`
- Check environment variables are set correctly

### Tool not found
- Verify the tool name matches exactly
- Check that the server has been built recently
- Review the server logs for errors

### Connection issues
- Ensure the server is running
- Check that the client is using the correct transport
- Verify file paths in configuration

## Architecture

Each MCP server:
1. Uses the `@modelcontextprotocol/sdk` for standardized communication
2. Implements stdio transport for IPC
3. Validates inputs using Zod schemas
4. Returns structured JSON responses
5. Handles errors gracefully

## Security Considerations

- Never expose sensitive credentials in MCP configuration
- Use environment variables for secrets
- Validate all inputs before processing
- Implement rate limiting for production use
- Log all MCP operations for audit trails

## Support

For issues or questions:
- Check the main README.md
- Review the infrastructure.md for architecture details
- Open an issue on GitHub

## License

MIT License - See LICENSE file for details