Skip to content

MCP-SERVERS.md

Latest commit

 

History

History
374 lines (283 loc) · 9.72 KB

MCP-SERVERS.md

File metadata and controls

374 lines (283 loc) · 9.72 KB
Raw

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.

mbtq://tools/deafauth — identity verification protocol 
∙	mbtq://tools/pinksync — accessibility protocol 
∙	mbtq://tools/fibronrose — trust query protocol 
∙	mbtq://tools/magicians — agent dispatch (recommend-only, enforced at protocol level)

Transport: stdio locally, Cloudflare Worker SSE at edge — with PinkSync as the reliability layer in between.

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