rosedael/remote-mcp-server-cf

COMPLiQ MCP Server - Production Ready 🚀

A production-ready Model Context Protocol (MCP) server for COMPLiQ AI compliance platform integration, featuring intelligent session management with automatic UUID generation and correlation ID tracking.

✅ Live Deployment

Production Server: https://remote-mcp-server-cf.t-benedict.workers.dev

• Health Check: /health - Server status and API key verification
• MCP Endpoint: /mcp - JSON-RPC protocol for tool execution
• SSE Endpoint: /sse - Server-Sent Events for real-time communication

🎯 Key Features

🔑 Intelligent Session Management

• Auto-Generated Session IDs: UUID v4 format, unique per user+model combination
• Model-Specific Sessions: Different models get different session IDs automatically
• Auto-Generated Correlation IDs: Unique identifier for each prompt/request
• User ID Requirement: All tools require user identifier for proper tracking

🛠️ Enhanced COMPLiQ Integration

• 6 Comprehensive Tools: Complete workflow coverage from input to output
• Automatic Timestamp Generation: ISO 8601 format as required by COMPLiQ API
• Secure Authentication: x-api-key header format with environment variable management
• Error Handling: Comprehensive error reporting and validation

📦 Available Tools

1. startSession

Initialize or update a session for a specific user and LLM model.

{
  "name": "startSession",
  "arguments": {
    "userId": "your-user-id",
    "modelName": "gpt-4"
  }
}

2. inputPrompt ⭐ Mandatory

Submit a prompt/request to COMPLiQ with automatic session management.

{
  "name": "inputPrompt",
  "arguments": {
    "userId": "your-user-id",
    "content": "Your prompt text here",
    "modelName": "gpt-4"
  }
}

3. addFile Optional

Attach a file to a request with automatic session management.

{
  "name": "addFile",
  "arguments": {
    "userId": "your-user-id",
    "fileBase64": "base64-encoded-file-data",
    "fileName": "document.pdf",
    "fileContentType": "application/pdf"
  }
}

4. intermediateResults Optional

Send intermediate processing results.

{
  "name": "intermediateResults",
  "arguments": {
    "userId": "your-user-id",
    "resourceName": "OpenAI GPT-4",
    "content": "Intermediate analysis results..."
  }
}

5. processingResult ⭐ Mandatory

Submit the final processing result/answer.

{
  "name": "processingResult",
  "arguments": {
    "userId": "your-user-id",
    "processingTime": "00:02:30",
    "content": "Final answer or analysis results..."
  }
}

6. getSessionInfo

Get information about user sessions and current session state.

{
  "name": "getSessionInfo",
  "arguments": {
    "userId": "your-user-id"
  }
}

📁 Clean Repository Structure

The repository has been streamlined for production use:

remote-mcp-server-cf/
├── src/
│   ├── index.ts          # Main server implementation (production-ready)
│   └── types.d.ts        # TypeScript type definitions
├── package.json          # Dependencies and scripts
├── wrangler.jsonc        # Cloudflare Workers configuration
├── tsconfig.json         # TypeScript configuration
├── biome.json           # Linting and formatting rules
└── README.md            # This documentation

What's NOT included (cleaned up):

• ❌ Obsolete alternative implementations
• ❌ Webpack configuration (not needed for Cloudflare Workers)
• ❌ Auto-generated type files
• ❌ Log files and build artifacts

🚀 Quick Start

Prerequisites

• Node.js 18.19.1+ (for local development)
• Cloudflare account (for deployment)
• COMPLiQ API key

Setup

1. Clone the repository

   git clone https://github.com/rosedael/remote-mcp-server-cf.git
   cd remote-mcp-server-cf
   

2. Install dependencies

   npm install
   

3. Configure API Key

   npx wrangler secret put COMPLIQ_API_KEY
   # Enter your COMPLiQ API key when prompted
   

4. Deploy to Cloudflare

   npm run deploy
   

Development Commands

# Local development server
npm run dev

# Code formatting
npm run format

# Linting with auto-fix
npm run lint:fix

# Type checking
npm run type-check

# Generate Cloudflare types (auto-generates worker-configuration.d.ts)
npm run cf-typegen

🧪 Testing Your Server

Method 1: MCP Inspector (Recommended)

1. Start the Inspector

   DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector@latest
   

2. Connect to Your Server

   • Open: http://localhost:6274
   • Transport: StreamableHttp
   • Server URL: https://remote-mcp-server-cf.t-benedict.workers.dev/mcp

3. Test Tools - Try the examples above in the inspector interface

Method 2: Command Line Testing

Health Check

curl https://remote-mcp-server-cf.t-benedict.workers.dev/health | jq

List Available Tools

curl -X POST https://remote-mcp-server-cf.t-benedict.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }' | jq '.result.tools[].name'

Test Session Creation

curl -X POST https://remote-mcp-server-cf.t-benedict.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "startSession",
      "arguments": {
        "userId": "test-user",
        "modelName": "gpt-4"
      }
    }
  }' | jq

Test COMPLiQ Integration

curl -X POST https://remote-mcp-server-cf.t-benedict.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "inputPrompt",
      "arguments": {
        "userId": "test-user",
        "content": "Hello COMPLiQ! Testing the integration.",
        "modelName": "gpt-4"
      }
    }
  }' | jq

🔧 Technical Details

Session Management Logic

• Session ID Generation: UUID v4 format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx)
• Model Switching: New session ID when user changes LLM model
• Correlation ID Format: Timestamp-based ({timestamp36}-{random6})
• Automatic Timestamps: ISO 8601 format (2025-06-22T18:09:35.229Z)

COMPLiQ API Integration

• Base URL: https://api.stage.compliq.ai
• Authentication: x-api-key header
• Content Type: multipart/form-data
• Supported File Types: png, jpeg, mp3, mp4, docx, pdf, csv, xml, ogg

Response Format

All tools return structured responses with session information:

{
  "success": true,
  "response": {
    "actionId": "uuid",
    "message": "Action was added to submitting queue!"
  },
  "sessionInfo": {
    "sessionId": "auto-generated-uuid",
    "correlationId": "auto-generated-id", 
    "userId": "user-provided-id",
    "modelName": "specified-model",
    "timestamp": "iso-8601-timestamp"
  }
}

📋 Environment Variables

Configure using Wrangler:

npx wrangler secret put COMPLIQ_API_KEY

🔍 Troubleshooting

Common Issues

"API key is required"

• Ensure COMPLIQ_API_KEY is set in Cloudflare Workers
• Verify the API key is valid and has proper permissions

"Connection Error"

• Check if the server is deployed and accessible
• Verify the MCP Inspector is using StreamableHttp transport
• Ensure the server URL is correct

"Tool execution failed"

• Verify userId is provided (required for all tools)
• Check that file uploads use supported formats
• Ensure content doesn't exceed length limits

Expected Success Indicators

• Health Check: Returns status "ok" with API key info
• Tools List: Returns 6 tools
• Session Creation: Returns UUID session ID
• COMPLiQ Calls: Return actionId and queue confirmation

📚 Documentation

• COMPLiQ API Documentation
• Model Context Protocol
• Cloudflare Workers

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  Cloudflare     │───▶│   COMPLiQ API   │
│   (Inspector)   │    │  Workers        │    │  (Compliance)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ Session Manager │
                    │ (UUID + Corr.)  │
                    └─────────────────┘

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 License

This project is licensed under the MIT License.

🎯 Status

✅ Production Ready
✅ All Tests Passing
✅ COMPLiQ API Verified
✅ Session Management Working
✅ MCP 2024-11-05 Compliant

Built with ❤️ for AI compliance and Model Context Protocol integration.