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

1. Install Bun if not already installed:

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

2. Clone the repository:

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

3. 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

1. 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 ..

2. 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

1. Check logs for errors:

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

2. Verify Bun is installed and accessible:

which bun
bun --version

3. Check file permissions:

ls -la /opt/hello-service/

4. 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

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Test locally and with systemd

5. Submit a pull request

License

[Specify your license here]