MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

Q
Quote MCP Server Simple
by @joydsilva
GitHub Repo(1 stars)

MCP server by joydsilva

Created 11/14/2025
Updated about 1 month ago
README
View Source
Repository documentation and setup instructions

Quote MCP Server Simple

A Model Context Protocol (MCP) server that provides health check and insurance quote creation tools. Now supports both stdio and Server-Sent Events (SSE) modes!

Features

  • Health Check Tool: Query any URL and get a detailed response including status, headers, and body content
  • Insurance Quote Creation: Create insurance quotes by submitting comprehensive quote data to the API
  • Error Handling: Comprehensive error handling for network issues, timeouts, and invalid data
  • Timeout Support: Configurable request timeout for both tools
  • Data Validation: Validates required fields and data structure for quote requests
  • Detailed Response: Returns status code, headers, response body, and timestamp
  • 🆕 SSE Support: Server-Sent Events for real-time communication
  • 🆕 Dual Mode: Run in traditional stdio mode or modern SSE mode

Installation

  1. Install dependencies:
npm install
  1. Install development dependencies (for SSE testing):
npm run install:dev

Usage

Running the Server

Traditional Stdio Mode (Default)

npm start

Or for development with auto-restart:

npm run dev

🆕 Server-Sent Events (SSE) Mode

npm run start:sse

Or with custom port:

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

For development with auto-restart:

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

Port Conflict Resolution: If you get an "EADDRINUSE" error, it means port 3000 is already in use (often by Docker, WSL, or other development servers). The server will automatically try the next available port, or you can use the alternate scripts above.

Check what's using a port:

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 Mode Endpoints

When running in SSE mode, the server provides these HTTP endpoints:

  • GET /sse: Server-Sent Events endpoint for MCP communication
  • GET /health: Server health check endpoint
  • POST /sse: Send MCP requests (JSON-RPC 2.0 format)

🆕 Testing SSE Mode

Web Browser Test Client

Open sse-test-client.html in your browser for a full-featured web interface:

# 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 Test Client

Run the automated test suite:

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

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

MCP Tool Usage

The server provides two tools:

health_check

Query a URL and return the response for health checking purposes.

Parameters:

  • url (optional): The URL to query for health check (default: "http://localhost:8080/api/v1/health")
  • timeout (optional): Request timeout in milliseconds (default: 5000, min: 1000, max: 30000)

Example Response:

{
  "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

Create an insurance quote by submitting comprehensive quote data to the API.

Parameters:

  • quote (required): Quote data object with the following structure:
    • created_date (required): Date when the quote was created (YYYY-MM-DD format)
    • expiration_date (required): Date when the quote expires (YYYY-MM-DD format)
    • quote_status (required): Current status of the quote (e.g., "Active")
    • locations (required): Array of location objects with:
      • address (required): Physical address
      • property_type (required): Type of property
      • square_footage (required): Total square footage
    • lines (required): Array of insurance line objects with:
      • line_type (required): Type of insurance line
      • policy_limit (required): Policy limit amount
      • deductible (required): Deductible amount
      • risks (required): Array of risk objects
  • timeout (optional): Request timeout in milliseconds (default: 10000)

Auto-Generated Fields: All ID fields ending with _id are automatically generated by the API if not provided:

  • quote_id: Format Q-YYYYMMDD-XXX
  • location_id: Format LOC-XXX
  • line_id: Format LINE-XXX
  • risk_id: Format RISK-XXX
  • coverage_id: Format COV-XXX

Example Quote Request:

{
  "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
              }
            ]
          }
        ]
      }
    ]
  }
}

Example Quote Response:

{
  "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
}

Error Response:

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

Integration with MCP Clients

This server can be integrated with any MCP-compatible client. The server communicates via stdio transport.

Claude Desktop Integration

Important: Claude Desktop uses stdio-based MCP connections, not HTTP/SSE. Use the default stdio mode for Claude Desktop.

To use this MCP server with Claude Desktop:

  1. Use stdio mode configuration (default):

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

  2. Configuration Location:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  3. Restart Claude Desktop to load the server

Note: Do NOT use SSE mode arguments in Claude Desktop configuration. SSE mode is for web browsers and HTTP clients only.

See CLAUDE_SETUP.md for detailed configuration instructions.

Cursor Integration

To use this MCP server with Cursor, add the following configuration to your Cursor settings:

  1. Option 1: Use the provided config file

    • Copy the contents of mcp-config.json to your Cursor MCP configuration
    • Or reference this server in your existing Cursor MCP settings

  2. Option 2: Manual configuration Add this to your Cursor settings JSON:

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

  3. Using the tools Once configured, you can use both tools naturally:

    • Health check: "Can you check if the API is healthy?"
    • Quote creation: "Create an insurance quote for a commercial building..."

See CURSOR_SETUP.md for detailed configuration instructions.

🆕 Server-Sent Events (SSE) Mode Details

SSE Communication Protocol

The SSE mode implements the MCP protocol over HTTP using Server-Sent Events for server-to-client communication and HTTP POST for client-to-server requests.

Client-to-Server (HTTP POST to /sse)

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

Server-to-Client (SSE Messages)

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

SSE Mode Benefits

  1. Web Browser Compatibility: Works directly in web browsers without special setup
  2. Real-time Communication: Immediate server responses via SSE
  3. CORS Support: Built-in CORS headers for web applications
  4. HTTP Debugging: Easy to debug with standard HTTP tools
  5. Scalable: Can handle multiple concurrent SSE connections

Development vs Production

  • Development: Use npm run dev:sse for auto-restart on file changes
  • Production: Use npm run start:sse for stable operation
  • Custom Port: Use node index.js sse <port> to specify a different port

Integration Examples

JavaScript/Browser

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();

Troubleshooting

Common Issues

  1. SSE Connection Fails

    • Ensure server is running in SSE mode: npm run start:sse
    • If port 3000 is in use, try: npm run start:sse:alt (port 3001)
    • Check what's using the port: npm run check-port
    • Find next available port: npm run find-port
    • Common port conflicts: Docker, WSL, other development servers

  2. EADDRINUSE Error

    • Port is already in use by another process
    • The server will attempt to use the next port automatically
    • Use alternate scripts: npm run start:sse:alt or npm run start:sse:port
    • Check processes: netstat -ano | findstr :3000

  3. CORS Errors in Browser

    • The server includes CORS headers, but ensure you're not running into local security restrictions
    • Try accessing the test client from the same origin

  4. stdio Mode vs SSE Mode

    • Default npm start runs in stdio mode (for MCP clients like Claude)
    • Use npm run start:sse for web/HTTP access
    • These are different modes and cannot be used simultaneously

Development

The server is built using the Model Context Protocol SDK and provides:

  • URL validation
  • Network error handling
  • Request timeout management
  • Structured response format

📊 Architecture Documentation

Comprehensive PlantUML diagrams are available in the repository:

  • mcp-flow-diagram.puml - Main interaction flow between client, server, and API
  • quote-data-flow.puml - Detailed quote creation sequence diagram
  • architecture-diagram.puml - Component architecture and system overview
  • state-diagram.puml - Tool execution state machine

See DIAGRAMS.md for detailed information about viewing and using these diagrams.

📁 Project Structure

├── 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

License

MIT

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-quote_mcp_server_simple

Cursor configuration (mcp.json)

{ "mcpServers": { "joydsilva-quote-mcp-server-simple": { "command": "npx", "args": [ "joydsilva-quote-mcp-server-simple" ] } } }