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

# 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

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

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

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

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:

{
  "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

npm run build

Run Individual MCP Server

# 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:

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

{
  "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:

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:

# 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