Opus MCP Server

# Opus MCP Server Model Context Protocol (MCP) server for the Opus Job Operator API. This server provides tools to programmatically interact with Opus workflows, including job initiation, execution, monitoring, and file uploads. > **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) for 3-minute setup! > **Installation**: See [INSTALL.md](INSTALL.md) for detailed instructions > **Distribution**: See [DISTRIBUTION.md](DISTRIBUTION.md) for sharing options ## Features - **Workflow Management**: Get workflow details and schemas - **Job Operations**: Initiate, execute, and monitor jobs - **File Handling**: Generate presigned URLs for secure file uploads - **Monitoring**: Check job status, retrieve results, and view audit logs ## Installation 1. Install dependencies: ```bash npm install ``` 2. Build the project: ```bash npm run build ``` 3. Set up environment variables: ```bash cp .env.example .env # Edit .env and add your OPUS_SERVICE_KEY ``` ## Getting Your API Key 1. Navigate to the Opus platform 2. Click **My Organization** at the top 3. Click the **gear icon** next to your Organization's name 4. Select **API Keys** from the settings menu 5. Click **+ Generate API Key** 6. Copy the key (shown only once) and add to `.env` file ## Configuration ### For Claude Desktop Add to your Claude Desktop config file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "opus": { "command": "node", "args": ["/absolute/path/to/function1 hackathon/build/index.js"], "env": { "OPUS_SERVICE_KEY": "your_service_key_here" } } } } ``` ### For Other MCP Clients Use the built executable with environment variable: ```bash OPUS_SERVICE_KEY=your_key node build/index.js ``` ## Available Tools ### 1. get_workflow_details Get workflow details including the `jobPayloadSchema` that defines required inputs. **Parameters**: - `workflowId` (string, required): The workflow ID from Opus **Returns**: Full workflow details including schema, execution estimation, and input requirements ### 2. initiate_job Create a new job instance for a workflow. **Parameters**: - `workflowId` (string, required): The workflow ID - `title` (string, required): Job title - `description` (string, required): Job description **Returns**: `jobExecutionId` needed for subsequent operations ### 3. generate_file_upload_url Generate presigned URLs for secure file uploads. **Parameters**: - `fileExtension` (string, required): File extension with dot (e.g., `.pdf`, `.jpeg`, `.png`, `.docx`) - `accessScope` (string, optional): Access scope - `all`, `user`, `workspace`, or `organization` (default) **Returns**: - `presignedUrl`: Use for uploading file via PUT request - `fileUrl`: Use this URL in job execution payload **Supported File Types**: .jpeg, .png, .jpg, .pdf, .docx, .csv, .xls, .xlsx, .txt, .json, .html, .xml ### 4. execute_job Execute a job with populated input values. **Parameters**: - `jobExecutionId` (string, required): From `initiate_job` response - `jobPayloadSchemaInstance` (object, required): Job inputs structured according to workflow schema **Example jobPayloadSchemaInstance**: ```json { "workflow_input_we4tej0ly": { "value": "API Test Project", "type": "str" }, "workflow_input_a0hk6ujuo": { "value": 45.8, "type": "float" }, "workflow_input_h69vx5i4a": { "value": "https://files.opus.com/media/private/uploaded/media_file.pdf", "type": "file" } } ``` ### 5. get_job_status Check current job execution status. **Parameters**: - `jobExecutionId` (string, required): The job ID **Returns**: Status - `IN PROGRESS`, `COMPLETED`, or `FAILED` ### 6. get_job_results Retrieve results from a completed job. **Parameters**: - `jobExecutionId` (string, required): The job ID **Returns**: Job results including output files and data (only works when status is `COMPLETED`) ### 7. get_job_audit_log Get detailed audit log of job execution. **Parameters**: - `jobExecutionId` (string, required): The job ID **Returns**: Timestamped log of all system actions ## Workflow Example ``` 1. Get workflow details to understand required inputs → get_workflow_details(workflowId: "B9uGJfZ3CFwOdMKH") 2. (If needed) Generate file upload URLs → generate_file_upload_url(fileExtension: ".pdf") → Upload file to presignedUrl using PUT request 3. Initiate a job → initiate_job(workflowId, title, description) → Save jobExecutionId 4. Execute the job with inputs → execute_job(jobExecutionId, jobPayloadSchemaInstance) 5. Monitor status → get_job_status(jobExecutionId) 6. Get results when complete → get_job_results(jobExecutionId) 7. (Optional) View audit log → get_job_audit_log(jobExecutionId) ``` ## Development Watch mode for development: ```bash npm run watch ``` ## API Documentation For complete API details, see the markdown files in the root directory: - `opus-00-get-workflow-details.md` - Workflow schema retrieval - `opus-03-initiate-job.md` - Job initiation - `opus-04-uploading-files-for-job-inputs.md` - File uploads - `opus-05-execute-job.md` - Job execution - `opus-06-get-job-execution-status.md` - Status monitoring - `opus-07-get-job-execution-results.md` - Results retrieval - `opus-08-job-audit-log.md` - Audit logs ## Base URL All requests are made to: `https://operator.opus.com` ## Troubleshooting **Error: OPUS_SERVICE_KEY environment variable is required** - Ensure your `.env` file exists with the correct key, or - Set the environment variable in your MCP client configuration **Error: Authentication failed** - Verify your service key is valid and not expired - Check that the key has proper permissions in Opus **File upload issues** - Ensure file extension matches the actual file type - Use PUT request without authentication headers for presigned URL - Verify file size limits (if any) in Opus documentation ## License MIT