Rezoomex MCP Server

Rezoomex MCP Server (Node.js)

A Node.js-based Server-Sent Events (SSE) MCP server for Rezoomex API integration with bearer token authentication.

Features

SSE Support: Real-time streaming responses for long-running operations
Bearer Token Authentication: Secure authentication using Rezoomex bearer tokens
Comprehensive API Coverage: All major Rezoomex API endpoints
Session Management: Multi-user session handling with automatic cleanup
Proper Error Handling: Detailed error messages and logging
Rate Limiting: Built-in protection against abuse
Health Monitoring: Health check endpoints and logging

Quick Start

1. Installation

cd /Users/pratik/Documents/Projects/Rezoomex/image-processing/rezoomex
npm install

2. Configuration

Copy the environment template:

cp .env.example .env

Edit .env with your configuration:

PORT=3000
NODE_ENV=development
REZOOMEX_BASE_URL=https://awsapi-gateway.rezoomex.com
# No default projects - all project_id and persona_id must be provided

3. Start the Server

npm start

The server will be available at http://localhost:3000

Authentication Flow

curl http://localhost:3000/auth/login-url

Response:

{
  "loginUrl": "https://workspace.rezoomex.com/account/login",
  "instructions": "Please login at the provided URL and extract the bearer token from the URL after successful authentication.",
  "tokenLocation": "The bearer token will be in the URL as access_token parameter after login."
}

Visit the login URL in your browser
Login with your Rezoomex credentials
After successful login, extract the access_token from the URL
The URL will look like: https://workspace.rezoomex.com/dashboard?access_token=YOUR_BEARER_TOKEN&...

Step 3: Authenticate with Server

curl -X POST http://localhost:3000/auth/token \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"bearerToken": "YOUR_BEARER_TOKEN"}'

Response:

{
  "success": true,
  "sessionId": "your-session-id",
  "message": "Authentication successful. Use this session ID for subsequent requests.",
  "expiresIn": "24 hours"
}

API Endpoints

Health Check

GET /health

Authentication

GET /auth/login-url                    # Get login URL
POST /auth/token                       # Authenticate with bearer token
GET /auth/session/:sessionId           # Check session status
DELETE /auth/session/:sessionId        # Clear session

MCP Tools

GET /mcp/tools                         # List available tools
GET /mcp/execute/:toolName             # Execute tool via SSE
POST /mcp/execute/:toolName            # Execute tool via POST

Available MCP Tools

Tool Name	Description	Required Parameters
`list_user_stories`	List all user stories with numbers for a project and persona	`project_id`, `persona_id`
`get_story_range`	Get user stories in a range (e.g., stories 1-5) with all details	`project_id`, `persona_id`, `start_number`, `end_number`
`get_single_story_details`	Get detailed information for a single user story	`project_id`, `persona_id`
`get_project_overview`	Get comprehensive project overview	`project_id`
`get_persona_profile`	Get detailed persona profile	`project_id`, `persona_id`
`get_user_journey`	Get detailed user journey events	`project_id`, `persona_id`
`get_jobs_to_be_done`	Get Jobs to be Done analysis	`project_id`, `persona_id`
`get_user_info`	Get authenticated user profile information	None
`get_project_environment`	Get project environment information including personas	`project_id`
`check_nda_status`	Check NDA status for the authenticated user	None
`get_product_info`	Get detailed product information for a project	`project_id`

Name-Based Lookup Tools (User-Friendly)

Tool Name	Description	Required Parameters
`list_projects`	List all available projects with their names and IDs	None
`find_project_by_name`	Find a project by its name and get the project ID	`project_name`
`find_persona_by_name`	Find a persona by name within a project and get the persona ID	`project_id`, `persona_name`
`get_user_stories_by_name`	List user stories using project and persona names (more user-friendly)	`project_name`, `persona_name`
`get_persona_by_name`	Get persona profile using project and persona names (more user-friendly)	`project_name`, `persona_name`

Legacy Tools (Backward Compatibility)

Tool Name	Description	Required Parameters
`mcp0_getUserInfo`	Legacy: Get authenticated user profile information	None
`mcp0_fetchPersona`	Legacy: Get persona details by project and persona ID	`projectId`, `personaId`
`mcp0_fetchElevatorPitch`	Legacy: Get project elevator pitch	`projectId`
`mcp0_fetchVisionStatement`	Legacy: Get project vision statement	`projectId`
`mcp0_fetchProductInfo`	Legacy: Get product information	`projectId`
`mcp0_fetchProjectEnvironment`	Legacy: Get project environment information	`projectId`
`mcp0_checkNdaStatus`	Legacy: Check NDA status for the authenticated user	None

Usage Examples

Using SSE (Server-Sent Events)

const eventSource = new EventSource(
  'http://localhost:3000/mcp/execute/list_user_stories?project_id=39SQ&persona_id=39SQ-P-003',
  {
    headers: {
      'X-Session-ID': 'your-session-id'
    }
  }
);

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data);
  console.log('Progress:', data.message);
});

eventSource.addEventListener('result', (event) => {
  const data = JSON.parse(event.data);
  console.log('Result:', data.result);
});

eventSource.addEventListener('complete', (event) => {
  console.log('Operation completed');
  eventSource.close();
});

eventSource.addEventListener('error', (event) => {
  const data = JSON.parse(event.data);
  console.error('Error:', data.message);
});

Using POST Requests

# Using IDs (traditional way)
curl -X POST http://localhost:3000/mcp/execute/list_user_stories \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"project_id": "39SQ", "persona_id": "39SQ-P-003"}'

# Using names (user-friendly way)
curl -X POST http://localhost:3000/mcp/execute/get_user_stories_by_name \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"project_name": "Talentally Yours", "persona_name": "Priya Sinha"}'

Get Story Range

curl -X POST http://localhost:3000/mcp/execute/get_story_range \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"start_number": 1, "end_number": 5, "project_id": "39SQ", "persona_id": "39SQ-P-003"}'

Get Single Story Details

curl -X POST http://localhost:3000/mcp/execute/get_single_story_details \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: your-session-id" \
  -d '{"story_number": 1, "project_id": "39SQ", "persona_id": "39SQ-P-003"}'

Error Handling

The server provides detailed error messages for different scenarios:

Authentication Required: AUTH_REQUIRED - Need to authenticate first
Session Expired: SESSION_EXPIRED - Need to re-authenticate
Unknown Tool: UNKNOWN_TOOL - Tool name not recognized
Validation Error: VALIDATION_ERROR - Invalid input parameters
Execution Error: EXECUTION_ERROR - Error during tool execution

Logging

Logs are written to both console and file (logs/rezoomex-mcp.log). Log levels:

error: Critical errors
warn: Warning messages
info: General information
debug: Detailed debugging information

Development

Run in Development Mode

npm run dev

Run Tests

npm test

Configuration Options

Environment Variable	Default	Description
`PORT`	`3000`	Server port
`NODE_ENV`	`development`	Environment mode
`REZOOMEX_BASE_URL`	`https://awsapi-gateway.rezoomex.com`	Rezoomex API base URL
`REZOOMEX_LOGIN_URL`	`https://workspace.rezoomex.com/account/login`	Login URL
`DEFAULT_PROJECT_ID`	`39SQ`	Default project ID
`DEFAULT_PERSONA_ID`	`39SQ-P-003`	Default persona ID
`LOG_LEVEL`	`info`	Logging level
`LOG_FILE`	`logs/rezoomex-mcp.log`	Log file path
`RATE_LIMIT_WINDOW_MS`	`900000`	Rate limit window (15 min)
`RATE_LIMIT_MAX_REQUESTS`	`100`	Max requests per window
`CORS_ORIGIN`	`*`	CORS origin setting

Security Features

Helmet.js: Security headers
Rate Limiting: Prevents abuse
CORS: Configurable cross-origin requests
Session Timeout: Automatic session cleanup
Input Validation: Parameter validation for all tools
Error Sanitization: Safe error messages

Architecture

rezoomex/
├── server.js              # Main server file
├── lib/
│   ├── rezoomex-client.js  # Rezoomex API client
│   ├── auth-manager.js     # Authentication management
│   └── mcp-tools.js        # MCP tool definitions
├── logs/                   # Log files
├── package.json
├── .env.example
└── README.md

Troubleshooting

Common Issues

Authentication Failed
- Ensure bearer token is valid and not expired
- Check that you're using the correct login URL
- Verify the token was extracted correctly from the URL
Session Expired
- Re-authenticate using /auth/token endpoint
- Check session timeout settings
API Errors
- Verify project ID and persona ID are correct
- Check Rezoomex API status
- Review server logs for detailed error information
Connection Issues
- Ensure server is running on correct port
- Check firewall settings
- Verify network connectivity to Rezoomex API

Debug Mode

Set LOG_LEVEL=debug in your .env file for detailed logging.

License

MIT License - see LICENSE file for details.

Support

For issues and questions, please check the logs first and ensure your authentication is valid. The server provides detailed error messages to help diagnose problems.

Rezoomex MCP Server