cody-docker/opine-mcp-server

Opine MCP Server

A Model Context Protocol (MCP) server for querying deals, evaluations, and tickets from the Opine CRM API.

Features

• List Deals: Query deals with filtering options
• Get Deal: Retrieve specific deal details by ID
• List Evaluations: Query evaluations with pagination
• List Tickets: Query tickets/requests with pagination

Installation

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

Configuration

Set your Opine API key as an environment variable:

export OPINE_API_KEY="your-api-key-here"

Usage

Running the Server

npm start

For development:

npm run dev

Docker

Building the Docker Image

# Build the Docker image
npm run docker:build

# Or use docker directly
docker build -t opine-mcp-server .

Running with Docker

# Run the container with your API key
npm run docker:run

# Or use docker directly
docker run -e OPINE_API_KEY="your-api-key" -i opine-mcp-server

Publishing to DockerHub

To publish your own version to DockerHub:

# Tag the image with your DockerHub username
docker tag opine-mcp-server your-username/opine-mcp-server:latest
docker tag opine-mcp-server your-username/opine-mcp-server:1.0.0

# Push to DockerHub (requires docker login)
docker push your-username/opine-mcp-server:latest
docker push your-username/opine-mcp-server:1.0.0

Using Pre-built Image

A pre-built image is available on DockerHub:

# Pull and run the pre-built image
docker pull codygreen719/opine-mcp-server:latest
docker run -e OPINE_API_KEY="your-api-key" -i codygreen719/opine-mcp-server:latest

Testing with MCP Inspector

The MCP Inspector provides a web-based interface to test your MCP server. There are two ways to use it:

Method 1: Direct Server Testing

npm run inspector

This will build the server and launch the inspector directly against the built server.

Method 2: Using Configuration File

# First, update mcp-config.json with your API key
npm run inspector:config

Before using the inspector, make sure to:

1. Set your OPINE_API_KEY in the environment or update mcp-config.json
2. Build the project with npm run build

The inspector will open a web interface where you can:

• View available tools (list_deals, get_deal, list_evaluations, list_tickets)
• Test tool calls with different parameters
• See real-time responses from the Opine API
• Debug any authentication or API issues

MCP Tools

The server provides the following tools:

list_deals

List deals from Opine CRM with optional parameters:

• limit (optional): Number of results (1-1000, default: 100)
• offset (optional): Number of results to skip (default: 0)
• includeSummary (optional): Include AI-generated deal summary
• includeDeleted (optional): Include deleted deals

get_deal

Get a specific deal by ID:

• id (required): Deal ID (Opine ID or external service ID)
• includeSummary (optional): Include AI-generated deal summary

list_evaluations

List evaluations with optional parameters:

• limit (optional): Number of results (1-1000, default: 100)
• offset (optional): Number of results to skip (default: 0)

list_tickets

List tickets/requests with optional parameters:

• limit (optional): Number of results (1-1000, default: 100)
• offset (optional): Number of results to skip (default: 0)

API Requirements

This server requires:

• A valid Opine API key
• The following API scopes:
  • deals:read for deal operations
  • evaluations:read for evaluation operations
  • tickets:read for ticket operations

Docker Security

This project uses hardened Docker images for enhanced security:

• Build Stage: demonstrationorg/dhi-node:24.7-alpine3.22-dev (hardened with build tools)
• Runtime Stage: demonstrationorg/dhi-node:24.7-alpine3.22 (minimal hardened runtime)

The multi-stage build ensures:

• Minimal attack surface in production
• No build tools or source code in final image
• Hardened base images with security patches
• Non-root user execution

Error Handling

The server handles API errors and provides meaningful error messages. Common issues:

• Missing or invalid API key
• Insufficient API scopes
• Network connectivity issues
• Invalid request parameters