使用说明

报价MCP服务器简单

提供健康检查和保险报价创建工具的模型上下文协议（MCP）服务器。 现在支持stdio和服务器发送事件（SSE）模式！

特性

健康检查工具：查询任何URL并获得详细的响应，包括状态、标题和正文内容
保险报价创建：通过向API提交综合报价数据来创建保险报价
错误处理：针对网络问题、超时和无效数据的全面错误处理
超时支持：两种工具的可配置请求超时
数据验证：验证报价请求的必填字段和数据结构
详细回复：返回状态代码、标头、响应正文和时间戳
🆕 SSE支持：服务器发送事件以进行实时通信
🆕 双模式：以传统stdio模式或现代SSE模式运行

安装

安装依赖项：

npm install

安装开发依赖项（用于SSE测试）：

npm run install:dev

用法

运行服务器

传统标准模式（默认）

npm start

或者用于自动重启的开发：

npm run dev

🆕 服务器发送事件（SSE）模式

npm run start:sse

或者使用自定义端口：

npm run start:sse:alt     # Uses port 3001
npm run start:sse:port    # Uses port 3002
# OR
node index.js sse 4000    # Custom port

对于自动重启的开发：

npm run dev:sse           # Port 3000
npm run dev:sse:alt       # Port 3001

端口冲突解决：如果您收到“EADDRINUSE”错误，则表示端口3000已在使用中（通常由Docker、WSL或其他开发服务器使用）。服务器将自动尝试下一个可用端口，或者您可以使用上面的备用脚本。

检查端口的使用情况：

npm run check-port        # Check port 3000
node check-ports.js check 3001  # Check port 3001
npm run find-port         # Find next available port

🆕 SSE模式端点

在SSE模式下运行时，服务器提供以下HTTP端点：

GET /sse：MCP通信的服务器发送事件端点
GET /health：服务器健康检查终结点
POST /sse：发送MCP请求（JSON-RPC 2.0格式）

🆕 测试SSE模式

Web浏览器测试客户端

打开 sse-test-client.html 在浏览器中查看功能齐全的web界面：

# Start the server
npm run start:sse

# Open sse-test-client.html in your browser
# Navigate to http://localhost:3000/health to verify server is running

Node.js测试客户端

运行自动化测试套件：

# In one terminal, start the server
npm run start:sse

# In another terminal, run the test client
npm run test:sse

MCP工具使用

服务器提供两个工具：

`health_check`

查询URL并返回响应以进行健康检查。

参数：

url （可选）：查询健康检查的URL（默认值：“http://localhost:8080/api/v1/health")
timeout （可选）：请求超时（毫秒）（默认值：5000，最小值：1000，最大值：30000）

示例响应：

{
  "url": "http://localhost:8080/api/v1/health",
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "text/html; charset=UTF-8",
    "content-length": "1256"
  },
  "body": "<!DOCTYPE html>...",
  "timestamp": "2025-10-22T10:30:00.000Z",
  "success": true
}

`create_insurance_quote`

通过向API提交综合报价数据来创建保险报价。

参数：

quote （必填）：引用具有以下结构的数据对象：
- created_date （必填）：创建报价的日期（YYYY-MM-DD格式）
- expiration_date （必填）：报价到期日期（YYYY-MM-DD格式）
- quote_status （必填）：报价的当前状态（例如“活动”）
- locations （必填）：位置对象数组，包含：
  - address （必填）：实际地址
  - property_type （必填）：物业类型
  - square_footage （必填）：总建筑面积
- lines （必填）：保险线对象数组，包含：
  - line_type （必填）：保险额度类型
  - policy_limit （必填）：保单限额金额
  - deductible （必填）：免赔额
  - risks （必填）：风险对象数组
timeout （可选）：请求超时（毫秒）（默认值：10000）

自动生成的字段： 所有以结尾的ID字段 _id 如果未提供，则由API自动生成：

quote_id：格式 Q-YYYYMMDD-XXX
location_id：格式 LOC-XXX
line_id：格式 LINE-XXX
risk_id：格式 RISK-XXX
coverage_id：格式 COV-XXX

报价请求示例：

{
  "quote": {
    "created_date": "2025-10-22",
    "expiration_date": "2026-10-22",
    "quote_status": "Active",
    "locations": [
      {
        "address": "123 Main Street, New York, NY 10001",
        "property_type": "Commercial Building",
        "square_footage": 50000
      }
    ],
    "lines": [
      {
        "line_type": "Property Insurance",
        "policy_limit": 5000000,
        "deductible": 10000,
        "risks": [
          {
            "risk_type": "Fire",
            "location_reference": "LOC-001",
            "risk_description": "Fire damage to commercial building structure and contents",
            "coverages": [
              {
                "coverage_type": "Building",
                "coverage_limit": 3000000
              },
              {
                "coverage_type": "Contents",
                "coverage_limit": 2000000
              }
            ]
          }
        ]
      }
    ]
  }
}

报价响应示例：

{
  "url": "http://localhost:8080/api/v1/quotes",
  "status": 200,
  "statusText": "OK",
  "response_data": {
    "quote": {
      "quote_id": "Q-20251022-001",
      "created_date": "2025-10-22",
      "total_premium": 125000.75,
      "quote_status": "Active",
      "expiration_date": "2026-10-22",
      "locations": [...],
      "lines": [...]
    }
  },
  "timestamp": "2025-10-22T10:30:00.000Z",
  "success": true
}

错误响应：

{
  "url": "https://invalid-url.example",
  "error": "DNS resolution failed for https://invalid-url.example",
  "timestamp": "2025-10-22T10:30:00.000Z",
  "success": false
}

与MCP客户端集成

此服务器可以与任何兼容MCP的客户端集成。服务器通过stdio传输进行通信。

Claude桌面集成

重要：Claude Desktop使用基于stdio的MCP连接，而不是HTTP/SSE。使用Claude Desktop的默认stdio模式。

要将此MCP服务器与Claude Desktop一起使用：

使用stdio模式配置 （默认）：

{
  "mcpServers": {
    "quote-health-check": {
      "command": "node",
      "args": ["c:\\POC\\quote_mcp_server_simple\\index.js"],
      "env": {}
    }
  }
}

配置位置：
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux： ~/.config/Claude/claude_desktop_config.json
重新启动克劳德桌面 加载服务器

备注：不要在Claude Desktop配置中使用SSE模式参数。SSE模式仅适用于web浏览器和HTTP客户端。

看 CLAUDE_SETUP.md 了解详细的配置说明。

光标集成

要将此MCP服务器与Cursor一起使用，请将以下配置添加到Cursor设置中：

选项1：使用提供的配置文件
- 复制以下内容 mcp-config.json 到您的Cursor MCP配置
- 或者在现有的Cursor MCP设置中引用此服务器

选项2：手动配置 将此添加到您的游标设置JSON中：

{
  "mcpServers": {
    "quote-health-check": {
      "command": "node",
      "args": ["index.js"],
      "cwd": "c:\\POC\\quote_mcp_server_simple",
      "env": {}
    }
  }
}

使用工具 配置后，您可以自然地使用这两个工具：
- 健康检查：“你能检查API是否健康吗？”
- 报价创建：“为商业建筑创建保险报价…”

看 CURSOR_SETUP.md 了解详细的配置说明。

🆕 服务器发送事件（SSE）模式详细信息

SSE通信协议

SSE模式通过HTTP实现MCP协议，使用服务器发送事件进行服务器到客户端的通信，使用HTTP POST进行客户端到服务器的请求。

客户端到服务器（HTTP POST到/sse）

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

服务器到客户端（SSE消息）

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

SSE模式优势

Web浏览器兼容性：无需特殊设置即可直接在web浏览器中工作
实时通信：通过SSE即时服务器响应
CORS支持：用于web应用程序的内置CORS标头
HTTP调试：使用标准HTTP工具易于调试
可扩展的：可以处理多个并发SSE连接

开发vs生产

发展：使用 npm run dev:sse 用于在文件更改时自动重新启动
生产：使用 npm run start:sse 稳定运行
自定义端口：使用 node index.js sse <port> 指定其他端口

集成示例

JavaScript/浏览器

const eventSource = new EventSource('http://localhost:3000/sse');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

// Send request
fetch('http://localhost:3000/sse', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/list",
    params: {}
  })
});

Node.js

import { MCPSSEClient } from './test-sse-client.js';

const client = new MCPSSEClient('http://localhost:3000');
await client.connect();
await client.listTools();
await client.healthCheck('https://example.com');
client.disconnect();

故障排除

常见问题

SSE连接失败
- 确保服务器在SSE模式下运行： npm run start:sse
- 如果端口3000正在使用中，请尝试： npm run start:sse:alt （端口3001）
- 检查端口的使用情况： npm run check-port
- 查找下一个可用端口： npm run find-port
- 常见端口冲突：Docker、WSL、其他开发服务器
EADDRINUSE错误
- 端口已被其他进程使用
- 服务器将尝试自动使用下一个端口
- 使用备用脚本： npm run start:sse:alt 或 npm run start:sse:port
- 检查流程： netstat -ano | findstr :3000
浏览器中的CORS错误
- 服务器包含CORS标头，但请确保您没有遇到本地安全限制
- 尝试从同一源访问测试客户端
stdio模式与SSE模式
- 默认 npm start 在stdio模式下运行（适用于Claude等MCP客户端）
- 使用 npm run start:sse 用于web/HTTP访问
- 这些是不同的模式，不能同时使用

发展

服务器使用模型上下文协议SDK构建，并提供：

URL验证
网络错误处理
请求超时管理
结构化响应格式

📊 架构文档

存储库中提供了全面的PlantUML图：

mcp-flow-diagram.puml -客户端、服务器和API之间的主要交互流程
quote-data-flow.puml -详细的报价创建顺序图
architecture-diagram.puml -组件架构和系统概述
state-diagram.puml -刀具执行状态机

看 DIAGRAMS.md 有关查看和使用这些图表的详细信息。

📁 项目结构

├── index.js                    # Main MCP server implementation (stdio + SSE)
├── package.json                # Project dependencies and scripts
├── sample-quote.json           # Example quote data structure
├── test-server.js              # Server testing script
├── 🆕 sse-test-client.html      # Web browser SSE test interface
├── 🆕 test-sse-client.js        # Node.js SSE test client and library
├── 🆕 check-ports.js            # Port checker utility for troubleshooting
├── README.md                   # Main documentation
├── DIAGRAMS.md                 # PlantUML diagrams documentation
├── CURSOR_SETUP.md             # Cursor configuration instructions
├── CLAUDE_SETUP.md             # Claude Desktop configuration instructions
├── mcp-config.json             # Cursor MCP configuration
├── claude-mcp-config.json      # Claude Desktop MCP configuration
├── cursor-mcp-config.json      # Alternative Cursor configuration
├── cursor-user-settings.json   # Cursor user settings template
├── mcp-flow-diagram.puml       # Main flow diagram
├── quote-data-flow.puml        # Quote creation sequence
├── architecture-diagram.puml   # System architecture
├── state-diagram.puml          # Execution states
└── .vscode/                    # VS Code workspace settings
    └── settings.json

许可证

麻省理工学院