suitecrm-mcp-server-sse

v1.0.2

Published

7 months ago

SuiteCRM MCP Server with SSE transport and HTTP endpoints for frontend integration

0High
0Medium
0Low

arauf037

suitecrm mcp model-context-protocol sse server-sent-events crm api oauth http frontend

SuiteCRM MCP Server SSE

A production-ready Model Context Protocol (MCP) server for SuiteCRM integration using Server-Sent Events (SSE) transport. Perfect for web applications and production portals that need real-time SuiteCRM data access.

Features

✅ SSE Transport: Server-Sent Events for real-time web communication
✅ Production Ready: Express server with security, CORS, rate limiting
✅ SuiteCRM Integration: Full OAuth 2.0 authentication and API access
✅ Four Core Tools:
- authenticate_crm - Authenticate with SuiteCRM
- get_modules - Fetch available CRM modules
- get_module_schema - Get detailed module schemas
- execute_query - Execute SQL queries with security validation
✅ Security Features: SQL injection prevention, input validation, audit logging
✅ Performance: Token caching, schema caching, connection pooling
✅ TypeScript: Full type definitions included
✅ Multi-Client Support: Multiple web clients can connect simultaneously

Installation

npm install suitecrm-mcp-server-sse

Quick Start

1. Install the Package

npm install suitecrm-mcp-server-sse

2. Create a Server Instance

const { SuiteCRMCPServer } = require('suitecrm-mcp-server-sse');

// Create server instance
const server = new SuiteCRMCPServer();

// Start the server
server.run().catch(console.error);

3. Configure Environment Variables

Create a .env file:

# Server Configuration
SERVER_PORT=3000
SERVER_HOST=0.0.0.0
CORS_ORIGIN=*

# SuiteCRM Configuration
SUITECRM_URL=https://your-suitecrm-instance.com
SUITECRM_CLIENT_ID=your_oauth_client_id
SUITECRM_CLIENT_SECRET=your_oauth_client_secret

# Performance Configuration
MAX_QUERY_ROWS=100
REQUEST_TIMEOUT=30000
LOG_LEVEL=info

# Rate Limiting
RATE_LIMIT_WINDOW=60000
RATE_LIMIT_MAX_REQUESTS=100

4. Start the Server

# Using npm script
npm start

# Or directly
node dist/index.js

Server Endpoints

Once started, your server will be available at:

MCP SSE Endpoint: http://localhost:3000/mcp
Health Check: http://localhost:3000/health
API Documentation: http://localhost:3000/docs
Server Info: http://localhost:3000/

Usage Examples

Web Client Integration

<!DOCTYPE html>
<html>
<head>
    <title>SuiteCRM MCP Client</title>
</head>
<body>
    <h1>SuiteCRM MCP Client</h1>
    <div id="output"></div>
    
    <script>
        // Connect to MCP server via SSE
        const eventSource = new EventSource('http://localhost:3000/mcp');
        
        eventSource.onopen = function(event) {
            console.log('Connected to MCP server');
            document.getElementById('output').innerHTML += '<p>✅ Connected to MCP server</p>';
        };
        
        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);
            console.log('Received:', data);
            document.getElementById('output').innerHTML += '<p>📨 ' + JSON.stringify(data) + '</p>';
        };
        
        eventSource.onerror = function(event) {
            console.error('SSE error:', event);
            document.getElementById('output').innerHTML += '<p>❌ Connection error</p>';
        };
    </script>
</body>
</html>

Express.js Integration

const express = require('express');
const { SuiteCRMCPServer } = require('suitecrm-mcp-server-sse');

const app = express();
app.use(express.json());

// Initialize MCP server
const mcpServer = new SuiteCRMCPServer();

// Start MCP server
mcpServer.run().catch(console.error);

// Your Express routes
app.get('/api/status', (req, res) => {
    res.json({ status: 'MCP server running' });
});

app.listen(3001, () => {
    console.log('Express app running on port 3001');
    console.log('MCP server running on port 3000');
});

Node.js Client

const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
const { SseClientTransport } = require('@modelcontextprotocol/sdk/client/sse.js');

async function testMCP() {
    const transport = new SseClientTransport('http://localhost:3000/mcp');
    const client = new Client({
        name: 'test-client',
        version: '1.0.0'
    });
    
    await client.connect(transport);
    
    // List available tools
    const tools = await client.listTools();
    console.log('Available tools:', tools);
    
    // Test authentication
    const result = await client.callTool('authenticate_crm', {
        crm_url: 'https://your-suitecrm-instance.com',
        client_id: 'your_client_id',
        client_secret: 'your_client_secret'
    });
    
    console.log('Authentication result:', result);
}

testMCP().catch(console.error);

Configuration Options

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SERVER_PORT | HTTP server port | 3000 | | SERVER_HOST | HTTP server host | 0.0.0.0 | | CORS_ORIGIN | CORS allowed origins | * | | SUITECRM_URL | SuiteCRM instance URL | http://localhost/suitecrm | | SUITECRM_CLIENT_ID | OAuth client ID | - | | SUITECRM_CLIENT_SECRET | OAuth client secret | - | | LOG_LEVEL | Logging level | info | | MAX_QUERY_ROWS | Maximum rows per query | 100 | | REQUEST_TIMEOUT | Request timeout (ms) | 30000 | | RATE_LIMIT_WINDOW | Rate limit window (ms) | 60000 | | RATE_LIMIT_MAX_REQUESTS | Max requests per window | 100 |

API Tools

1. authenticate_crm

Authenticate with SuiteCRM using client credentials.

Parameters:

crm_url (string): SuiteCRM instance URL
client_id (string): OAuth client ID
client_secret (string): OAuth client secret

2. get_modules

Fetch available CRM modules.

Parameters:

crm_url (string): SuiteCRM instance URL
access_token (string): Valid access token

3. get_module_schema

Get detailed schema for a specific module.

Parameters:

crm_url (string): SuiteCRM instance URL
access_token (string): Valid access token
module_name (string): Name of the module

4. execute_query

Execute SQL query against CRM database.

Parameters:

crm_url (string): SuiteCRM instance URL
access_token (string): Valid access token
sql_query (string): SQL query to execute (SELECT only)

Security Features

SQL Injection Prevention: Query validation and sanitization
Rate Limiting: Configurable request limits per IP
CORS Protection: Configurable cross-origin resource sharing
Security Headers: Helmet.js for security headers
Input Validation: Zod schema validation for all inputs
Audit Logging: Comprehensive logging of all operations

Production Deployment

Docker Deployment

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
COPY .env ./

EXPOSE 3000

CMD ["node", "dist/index.js"]

Environment Configuration

# Production environment variables
export NODE_ENV=production
export SERVER_PORT=3000
export SERVER_HOST=0.0.0.0
export CORS_ORIGIN=https://yourdomain.com
export SUITECRM_URL=https://your-suitecrm-instance.com
export SUITECRM_CLIENT_ID=your_production_client_id
export SUITECRM_CLIENT_SECRET=your_production_client_secret
export LOG_LEVEL=warn

Load Balancer Configuration

upstream mcp_server {
    server localhost:3000;
}

server {
    listen 80;
    server_name yourdomain.com;

    location /mcp {
        proxy_pass http://mcp_server;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400;
    }

    location /health {
        proxy_pass http://mcp_server;
    }
}

Monitoring and Logging

The server includes comprehensive logging:

// Log levels: debug, info, warn, error
// Logs are written to console and files (if configured)

// Example log output:
// [2024-01-15T10:30:00.000Z] INFO: Starting SuiteCRM MCP Server with SSE transport
// [2024-01-15T10:30:00.100Z] INFO: HTTP server started on http://0.0.0.0:3000
// [2024-01-15T10:30:05.200Z] INFO: SSE connection established

Troubleshooting

Common Issues

Connection Refused: Check if server is running on correct port
CORS Errors: Verify CORS_ORIGIN configuration
Authentication Failed: Check SuiteCRM credentials and URL
Rate Limited: Increase rate limit settings if needed

Debug Mode

Enable debug logging:

LOG_LEVEL=debug

Health Check

Monitor server health:

curl http://localhost:3000/health

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Issues: GitHub Issues
Documentation: GitHub Wiki
Examples: See the examples/ directory

Changelog

v1.0.0

Initial release
SSE transport support
Production-ready Express server
Full SuiteCRM integration
Security features and rate limiting

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

SuiteCRM MCP Server SSE

Features

Installation

Quick Start

1. Install the Package

2. Create a Server Instance

3. Configure Environment Variables

4. Start the Server

Server Endpoints

Usage Examples

Web Client Integration

Express.js Integration

Node.js Client

Configuration Options

Environment Variables

API Tools

1. authenticate_crm

2. get_modules

3. get_module_schema

4. execute_query

Security Features

Production Deployment

Docker Deployment

Environment Configuration

Load Balancer Configuration

Monitoring and Logging

Troubleshooting

Common Issues

Debug Mode

Health Check

Contributing

License

Support

Changelog

v1.0.0