# RZMX MCP Server

OAuth2-enabled Model Context Protocol (MCP) server for Rezoomex that provides seamless IDE integration with project data, user stories, personas, and project management information.

## Features

- **OAuth2 Authentication**: Seamless "connect button" experience with Windsurf and Cursor IDEs
- **SSE Transport**: Real-time Server-Sent Events for MCP communication
- **JSON-RPC Support**: Direct tool calls via HTTP POST endpoints
- **Comprehensive Tools**: 26+ tools for project management, user stories, and persona analysis
- **IDE Integration**: Native support for Windsurf and Cursor IDEs

## Quick Start

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Configure environment:**
   ```bash
   cp .env.oauth.example .env.oauth
   # Edit .env.oauth with your settings
   ```

3. **Start the server:**
   ```bash
   node mcp-server-rezoomex-oauth.js
   ```

4. **Configure your IDE:**
   Add to Windsurf MCP config:
   ```json
   {
     "mcpServers": {
       "rzmx": {
         "url": "http://localhost:3000/v1/sse"
       }
     }
   }
   ```

## OAuth2 Flow

The server provides OAuth2 endpoints for IDE integration:

- `GET /authorize` - Authorization endpoint with login form
- `POST /authenticate` - Credential authentication
- `GET /callback` - OAuth2 callback handler
- `POST /token` - Token exchange endpoint

## MCP Endpoints

- `GET /v1/sse` - SSE transport for real-time MCP communication
- `POST /v1/sse` - JSON-RPC endpoint for direct tool calls

## Available Tools

### Core Project Tools
- `list_user_stories` - List user stories for project and persona
- `get_user_story` - Get specific user story details
- `get_projects` - Get all accessible projects
- `get_project_overview` - Comprehensive project information
- `get_persona_profile` - Detailed persona analysis

### Advanced Tools
- `get_story_range` - Get multiple stories by range
- `get_user_journey` - User journey mapping
- `get_jobs_to_be_done` - JTBD analysis
- `search_projects` - Project search functionality
- `find_project_by_name` - Project discovery by name

### User Management
- `get_user_info` - Authenticated user profile
- `check_nda_status` - NDA compliance status

*And 15+ additional tools for comprehensive project management*

## Environment Configuration

```bash
# .env.oauth
NODE_ENV=development
PORT=3000
BASE_URI=http://localhost:3000
REZOOMEX_BASE_URL=https://awsapi-gateway.rezoomex.com
REZOOMEX_LOGIN_URL=https://workspace.rezoomex.com/account/login
LOG_LEVEL=info
```

## Architecture

```
├── lib/
│   ├── auth-manager.js     # Authentication management
│   ├── mcp-tools.js        # 26+ tool definitions
│   └── rezoomex-client.js  # Rezoomex API client
├── views/
│   ├── dashboard.html      # OAuth dashboard
│   └── index.html          # Server info page
├── mcp-server-rezoomex-oauth.js  # Main OAuth MCP server
├── server.js               # Legacy HTTP server
└── windsurf_mcp_config_oauth.json  # IDE configuration
```

## Development

The server supports both SSE transport and direct JSON-RPC calls, making it compatible with various MCP clients and IDEs.

### Adding Tools

1. Add tool definition to `lib/mcp-tools.js`
2. Implement logic in the tool's `callTool` method
3. Tools are automatically available in both SSE and JSON-RPC endpoints

## Deployment

The server can be deployed to any Node.js hosting platform. See `DEPLOYMENT.md` for detailed deployment instructions.

## License

Proprietary to Rezoomex.
curl http://localhost:3000/auth/login-url
```

Response:
```json
{
  "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."
}
```

### Step 2: Login and Extract Bearer Token

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

### Step 3: Authenticate with Server

```bash
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:
```json
{
  "success": true,
  "sessionId": "your-session-id",
  "message": "Authentication successful. Use this session ID for subsequent requests.",
  "expiresIn": "24 hours"
}
```

## API Endpoints

### Health Check
```bash
GET /health
```

### Authentication
```bash
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
```bash
GET /mcp/tools                         # List available tools
GET /mcp/execute/:toolName             # Execute tool via SSE
POST /mcp/execute/:toolName            # Execute tool via POST

```bash
# 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

```bash
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

```bash
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
```bash
npm run dev
```

### Run Tests
```bash
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

1. **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

2. **Session Expired**
   - Re-authenticate using `/auth/token` endpoint
   - Check session timeout settings

3. **API Errors**
   - Verify project ID and persona ID are correct
   - Check Rezoomex API status
   - Review server logs for detailed error information

4. **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.