@dashtray/mcp-server 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# Dashtray MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Model Context Protocol server for [Dashtray](https://dashtray.app) - send notifications to your phone from AI agents, build scripts, and automation tools.
+
+## Features
+
+- **Single, focused tool:** `send_notification` - send alerts to your phone
+- **No preset management:** Notifications are automatically logged in history
+- **Auto-prefixed:** All notifications prefixed with "MCP - " for clarity
+- **Rate-limited:** Per-plan limits (Starter 100/min, Pro 1000/min)
+- **Secure:** SHA256-hashed API keys, bearer token auth
+- **Lightweight:** Minimal dependencies, ~30KB bundle
+
+## Installation
+
+### Option 1: From npm
+
+```bash
+npm install @dashtray/mcp-server
+# or run directly:
+npx @dashtray/mcp-server
+```
+
+## Setup
+
+### 1. Get Your API Key
+
+1. Open **Dashtray** on your phone
+2. Go to **Settings → Integrations → API Keys**
+3. Tap **Generate New Key**
+4. Give it a name (e.g., "Claude Desktop")
+5. **Copy the full key** (starts with `sk_test_`)
+6. Save it securely - you won't see it again
+
+### 2. Set Environment Variables
+
+Create a `.env` file or export in your shell:
+
+```bash
+export DASHTRAY_API_KEY="sk_test_your_key_here"
+export DASHTRAY_API_ENDPOINT="https://api.dashtray.app"  # Optional, uses default if omitted
+```
+
+### 3. Configure Your Agent
+
+#### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "dashtray": {
+      "command": "npx",
+      "args": ["-y", "@dashtray/mcp-server"],
+      "env": {
+        "DASHTRAY_API_KEY": "sk_test_your_key_here",
+        "DASHTRAY_API_ENDPOINT": "https://api.dashtray.app"
+      }
+    }
+  }
+}
+```
+Then restart Claude Desktop.
+
+#### Cline
+
+In your project's `.cline/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dashtray": {
+      "command": "npx",
+      "args": ["-y", "@dashtray/mcp-server"],
+      "env": {
+        "DASHTRAY_API_KEY": "sk_test_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Custom Agents
+
+Start the server and connect via stdio:
+
+```javascript
+import { ChildProcess, spawn } from "child_process";
+
+const server = spawn("node", ["/path/to/dashtray/packages/mcp-server/dist/index.js"], {
+  env: {
+    ...process.env,
+    DASHTRAY_API_KEY: "sk_test_your_key_here",
+  },
+});
+
+// Connect to server via server.stdio
+```
+
+## Usage
+
+### Send a Notification
+
+```typescript
+// The send_notification tool accepts:
+{
+  "title": "Build Passed",        // Required: notification title (max 200 chars)
+  "body": "Production build #42 completed in 3m 21s"  // Required: details (max 500 chars)
+}
+```
+
+### Examples
+
+**Build Alert:**
+```
+Title: Build Failed
+Body: Docker image build failed. Error: unauthorized. Check credentials.
+```
+
+**Deployment Status:**
+```
+Title: Deployment Complete
+Body: App v1.2.3 deployed to production. 50 instances running, health check passed.
+```
+
+**Test Results:**
+```
+Title: Tests Passed
+Body: All 342 tests passed. Coverage: 87%. Duration: 2m 15s.
+```
+
+**Long-Running Task:**
+```
+Title: Analysis Complete
+Body: Dataset processed. 1.2M records. Anomalies: 3. Report: https://...
+```
+
+## API Reference
+
+### Tool: `send_notification`
+
+**Description:** Send a notification to your Dashtray account. Notifications appear on your phone with "MCP - " prefix and are logged in history.
+
+**Inputs:**
+| Field | Type | Required | Max Length | Notes |
+|-------|------|----------|-----------|-------|
+| `title` | string | Yes | 200 | Notification title. Auto-prefixed with "MCP - " |
+| `body` | string | Yes | 500 | Notification details/body |
+
+**Outputs:**
+```json
+{
+  "success": true,
+  "message": "Notification sent successfully!\n\nTitle: Build Passed\nBody: ...\n\nIt will appear on your phone with the \"MCP - \" prefix..."
+}
+```
+
+**Errors:**
+- `DASHTRAY_API_KEY not set` - Missing environment variable
+- `Invalid input: title is required` - Missing or empty title
+- `Invalid input: body must be 500 chars or less` - Body too long
+- `API error: 401 Unauthorized` - Invalid API key
+- `API error: 429 Too Many Requests` - Rate limit exceeded
+- `API error: 500 Internal Server Error` - Server error
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DASHTRAY_API_KEY` | Yes | - | API key from Dashtray app |
+| `DASHTRAY_API_ENDPOINT` | No | https://api.dashtray.app | Dashtray API URL (self-hosted or cloud) |
+
+### API Key Format
+
+All keys are generated with the `sk_test_` prefix followed by 48 hex characters, regardless of plan.
+
+## Rate Limiting
+
+Notifications are rate-limited per-plan:
+
+| Plan | Limit | Window |
+|------|-------|--------|
+| Starter | 100/min | Fixed 1-minute window |
+| Pro | 1000/min | Fixed 1-minute window |
+
+When rate limit is exceeded, the API returns `429 Too Many Requests`.
+
+## Troubleshooting
+
+### "DASHTRAY_API_KEY environment variable is not set"
+
+**Solution:** Set the environment variable in your shell or config file.
+
+```bash
+export DASHTRAY_API_KEY="sk_test_..."
+```
+
+### "API error: 401 Unauthorized"
+
+**Solution:** Check your API key:
+1. Open Dashtray app
+2. Go to Settings → Integrations → API Keys
+3. Verify the key is still active (hasn't been revoked)
+4. Generate a new key if needed
+
+### "API error: 429 Too Many Requests"
+
+**Solution:** You've hit your rate limit for this plan. Either:
+- Wait a minute and retry
+- Upgrade your plan in the app
+- Batch notifications together
+
+### "Failed to send notification: ECONNREFUSED"
+
+**Solution:** Check that:
+1. `DASHTRAY_API_ENDPOINT` is correct
+2. The endpoint is reachable from your network
+3. No firewall is blocking the connection
+
+### Tool not appearing in Claude Desktop
+
+**Solution:**
+1. Restart Claude Desktop completely
+2. Check `claude_desktop_config.json` is valid JSON
+3. Verify Node 18+ is installed (`node --version`) so `npx` can fetch the server
+
+### "Invalid input: title is required"
+
+**Solution:** The title must be a non-empty string:
+
+```typescript
+// ❌ Wrong
+send_notification({ body: "Only body" })
+
+// ✓ Right
+send_notification({ title: "Alert", body: "Details" })
+```
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run watch
+```
+
+### Manual Testing
+
+```bash
+export DASHTRAY_API_KEY="sk_test_..."
+node dist/index.js
+```
+
+Then send a test request (requires MCP client like Claude Desktop).
+
+## Support
+
+- **Dashtray App Issues:** Settings → Help & Support
+- **MCP Server Issues:** support@dashtray.app
+- **API Questions:** See [API Reference](https://docs.dashtray.app/api-reference/overview)
+
+## License
+
+MIT
+
+---
+
+**Dashtray MCP Server** - Minimal, focused, production-ready.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Dashtray MCP Server
+ *
+ * Model Context Protocol server that provides a single tool:
+ * - send_notification: Send notifications to your phone via Dashtray
+ *
+ * Usage:
+ *   - Local (stdio): node dist/index.js
+ *   - Environment: Set DASHTRAY_API_KEY and DASHTRAY_API_ENDPOINT
+ *
+ * Configuration:
+ *   - Get API key from: Dashtray app → Settings → Integrations → API Keys
+ *   - Default endpoint: https://api.dashtray.app (or self-hosted)
+ *
+ * SDK notes (matches @modelcontextprotocol/sdk >= 1.x):
+ *   - `Server` from `server/index.js`; the stdio transport lives in
+ *     `server/stdio.js` and request schemas/types in `types.js`.
+ *   - Handlers register against the exported request SCHEMAS (validated
+ *     end-to-end by the SDK), not string method names.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Dashtray MCP Server
+ *
+ * Model Context Protocol server that provides a single tool:
+ * - send_notification: Send notifications to your phone via Dashtray
+ *
+ * Usage:
+ *   - Local (stdio): node dist/index.js
+ *   - Environment: Set DASHTRAY_API_KEY and DASHTRAY_API_ENDPOINT
+ *
+ * Configuration:
+ *   - Get API key from: Dashtray app → Settings → Integrations → API Keys
+ *   - Default endpoint: https://api.dashtray.app (or self-hosted)
+ *
+ * SDK notes (matches @modelcontextprotocol/sdk >= 1.x):
+ *   - `Server` from `server/index.js`; the stdio transport lives in
+ *     `server/stdio.js` and request schemas/types in `types.js`.
+ *   - Handlers register against the exported request SCHEMAS (validated
+ *     end-to-end by the SDK), not string method names.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+/**
+ * Dashtray Notification Schema
+ * Matches POST /api/v1/notifications/send endpoint
+ */
+// Limits match the backend's validateNotificationInput (title 1–200,
+// body 1–500) exactly - rejecting early with a clear message beats letting
+// the API 400 with a generic validation error.
+const NotificationSchema = z.object({
+    title: z
+        .string()
+        .min(1, "Title is required")
+        .max(200, "Title must be 200 chars or less"),
+    body: z
+        .string()
+        .min(1, "Body is required")
+        .max(500, "Body must be 500 chars or less"),
+    source: z
+        .string()
+        .min(1)
+        .max(40, "Source must be 40 chars or less")
+        .optional(),
+});
+/**
+ * Get API credentials from environment
+ */
+function getApiCredentials() {
+    const apiKey = process.env.DASHTRAY_API_KEY;
+    if (!apiKey) {
+        throw new Error("DASHTRAY_API_KEY environment variable is not set. " +
+            "Get it from: Dashtray app → Settings → Integrations → API Keys");
+    }
+    const endpoint = process.env.DASHTRAY_API_ENDPOINT || "https://api.dashtray.app";
+    return { apiKey, endpoint };
+}
+/**
+ * Send notification to Dashtray
+ */
+async function sendNotification(notification, apiKey, endpoint) {
+    const url = `${endpoint}/api/v1/notifications/send`;
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({
+                title: notification.title,
+                body: notification.body,
+                source: notification.source,
+            }),
+        });
+        if (!response.ok) {
+            const errorData = (await response.json().catch(() => ({})));
+            return {
+                ok: false,
+                error: `API error: ${response.status} ${response.statusText}. ${errorData.error || ""}`,
+            };
+        }
+        const data = (await response.json());
+        return {
+            ok: true,
+            data: data.data || { ...notification, id: "sent", createdAt: Date.now() },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `Failed to send notification: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * MCP Server Main
+ */
+async function main() {
+    const { apiKey, endpoint } = getApiCredentials();
+    const server = new Server({
+        name: "dashtray",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Define the send_notification tool
+    const sendNotificationTool = {
+        name: "send_notification",
+        description: "Send a notification to your Dashtray account. " +
+            "Notifications appear on your phone with 'MCP - ' prefix and are also logged in history. " +
+            "Perfect for build alerts, deployment updates, workflow notifications, etc.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Short notification title (max 200 chars). Will be prefixed with 'MCP - ' in the app.",
+                    examples: [
+                        "Build Complete",
+                        "Deployment Failed",
+                        "Test Suite Passed",
+                    ],
+                },
+                body: {
+                    type: "string",
+                    description: "Notification body/details (max 500 chars). Can include status, error details, links, etc.",
+                    examples: [
+                        "Build succeeded in 2m 15s. Ready to deploy.",
+                        "E2E tests failed on 3 files. See logs for details.",
+                    ],
+                },
+                source: {
+                    type: "string",
+                    description: "Name of the app/integration that sent this (max 40 chars, e.g. 'OpenCode', 'CI'). " +
+                        "Notifications with the same source are grouped under one alert named 'MCP - <source>' in the app. " +
+                        "Omit to group on the generic 'MCP & API' alert.",
+                },
+            },
+            required: ["title", "body"],
+        },
+    };
+    // Register tools/list handler (schema-based, per current SDK contract)
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [sendNotificationTool],
+        };
+    });
+    // Handle tool calls
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (request.params.name !== "send_notification") {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown tool: ${request.params.name}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            // Validate input
+            const args = request.params.arguments;
+            const validated = NotificationSchema.parse({
+                title: args.title,
+                body: args.body,
+            });
+            // Send to Dashtray
+            const result = await sendNotification(validated, apiKey, endpoint);
+            if (!result.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error sending notification: ${result.error}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Success response
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Notification sent successfully!\n\nTitle: ${result.data?.title}\nBody: ${result.data?.body}\n\nIt will appear on your phone with the "MCP - " prefix and also be logged in your Dashtray history.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof z.ZodError
+                ? `Invalid input: ${error.issues.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")}`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Start server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Dashtray MCP Server started");
+    console.error(`Using endpoint: ${endpoint}`);
+    console.error("Listening on stdio...");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@dashtray/mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.1",
+  "description": "Dashtray MCP Server - send notifications to your phone via MCP agents",
+  "type": "module",
+  "bin": {
+    "dashtray-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node dist/index.js",
+    "watch": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "notifications",
+    "dashtray",
+    "agents"
+  ],
+  "author": "Dashtray",
+  "license": "MIT",
+  "homepage": "https://dashtray.app",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }