qr-mcp-service

v2.3.0

Published

12 days ago

Model Context Protocol (MCP) service for QR code generation with stdio transport

0High
0Medium
0Low

qingtingnpm

mcp model-context-protocol qr-code qr ai api server stdio

QR Service

A Model Context Protocol (MCP) service implementation that can be used by AI models to generate QR codes. Now supports Server-Sent Events (SSE) for real-time web integration.

Features

QR code generation tool for AI models
MCP protocol compliant server
NEW MCP over Server-Sent Events (SSE) transport protocol
RESTful API endpoint
Easy deployment
Interactive web example

Getting Started

Prerequisites

Node.js (version 14 or higher)
npm

Installation

npm install

Running Locally

MCP Mode (Original)

npm start

MCP SSE Mode (New - MCP over SSE transport)

npm run dev-mcp-sse

Production MCP SSE Mode

npm run build-mcp-sse
npm run start-mcp-sse

SSE Mode (New - for web applications)

npm run dev-sse

Production SSE Mode

npm run build-sse
npm run start-sse

The service will be available at http://localhost:7997

Development Mode

npm run dev
npm run dev-sse

Running with npx (if installed globally or linked locally)

npx qr-service

Or if linked locally:

qr-service

MCP Endpoint

POST /mcp - Main MCP endpoint for AI model communication

MCP SSE Transport Endpoints

GET /mcp/sse - SSE endpoint for receiving MCP responses (establish connection)
POST /mcp/send - Send MCP requests (include X-Session-ID header)
GET / - Server information and usage instructions

SSE Endpoints

GET /events - Server-Sent Events endpoint for real-time updates
GET /example - Interactive web example with SSE integration
POST /mcp - Same MCP endpoint compatible with SSE mode

API Endpoints

GET / - Service information
GET /health - Health check endpoint

MCP over SSE Integration

The new MCP SSE transport allows MCP clients to communicate via Server-Sent Events instead of stdio:

Usage Pattern

Establish SSE Connection:

const sessionId = 'client-session-123';
const eventSource = new EventSource('/mcp/sse', {
  headers: { 'X-Session-ID': sessionId }
});
   
eventSource.onmessage = function(event) {
  const mcpMessage = JSON.parse(event.data);
  console.log('MCP Response:', mcpMessage);
};

Send MCP Requests:

async function sendMcpRequest(request) {
  const response = await fetch('/mcp/send', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Session-ID': sessionId
    },
    body: JSON.stringify(request)
  });
  return await response.json();
}
   
// Example: List available tools
sendMcpRequest({
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/list'
});

Generate QR Code:

sendMcpRequest({
  jsonrpc: '2.0',
  id: 2,
  method: 'tools/call',
  params: {
    name: 'generate_qr_code',
    arguments: {
      url: 'https://example.com',
      size: 200
    }
  }
});

MCP SSE Client Example

See mcp-sse-client-example.html for a complete working example of an MCP client using SSE transport.

Web Integration with SSE

The traditional SSE mode allows easy integration with web applications:

HTML Example

<!DOCTYPE html>
<html>
<head>
    <title>QR Code Generator</title>
</head>
<body>
    <div id="qr-result"></div>
    <div id="events"></div>
    
    <script>
        // Connect to SSE stream
        const eventSource = new EventSource('/events');
        
        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);
            if (data.type === 'qr_generated') {
                document.getElementById('qr-result').innerHTML = 
                    '<img src="' + data.data + '" alt="QR Code">';
            }
        };
        
        // Generate QR code
        async function generateQR(url, size) {
            const response = await fetch('/mcp', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    id: Date.now(),
                    method: 'tools/call',
                    params: {
                        name: 'generate_qr_code',
                        arguments: { url, size }
                    }
                })
            });
            return await response.json();
        }
    </script>
</body>
</html>

MCP Tools

generate_qr_code

Generates a QR code for a given URL.

Parameters:

url (string, required): The URL to encode in the QR code
size (integer, optional): Size of the QR code image (default: 200)

Example usage:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "generate_qr_code",
    "arguments": {
      "url": "https://www.baidu.com",
      "size": 300
    }
  }
}

Deployment

To deploy this service publicly:

Choose a hosting platform (cloud server, Heroku, Vercel, etc.)
Install Node.js on the server
Copy the project files to the server
Run npm install to install dependencies
Configure firewall to allow traffic on port 7997 (or your chosen port)
For MCP mode: Start the service with npm start
For SSE/Web mode: Start the service with npm run build-sse && npm run start-sse
(Optional) Set up a reverse proxy like Nginx for production use
(Optional) Configure a domain name pointing to your server

Environment Variables

PORT - Server port (default: 7997)
MCP_DEBUG - Enable MCP debug logging
SSE_DEBUG - Enable SSE debug logging

CORS Support

The SSE server includes CORS headers for cross-origin requests, making it easy to embed in any web application.