service-mcp

v1.2.0

Published

2 months ago

MCP Hub & Notification Center — the only MCP server an AI agent needs

0High
0Medium
0Low

mcp model-context-protocol ai agent notification hub daemon cli

 ____  _____ ______     _____ ____ _____
/ ___|| ____|  _ \ \   / /_ _/ ___| ____|
\___ \|  _| | |_) \ \ / / | | |   |  _|
 ___) | |___|  _ < \ V /  | | |___| |___
|____/|_____|_| \_\ \_/  |___\____|_____|

  MCP Hub & Notification Center

The only MCP server your AI agent needs.

AI agents today juggle a dozen MCP servers: one for GitHub, one for the filesystem, one for search, one for Slack. Every restart, every new project, every new agent has to re-configure all of them. SERVICE solves this. It's a persistent 24/7 background daemon that aggregates all your downstream MCP servers into one unified connection — and layers on a real-time notification gateway so your agents can receive events from X/Twitter, Slack, Email, and webhooks the moment they happen.

One connection. All your tools. Always on.

Why SERVICE?

🔌 Single MCP endpoint for everything — Claude Desktop, Cursor, Copilot, and any MCP client connect to one URL (http://localhost:3333/mcp) and instantly get all tools from all your downstream servers, namespaced cleanly (github__create_issue, filesystem__read_file, etc.)
⚡ Real-time push, not polling — integrations like Slack, Email, X/Twitter, and webhooks stream events to your agents the moment they arrive via SSE, so agents can react in real-time without burning tokens on polling loops
🔒 Local-first and private — all data lives in ~/.service/service.db (SQLite), credentials are AES-256-GCM encrypted, nothing leaves your machine unless you configure it to
🧩 Plugin-style integrations — add new integrations via a CLI wizard or the REST API; no rebuild required

Architecture

AI Agent (Claude Desktop / Cursor / Copilot / any MCP client)
              │
              │  Single MCP connection (Streamable HTTP)
              ▼
┌─────────────────────────────────────────────────────────────┐
│                      SERVICE DAEMON                         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            MCP Hub  ·  port 3333                      │  │
│  │  Aggregates & proxies tools from all downstream MCPs  │  │
│  │  Namespaced tools: github__create_issue, etc.         │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Notification Gateway  ·  port 3334               │  │
│  │  24/7 listener for all integrations                   │  │
│  │  SQLite persistence + SSE push to agents              │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Integration System  (plugin-based)               │  │
│  │  X/Twitter · Slack · Email · Webhooks · HTTP-poll     │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │      Interactive TUI Dashboard  (Ink v6)              │  │
│  │  Notification Center · Integration Manager ·          │  │
│  │  MCP Manager · Full keyboard navigation               │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │                              │
    ┌────┘                              └──────────────────┐
    ▼                                                      ▼
Downstream MCPs (stdio)                      External Platforms
github, filesystem, memory,          X/Twitter, Slack, Email,
brave-search, any MCP server         Webhook, HTTP-poll, custom

Quickstart

# 1. Install globally
npm install -g service-mcp

# 2. Start the daemon
service start

# 3. Add your AI client config (see below)

# 4. Add integrations interactively
service integration add

# 5. Watch it live
service dashboard

Ports: 3333 — MCP Hub (agents connect here) · 3334 — Admin API + SSE stream

Connect Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "service": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Cursor

Edit your Cursor MCP settings (~/.cursor/mcp.json or via Settings → MCP):

{
  "mcpServers": {
    "service": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

Any stdio-compatible client

{
  "mcpServers": {
    "service": {
      "command": "npx",
      "args": ["service-mcp", "mcp-server"]
    }
  }
}

CLI Reference

Daemon Lifecycle

| Command | Description | |---|---| | service start | Start the SERVICE daemon in the background | | service stop | Gracefully stop the daemon | | service status | Show daemon status (uptime, ports, integrations, MCPs) |

Integration Management

| Command | Description | |---|---| | service integration list | List all configured integrations and their status | | service integration add [type] | Add a new integration via interactive wizard | | service integration remove <id> | Permanently remove an integration | | service integration enable <id> | Re-enable a disabled integration | | service integration disable <id> | Disable without removing |

MCP Connection Management

| Command | Description | |---|---| | service mcp list | List all downstream MCP connections | | service mcp add [name] [command] [args...] | Add a downstream MCP server (interactive wizard if no args) | | service mcp remove <id> | Disconnect and remove a downstream MCP |

Utilities

| Command | Description | |---|---| | service dashboard | Open the interactive TUI dashboard (full-screen Ink v6 app) | | service completion <shell> | Generate shell completion script (bash/zsh/fish) | | service update | Check for and install newer versions from npm | | service --help | Show help for all commands | | service --version | Show installed version |

Interactive TUI Dashboard

The service dashboard command launches a full-screen, keyboard-driven terminal UI built on Ink v6 (React for CLI — the same framework powering Claude Code and Gemini CLI). It provides complete management of notifications, integrations, and MCP connections without leaving the terminal.

Navigation

| Key | Action | |---|---| | Tab | Cycle between panes (Live Feed → Integrations → MCPs → System) | | ↑/↓ or j/k | Navigate lists | | Enter | Open detail view for selected item | | Escape | Go back to previous screen | | q | Quit dashboard | | ? | Show/hide keyboard shortcut help overlay | | r | Refresh current pane |

Notification Center

Manage all notifications in real-time:

Real-time updates: New notifications appear instantly via SSE push — no polling
Visual indicators: ● unread (bold) vs ○ read (dimmed)
Mark as read: Space marks selected notification, A marks all as read
Filter: u toggles unread-only view
Search: / opens inline full-text search (FTS5)
Detail view: Enter shows full notification body, source, type, and timestamp

Integration Manager

View, configure, and manage all integrations:

Status badges: 🟢 active / 🔴 error / ⏸ disabled (color-coded)
Detail view: Shows config fields with secrets redacted as ••••••
Enable/Disable: e/d keys toggle integration state
Remove: x key with confirmation dialog
Add new: a opens in-TUI multi-step form with type selection, schema-driven fields, and password masking for secret fields

MCP Connection Manager

Manage all downstream MCP server connections:

Status badges: 🟢 connected / 🔴 error / ⏳ connecting, with tool count display
Detail view: Full command + args, status, and scrollable tool list
Reconnect: r key triggers reconnect for disconnected MCPs
Remove: x key with confirmation dialog
Add new: a opens in-TUI form for name, command, and args

MCP Tool Reference

All built-in SERVICE tools are prefixed with service__. Downstream MCP tools are namespaced as {mcpName}__toolName (e.g. github__create_issue).

Notifications

| Tool | Parameters | Description | |---|---|---| | service__get_notifications | limit?, source? | Get recent notifications with optional filters | | service__get_unread_count | — | Count of unread notifications | | service__mark_notification_read | id | Mark a specific notification as read | | service__search_notifications | query | Full-text search across notification history |

Agent Memory

| Tool | Parameters | Description | |---|---|---| | service__save_note | key, value | Save a persistent key-value note | | service__get_note | key | Retrieve a note by key | | service__list_notes | — | List all saved note keys | | service__delete_note | key | Delete a note by key |

MCP Management

| Tool | Parameters | Description | |---|---|---| | service__connect_mcp | name, command, args? | Add a downstream MCP at runtime | | service__disconnect_mcp | id | Remove a downstream MCP connection | | service__list_connected_mcps | — | List all active downstream MCP connections |

System

| Tool | Parameters | Description | |---|---|---| | service__service_status | — | Daemon health: uptime, version, integration count | | service__help | — | Formatted guide of all available tools |

Platform Tools (Auto-registered from Integrations)

When integrations are active, their tools are automatically registered and available to your agents:

| Integration | Tools | |---|---| | X / Twitter | x__tweet, x__reply, x__retweet, x__like, x__search_tweets | | Slack | slack__send_message, slack__list_channels, slack__get_thread, slack__react | | Email | email__send_email, email__list_emails, email__read_email, email__reply_email | | HTTP-poll | httpPoll__fetch_now |

Integration Setup

Webhook

The simplest integration — receives HTTP POST requests and converts them to notifications.

service integration add webhook --name my-webhook
# Returns webhook URL: http://localhost:3334/webhooks/<integration-id>

Send events from any external system:

curl -X POST http://localhost:3334/webhooks/<id> \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy Complete", "body": "v2.1.0 deployed to production"}'

X / Twitter

Requires a Twitter API v2 bearer token. Optional: keyword tracking.

service integration add x
# Wizard prompts for:
#   bearer_token     — Twitter API v2 bearer token
#   track_keywords   — (optional) comma-separated keywords to monitor

Slack

Requires a Slack Bot Token with Socket Mode enabled.

service integration add slack
# Wizard prompts for:
#   bot_token   — xoxb-... (Bot User OAuth Token)
#   app_token   — xapp-... (App-Level Token for Socket Mode)

Scopes required: channels:read, chat:write, reactions:write, channels:history

Email (SMTP + IMAP)

Monitors your inbox via IMAP and sends email via SMTP. Works with Gmail, Outlook, Fastmail, and any standard mail server.

service integration add email
# Wizard prompts for:
#   imap_host, imap_port   — e.g. imap.gmail.com:993
#   smtp_host, smtp_port   — e.g. smtp.gmail.com:587
#   user, password         — your email credentials (stored encrypted)

Tip for Gmail: Enable "App Passwords" in your Google Account security settings.

HTTP Poll

Polls a URL on a schedule and creates a notification whenever the content changes.

service integration add http-poll
# Wizard prompts for:
#   url               — endpoint to poll
#   interval_seconds  — polling interval (e.g. 60)
#   method            — GET or POST

Admin REST API

SERVICE exposes a full REST API on port 3334 for programmatic management and automation:

| Endpoint | Method | Description | |---|---|---| | /health | GET | Health check — returns {"status":"ok"} | | /api/status | GET | Full daemon status (uptime, version, counts) | | /api/notifications | GET | List notifications (?unread, ?source, ?limit) | | /api/notifications/:id/read | PATCH | Mark a notification as read | | /api/integrations | GET | List all configured integrations | | /api/integrations | POST | Create a new integration | | /api/integrations/:id | DELETE | Remove an integration | | /api/integrations/types | GET | List all available integration types | | /api/mcp-connections | GET | List downstream MCP connections | | /api/mcp-connections | POST | Add a downstream MCP server | | /api/mcp-connections/:id | DELETE | Remove a downstream MCP | | /events | GET | SSE stream — real-time notification events | | /webhooks/:id | POST | Inbound webhook receiver |

SSE Event Stream

Subscribe to real-time events:

curl -N http://localhost:3334/events

Events are JSON-encoded NotificationEvent objects pushed as they arrive.

Data Storage

All data is stored locally on your machine. Nothing is sent to external servers unless you configure an integration.

| Path | Purpose | |---|---| | ~/.service/service.db | SQLite database — notifications, integrations, notes | | ~/.service/config.json | Daemon configuration | | ~/.service/service.pid | Daemon PID file | | ~/.service/state.json | Runtime state (connected agents, uptime) | | ~/.service/logs/ | Rotating log files | | ~/.service/.encryption_key | Auto-generated AES-256-GCM encryption key for credentials |

Credentials stored in integrations are encrypted at rest using AES-256-GCM. The encryption key is generated once on first run and stored at ~/.service/.encryption_key.

Examples

See the examples/ directory for ready-to-use configs:

| File | Description | |---|---| | claude-desktop-config.json | Full Claude Desktop configuration | | cursor-mcp-config.json | Cursor editor MCP config | | mcp-connections.json | Sample downstream MCP connections (github, filesystem, brave) | | webhook-integration.sh | Shell script for sending webhook events |

Requirements

| Requirement | Version | |---|---| | Node.js | ≥ 20.0.0 | | npm | ≥ 9.0.0 | | OS | macOS, Linux, Windows (WSL2) |

Development

# Clone and install
git clone https://github.com/baiehclaca/service-mcp.git
cd service-mcp
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Development mode (watch + auto-reload)
npm run dev

# Lint
npm run lint

Adding a Custom Integration

Every integration implements the IntegrationAdapter interface:

interface IntegrationAdapter {
  id: string
  name: string
  description: string
  configSchema: JSONSchema          // Fields the wizard will prompt for
  connect(config: Record<string, string>): Promise<void>
  disconnect(): Promise<void>
  onEvent(handler: (event: NotificationEvent) => void): void
  getTools(): MCPTool[]             // Tools exposed to agents
}