Opine MCP Server

Opine MCP服务器

模型上下文协议（MCP）服务器，用于从Opine CRM API查询交易、评估和票据。

特性

• 列出优惠：查询处理筛选选项
• 达成交易：按ID检索特定交易详细信息（Opine ID或Salesforce ID）
• 列表评估：带分页的查询评估
• 列出门票：查询带分页的票证/请求
• 列表注释：使用可选交易筛选器查询备注
• 销售流程工具：查询和丰富销售流程和阶段元数据的交易
• 创建票证：创建新票
• 更新工单：更新现有票
• 创建交易记录：为交易添加注释

安装

1. 克隆此仓库
2. 安装依赖项：

   npm install

1. 构建服务器：

   npm run build

配置

将您的Opine API密钥设置为环境变量：

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

用法

运行服务器

npm start

发展：

npm run dev

码头工人

构建Docker镜像

# Build the Docker image
npm run docker:build

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

使用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

# Test MCP Server
npx @modelcontextprotocol/inspector -- docker run -e OPINE_API_KEY="your_api_key" -i  --rm opine-mcp-server

发布到DockerHub

要构建多架构映像（linux/amd64和linux/arm64）并将其发布到您自己的DockerHub帐户：

1. 在环境变量中设置DockerHub用户名：

   export DOCKERHUB_USERNAME="your-dockerhub-username"

1. 请确保您已登录DockerHub：

   docker login

1. 构建并推送多拱形图像（标签 latest 和电流 package.json version），只需一个命令：

   npm run docker:build:multiarch

此命令使用 DOCKERHUB_USERNAME 作为图像前缀（例如， "$DOCKERHUB_USERNAME"/opine-mcp-server:latest)并为amd64和arm64推送多架构清单。

您可以选择覆盖默认标记(latest 和电流 package.json 版本），通过设置逗号分隔 TAGS 环境变量，例如：

export TAGS="latest,1.0.5"

使用预构建图像

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

MCP检验员测试

MCP检查器提供了一个基于web的界面来测试您的MCP服务器。有两种方法可以使用它：

方法1：直接服务器测试

npm run inspector

这将构建服务器，并直接对构建的服务器启动检查器。

方法2：使用配置文件

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

在使用检查器之前，请确保：

1. 设置您的 OPINE_API_KEY 在环境中或更新 mcp-config.json
2. 用以下方式构建项目 npm run build

检查员将打开一个web界面，您可以在其中：

• 查看所有可用工具
• 具有不同参数的测试工具调用
• 查看Opine API的实时响应
• 调试任何身份验证或API问题

MCP工具

服务器提供以下工具：

阅读工具

list_deals

使用可选参数列出Opine CRM中的交易：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）
• includeSummary （可选）：包括AI生成的交易摘要
• includeDeleted （可选）：包括已删除的交易

每笔交易还包括 salesProcessId 和 salesProcessStageId 字段可用时，可以通过下面的销售流程工具解决。

get_deal

按ID获取特定交易：

• id （必填）：交易ID（Opine ID或外部服务ID）
• includeSummary （可选）：包括AI生成的交易摘要

get_salesforce_deal

通过Salesforce机会ID获取特定交易。自动规范15或18个字符的Salesforce ID，并在前面添加 eid: 前缀：

• id （必填）：Salesforce交易ID（15或18个字符）
• includeSummary （可选）：包括AI生成的交易摘要

list_evaluations

列出带有可选参数的评估：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）

list_tickets

列出带有可选参数的票/请求：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）

list_notes

列出带有可选参数的注释（必需 notes:read 范围）：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）
• dealId （可选）：使用Opine数字ID按交易筛选或 eid:-前缀供应商实体ID

list_sales_processes

列出Opine中配置的销售流程：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）

list_sales_process_stages

列出Opine的销售流程阶段：

• limit （可选）：结果数量（1-1000，默认值：100）
• offset （可选）：要跳过的结果数（默认值：0）
• includeDeleted （可选）：包括已删除的阶段

describe_deal_sales_process

获取单个交易及其销售过程的丰富视图：

• id （必填）：交易ID。如果这是Salesforce ID（15或18个字符），请设置 isSalesforceId 真的。
• isSalesforceId （可选）：治疗 id 作为Salesforce ID，并使用normalize+前缀 eid:.
• includeSummary （可选）：在获取交易时包含AI生成的交易摘要

回应包括原始交易（ salesProcessId/salesProcessStageId)加上已解决 salesProcess 和 salesProcessStage 元数据（如果可用）。

编写工具

create_ticket

在Opine中创建新票证（需要 tickets:write 范围）：

• title （必填）：门票标题（1-256个字符）
• type （必填）：门票类型-BUG、FEATURE、CUSTOM_1、CUSTOM_2、CUSTOM_3、CUSTOM_4、CUSTOM_5
• state （必填）：票证状态-打开、优先级、路线图、已防御、IN_PROGRESS、已关闭
• description （可选）：票证描述（Slate节点数组或markdown字符串）
• targetDueDate （可选）：ISO 8601格式的目标截止日期
• deals （可选）：交易关联数组 id 和 priority （拦截器/重要/NICE_TO_HAVE）
• labels （可选）：标签字符串数组
• vendorEntityUrl （可选）：URI格式的供应商实体URL

update_ticket

在Opine中更新现有票证（需要 tickets:write 范围）：

• id （必填）：要更新的工单ID
• title （可选）：门票标题（1-256个字符）
• type （可选）：门票类型-BUG、FEATURE、CUSTOM_1、CUSTOM_2、CUSTOM_3、CUSTOM_4、CUSTOM_5
• state （可选）：票证状态-打开、优先级、路线图、已防御、IN_PROGRESS、已关闭
• description （可选）：票证描述（Slate节点数组、标记字符串或清除null）
• targetDueDate （可选）：ISO 8601格式的目标截止日期（可空）
• deals （可选）：交易关联数组 id, priority （阻塞/重要/NICE_TO_HAVE），可选 delete 旗帜
• labels （可选）：区分大小写的标签字符串数组（替换所有现有标签，如果为空，则清除）
• vendorEntityUrl （可选）：URI格式的供应商实体URL（可以为空）

create_deal_note

在特定交易中添加注释（需要 deals:write 范围）：

• dealId （必填）：交易ID（Opine ID或外部服务ID）
• title （必填）：备注标题（最多512个字符）
• body （可选）：注释体（Slate节点数组或markdown字符串）

API要求

此服务器需要：

• 有效的Opine API密钥
• 以下API作用域：

Docker安全

该项目使用强化的Docker镜像来增强安全性：

• 构建阶段: demonstrationorg/dhi-node:24.7-alpine3.22-dev （用构建工具硬化）
• 运行阶段: demonstrationorg/dhi-node:24.7-alpine3.22 （最小强化运行时间）

多阶段构建可确保：

• 生产中的最小攻击面
• 最终图像中没有构建工具或源代码
• 带有安全补丁的强化基础图像
• 非root用户执行

错误处理

服务器处理API错误并提供有意义的错误消息。常见问题：

• API密钥丢失或无效
• API作用域不足
• 网络连接问题
• 无效的请求参数