Hello Service

A unified HTTP/HTTPS service built with Bun that provides both REST API endpoints and MCP (Model Context Protocol) functionality over SSE (Server-Sent Events).

Architecture

This service combines traditional REST API functionality with MCP capabilities in a single TypeScript/Bun server (server.ts). The MCP protocol, typically used for stdio communication between AI assistants and tools, is exposed through HTTP endpoints for remote access.

Key Components:

Bun Runtime: Fast JavaScript/TypeScript runtime for server-side applications
HTTP/HTTPS Server: Built-in Bun server with CORS support
MCP Integration: Model Context Protocol tools exposed via SSE (Server-Sent Events)
Systemd Integration: Production deployment with automatic restart and logging

Related MCP server: MCP Gateway

Features

HTTP and HTTPS support
CORS enabled for all origins
REST API endpoints
MCP tools exposed via SSE transport
Health check endpoint
Systemd service integration
TypeScript support
Fast startup and low memory footprint

API Endpoints

Standard API

GET /hello - Returns a JSON greeting message
GET /health - Health check endpoint
GET /info - Server capabilities and endpoints information

MCP-over-SSE API

GET /sse - SSE endpoint for MCP connections
POST /messages?sessionId=XXX - Send MCP protocol messages

Installation

Prerequisites

Install Bun if not already installed:

curl -fsSL https://bun.sh/install | bash

Clone the repository:

git clone <repository-url> cd hello-service-workspace

Install dependencies:

bun install

Running the Server

Development Mode

Run directly from the current directory:

# Run with default settings (HTTP on port 3000) bun server.ts # Or using npm npm start # Run with custom port PORT=8080 bun server.ts # Run with HTTPS SSL_KEY_PATH=certs/server.key SSL_CERT_PATH=certs/server.crt bun server.ts

Production Deployment

1. Prepare the System

Create a dedicated user for the service:

sudo useradd -r -s /bin/false hello-service

2. Deploy to /opt

# Create deployment directory sudo mkdir -p /opt/hello-service # Copy application files sudo cp server.ts package.json package-lock.json /opt/hello-service/ # Set ownership sudo chown -R hello-service:hello-service /opt/hello-service # Install dependencies sudo -u hello-service bash -c "cd /opt/hello-service && bun install"

3. Install Systemd Service

# Copy service file sudo cp hello-service.service /etc/systemd/system/ # Reload systemd sudo systemctl daemon-reload # Enable service to start on boot sudo systemctl enable hello-service # Start the service sudo systemctl start hello-service

4. Verify Deployment

# Check service status sudo systemctl status hello-service # Test the API curl http://localhost:3000/info | jq . # View logs sudo journalctl -u hello-service -f

Using the MCP Server

MCP Tools Available

The server provides the following MCP tool:

hello - Returns a greeting message with optional name parameter

Connecting with Claude Desktop

To use this MCP server with Claude Desktop, see the detailed setup guide: CLAUDE_DESKTOP_SETUP.md

Quick configuration example:

{ "mcpServers": { "hello-service": { "command": "npx", "args": [ "-y", "mcp-remote", "https://91.99.172.64:3000/sse" ], "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" } } } }

This configuration uses npx to run mcp-remote, which acts as a proxy between Claude Desktop's stdio transport and remote SSE servers.

Alternative: Direct SSE Connection Test

# Connect to SSE endpoint curl -N -H "Accept: text/event-stream" https://91.99.172.64:3000/sse # The server will respond with a session ID event

Configuration

Environment Variables

PORT - Server port (default: 3000)
SSL_KEY_PATH - Path to SSL private key file (for HTTPS)
SSL_CERT_PATH - Path to SSL certificate file (for HTTPS)
NODE_ENV - Environment mode (automatically set to "production" by systemd)

HTTPS Setup

Generate self-signed certificates (for development):

mkdir -p certs cd certs openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout server.key -out server.crt \ -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost" cd ..

For production with systemd, place certificates in /opt/hello-service/certs/ and update the service:

sudo systemctl edit hello-service

Add:

[Service] Environment="SSL_KEY_PATH=/opt/hello-service/certs/server.key" Environment="SSL_CERT_PATH=/opt/hello-service/certs/server.crt"

Service Management

Systemd Commands

# Start/Stop/Restart sudo systemctl start hello-service sudo systemctl stop hello-service sudo systemctl restart hello-service # Enable/Disable auto-start sudo systemctl enable hello-service sudo systemctl disable hello-service # Check status sudo systemctl status hello-service # View logs sudo journalctl -u hello-service -n 50 # Last 50 lines sudo journalctl -u hello-service -f # Follow logs sudo journalctl -u hello-service --since "1 hour ago"

Updating the Service

To deploy updates:

# Pull latest changes git pull # Copy updated files sudo cp server.ts package.json /opt/hello-service/ # Update dependencies if needed sudo -u hello-service bash -c "cd /opt/hello-service && bun install" # Restart service sudo systemctl restart hello-service

Testing

Quick Tests

# Test API endpoints curl http://localhost:3000/hello | jq . curl http://localhost:3000/health | jq . curl http://localhost:3000/info | jq . # Test SSE connection curl -N http://localhost:3000/sse

Using HTTPie (if installed)

# GET requests http :3000/info http :3000/hello http :3000/health

Troubleshooting

Service Won't Start

Check logs for errors:

sudo journalctl -u hello-service -n 100 --no-pager

Verify Bun is installed and accessible:

which bun bun --version

Check file permissions:

ls -la /opt/hello-service/

Test manually as service user:

sudo -u hello-service bash -c "cd /opt/hello-service && bun server.ts"

Port Already in Use

If you see EADDRINUSE error:

# Find process using port 3000 sudo lsof -i :3000 # Or change the port sudo systemctl edit hello-service # Add: Environment="PORT=3001"

Dependencies Issues

# Reinstall dependencies sudo rm -rf /opt/hello-service/node_modules sudo -u hello-service bash -c "cd /opt/hello-service && bun install"

Development Tools

The following tools are installed on the server for development and debugging:

jq - Command-line JSON processor
yq - Command-line YAML processor
httpie - User-friendly HTTP client
ripgrep (rg) - Fast text search
bat - Cat clone with syntax highlighting
fd - Fast file finder
tree - Directory structure viewer
htop - Interactive process viewer
ncdu - Disk usage analyzer

Security Considerations

The service runs as a dedicated non-privileged user (hello-service)
Systemd security settings restrict file system access
CORS is enabled for all origins (adjust for production)
Consider using a reverse proxy (nginx/caddy) for production
Use proper SSL certificates from Let's Encrypt for production

Contributing

Fork the repository
Create a feature branch
Make your changes
Test locally and with systemd
Submit a pull request

License

[Specify your license here]