@ionhour/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# @ionhour/mcp-server
+
+Connect AI assistants to your [IonHour](https://ionhour.com) uptime monitoring workspace using the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Start
+
+```bash
+# Set your API key
+export IONHOUR_API_KEY=ionh_your_key_here
+
+# Run with npx (no install needed)
+npx @ionhour/mcp-server
+```
+
+## Setup with AI Assistants
+
+### Claude Code
+
+```bash
+claude mcp add ionhour -- npx @ionhour/mcp-server
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ionhour": {
+      "command": "npx",
+      "args": ["@ionhour/mcp-server"],
+      "env": {
+        "IONHOUR_API_KEY": "ionh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ionhour": {
+      "command": "npx",
+      "args": ["@ionhour/mcp-server"],
+      "env": {
+        "IONHOUR_API_KEY": "ionh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "ionhour": {
+      "command": "npx",
+      "args": ["@ionhour/mcp-server"],
+      "env": {
+        "IONHOUR_API_KEY": "ionh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Getting an API Key
+
+1. Go to your IonHour workspace **Settings > API Keys**
+2. Create a new key with **Read & Write** or **Read Only** permission
+3. Copy the key (starts with `ionh_`)
+
+## Available Tools
+
+### Workspace
+- `get_workspace` - Get workspace details
+- `get_workspace_summary` - Overview of projects, checks, and incidents
+- `get_workspace_reliability` - Uptime, incident count, and MTTR metrics
+- `list_team_members` - List workspace members and roles
+- `send_invitation` - Invite users to the workspace
+
+### Projects
+- `list_projects` / `create_project` / `update_project`
+
+### Checks (Monitors)
+- `register_check` - Create a new monitoring check
+- `list_checks` / `list_checks_by_status` / `find_check_by_name`
+- `get_check_status` - Detailed status with recent signals
+- `get_check_uptime` - Uptime percentage with daily buckets
+- `pause_check` / `resume_check`
+
+### Signals (Heartbeats)
+- `send_heartbeat` - Send a success signal
+- `send_failure_signal` - Report a failure
+- `list_signals` - View signal history
+
+### Incidents
+- `list_incidents` / `search_incidents` / `get_incident`
+- `get_incident_timeline` - Incident history for a check
+- `create_incident` / `acknowledge_incident` / `resolve_incident`
+- `add_incident_note`
+
+### Deployments
+- `create_deployment` - Start a deployment window (auto-pauses checks)
+- `end_deployment` - End deployment and resume checks
+- `list_deployments`
+
+### Dependencies
+- `list_dependencies` / `get_dependency` / `create_dependency`
+- `update_dependency_status`
+
+### Status Pages & Alerts
+- `list_status_pages` / `create_status_page` / `update_status_page`
+- `create_announcement`
+- `list_alert_channels` / `create_alert_channel` / `update_alert_channel`
+- `list_escalation_rules` / `create_escalation_rule` / `update_escalation_rule`
+
+## CLI Options
+
+```
+npx @ionhour/mcp-server [options]
+
+Options:
+  --api-key KEY     IonHour API key (or set IONHOUR_API_KEY env var)
+  --base-url URL    API base URL (default: https://app.failsignal.com)
+  --help, -h        Show help
+```
+
+## How It Works
+
+This package runs a local MCP server over **stdio** that proxies requests to the IonHour API. Your AI assistant communicates with this local server, which forwards tool calls to your IonHour workspace.
+
+```
+AI Assistant <--stdio--> @ionhour/mcp-server <--HTTPS--> IonHour API
+```
+
+## Requirements
+
+- Node.js >= 18
+- An IonHour account with an API key
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ionhour/mcp-server",
+  "version": "0.1.0",
+  "description": "IonHour MCP Server -- connect AI assistants to your uptime monitoring workspace",
+  "license": "MIT",
+  "bin": {
+    "ionhour-mcp": "./src/bin.js"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ionhour",
+    "monitoring",
+    "uptime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ionhour/ionhour",
+    "directory": "libs/mcp-server"
+  },
+  "homepage": "https://ionhour.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0"
+  },
+  "module": "./src/index.js"
+}

package/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/bin.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { startProxyServer, resolveConfig } from './index.js';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--api-key' && args[i + 1]) {
+            result.apiKey = args[++i];
+        }
+        else if (args[i] === '--base-url' && args[i + 1]) {
+            result.baseUrl = args[++i];
+        }
+        else if (args[i] === '--help' || args[i] === '-h') {
+            process.stderr.write(`
+IonHour MCP Server v0.1.0
+
+Connect AI assistants to your IonHour monitoring workspace.
+
+Usage:
+  npx @ionhour/mcp-server [options]
+
+Options:
+  --api-key KEY     IonHour API key (or set IONHOUR_API_KEY env var)
+  --base-url URL    IonHour API base URL (default: https://app.failsignal.com)
+  --help, -h        Show this help message
+
+Setup with Claude Code:
+  claude mcp add ionhour -- npx @ionhour/mcp-server
+
+Environment Variables:
+  IONHOUR_API_KEY       API key for authentication
+  IONHOUR_BASE_URL      Base URL override
+`);
+            process.exit(0);
+        }
+    }
+    return result;
+}
+async function main() {
+    try {
+        const args = parseArgs();
+        const config = resolveConfig(args);
+        await startProxyServer(config);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=bin.js.map

package/src/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../../../libs/mcp-server/src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,WAAW,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC3C,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,YAAY,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACnD,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;CAmB1B,CAAC,CAAC;YACG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACrE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+export interface IonHourMcpConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+/**
+ * Resolve configuration from explicit overrides, environment variables, or defaults.
+ * Throws if no API key is available from any source.
+ */
+export declare function resolveConfig(overrides?: Partial<IonHourMcpConfig>): IonHourMcpConfig;
+/**
+ * Start the stdio-to-HTTP MCP proxy server.
+ *
+ * 1. Connects to the remote IonHour MCP endpoint as a client
+ * 2. Exposes an MCP server over stdio
+ * 3. Proxies all tool/resource/prompt requests to the remote endpoint
+ */
+export declare function startProxyServer(config: IonHourMcpConfig): Promise<void>;

package/src/index.js

@@ -0,0 +1,115 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Resolve configuration from explicit overrides, environment variables, or defaults.
+ * Throws if no API key is available from any source.
+ */
+export function resolveConfig(overrides) {
+    const apiKey = overrides?.apiKey || process.env['IONHOUR_API_KEY'];
+    if (!apiKey) {
+        throw new Error('IonHour API key is required. Set IONHOUR_API_KEY environment variable or pass --api-key flag.');
+    }
+    return {
+        apiKey,
+        baseUrl: overrides?.baseUrl ||
+            process.env['IONHOUR_BASE_URL'] ||
+            'https://app.failsignal.com',
+    };
+}
+/**
+ * Create an MCP Client connected to the remote IonHour API endpoint.
+ */
+async function createRemoteClient(config) {
+    const transport = new StreamableHTTPClientTransport(new URL(`${config.baseUrl}/mcp`), {
+        requestInit: {
+            headers: {
+                Authorization: `Bearer ${config.apiKey}`,
+            },
+        },
+    });
+    const client = new Client({ name: 'ionhour-mcp-proxy', version: '0.1.0' });
+    await client.connect(transport);
+    return client;
+}
+/**
+ * Start the stdio-to-HTTP MCP proxy server.
+ *
+ * 1. Connects to the remote IonHour MCP endpoint as a client
+ * 2. Exposes an MCP server over stdio
+ * 3. Proxies all tool/resource/prompt requests to the remote endpoint
+ */
+export async function startProxyServer(config) {
+    let remoteClient;
+    try {
+        remoteClient = await createRemoteClient(config);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`Failed to connect to IonHour API at ${config.baseUrl}/mcp: ${message}\n`);
+        process.exit(1);
+    }
+    const server = new Server({ name: 'ionhour', version: '0.1.0' }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // Proxy tools/list
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const result = await remoteClient.listTools();
+        return { tools: result.tools };
+    });
+    // Proxy tools/call
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await remoteClient.callTool({
+            name: request.params.name,
+            arguments: request.params.arguments,
+        });
+        return result;
+    });
+    // Proxy resources/list
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        try {
+            const result = await remoteClient.listResources();
+            return { resources: result.resources };
+        }
+        catch {
+            return { resources: [] };
+        }
+    });
+    // Proxy resources/read
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const result = await remoteClient.readResource({
+            uri: request.params.uri,
+        });
+        return result;
+    });
+    // Proxy prompts/list
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        try {
+            const result = await remoteClient.listPrompts();
+            return { prompts: result.prompts };
+        }
+        catch {
+            return { prompts: [] };
+        }
+    });
+    // Proxy prompts/get
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const result = await remoteClient.getPrompt({
+            name: request.params.name,
+            arguments: request.params.arguments,
+        });
+        return result;
+    });
+    // Connect local server to stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr so stdout remains clean for MCP JSON-RPC protocol
+    process.stderr.write('IonHour MCP server started (stdio proxy mode)\n');
+}
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/mcp-server/src/index.ts"],"names":[],"mappings":"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"}