@crontinel/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harun R Rayhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+# @crontinel/mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@crontinel/mcp-server)](https://www.npmjs.com/package/@crontinel/mcp-server)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/crontinel/mcp-server/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/crontinel/mcp-server)](https://github.com/crontinel/mcp-server)
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects AI assistants to [Crontinel](https://crontinel.com), the background job monitoring platform for Laravel. It runs as a local stdio process, proxying tool calls from your AI assistant to the Crontinel REST API.
+
+Ask your AI assistant questions like "Did my cron jobs run last night?" or "What's the queue depth right now?" and get answers inline, without opening a browser.
+
+## Requirements
+
+- Node.js 18+
+- A Crontinel account with an API key ([app.crontinel.com](https://app.crontinel.com))
+
+## Installation
+
+```bash
+npx -y @crontinel/mcp-server
+```
+
+Or install globally:
+
+```bash
+npm install -g @crontinel/mcp-server
+```
+
+## Configuration
+
+### Claude Code
+
+Add to `~/.claude/settings.json` (or use the Claude Code settings UI):
+
+```json
+{
+  "mcpServers": {
+    "crontinel": {
+      "command": "npx",
+      "args": ["-y", "@crontinel/mcp-server"],
+      "env": {
+        "CRONTINEL_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` or the project-level `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "crontinel": {
+      "command": "npx",
+      "args": ["-y", "@crontinel/mcp-server"],
+      "env": {
+        "CRONTINEL_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `CRONTINEL_API_KEY` | Yes | n/a | Your Crontinel API key |
+| `CRONTINEL_API_URL` | No | `https://app.crontinel.com` | Override the API base URL (self-hosted or local dev) |
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `list_scheduled_jobs` | List all monitored cron commands with last run status |
+| `get_cron_status` | Last run details for a specific command (exit code, duration, output) |
+| `get_queue_status` | Depth, failed count, and wait time for queues |
+| `get_horizon_status` | Horizon supervisor health snapshot (status, failed/min) |
+| `list_recent_alerts` | Alerts fired in the last N hours |
+| `acknowledge_alert` | Dismiss an active alert by its key |
+| `create_alert` | Create a new alert channel (Slack, email, or webhook) |
+
+### `list_scheduled_jobs`
+
+List all monitored cron jobs for an app, with their last run status and timing.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug from your Crontinel dashboard |
+
+**Returns:** Array of job objects with `command`, `schedule`, `last_run_at`, `last_exit_code`, `last_duration_ms`, `status` (`ok` / `late` / `failing` / `never_ran`).
+
+---
+
+### `get_cron_status`
+
+Get the last run result for a specific cron command.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+| `command` | string | Yes | The cron command string (e.g. `php artisan inspire`) |
+
+**Returns:** `command`, `last_run_at`, `exit_code`, `duration_ms`, `output` (last 500 chars of stdout/stderr), `status`.
+
+---
+
+### `get_queue_status`
+
+Get queue depth, failed count, and oldest pending job age.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+| `queue` | string | No | Specific queue name; omit for all queues |
+
+**Returns:** Array of queue objects with `name`, `depth`, `failed_count`, `oldest_job_age_seconds`.
+
+---
+
+### `get_horizon_status`
+
+Get a health snapshot of Laravel Horizon: supervisor states, paused/running, failed jobs per minute.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+
+**Returns:** `status` (`running` / `paused` / `inactive`), `failed_jobs_per_minute`, `supervisors` array with `name`, `status`, `processes`.
+
+---
+
+### `list_recent_alerts`
+
+List alerts that have fired within the last N hours.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+| `hours` | number | No | Look-back window in hours (default: 24) |
+
+**Returns:** Array of alert objects with `alert_key`, `state` (`firing` / `resolved`), `fired_at`, `resolved_at`, `message`.
+
+---
+
+### `acknowledge_alert`
+
+Dismiss an active alert so it stops notifying.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+| `alert_key` | string | Yes | Alert key (from `list_recent_alerts`) |
+
+**Returns:** `{ acknowledged: true, alert_key: "..." }` on success.
+
+---
+
+### `create_alert`
+
+Create a new alert channel for an app. Requires a Pro or Team plan.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `app_slug` | string | Yes | App slug |
+| `type` | string | Yes | `slack`, `email`, or `webhook` |
+| `config` | object | Yes | Channel-specific config (see below) |
+
+**Config by type:**
+
+| Type | Required fields |
+|---|---|
+| `slack` | `webhook_url`: Incoming Webhook URL |
+| `email` | `address`: Recipient email address |
+| `webhook` | `url`: Endpoint URL; optionally `secret` for HMAC signing |
+
+**Returns:** The new alert channel ID on success.
+
+---
+
+## How It Works
+
+1. Your AI assistant spawns the MCP server as a local stdio process
+2. The server receives JSON-RPC tool calls over stdin
+3. It forwards each call as an HTTP request to `app.crontinel.com/api/mcp` with your API key in the `Authorization` header
+4. The JSON-RPC response is returned over stdout
+
+All tool definitions are declared locally so your AI can inspect them without a network round-trip.
+
+## Troubleshooting
+
+**`401 Unauthorized`**: Your `CRONTINEL_API_KEY` is missing or invalid. Check that the env var is set in your MCP config, not your shell profile (MCP servers don't inherit your shell environment).
+
+**`404 Not Found` on a tool call**: The `app_slug` doesn't match any app in your account. Copy the slug from the app URL in the Crontinel dashboard (`app.crontinel.com/apps/{slug}`).
+
+**Tools not showing up in Claude/Cursor**: Restart the AI client after updating the MCP config. Most clients only load MCP servers at startup.
+
+**`npx` slow on first run**: `npx -y` downloads the package on first use. Run `npm install -g @crontinel/mcp-server` once to cache it locally, then change `command` to `crontinel-mcp` and remove the `args`.
+
+## Documentation
+
+For the full integration guide, tool reference, and setup walkthroughs:
+
+- [MCP Overview](https://docs.crontinel.com/mcp/overview/)
+- [Available Tools Reference](https://docs.crontinel.com/mcp/tools/)
+- [Claude Code Setup](https://docs.crontinel.com/mcp/claude-code/)
+
+## Ecosystem
+
+| Package | Description |
+|---|---|
+| [@crontinel/mcp-server](https://github.com/crontinel/mcp-server) | MCP server for AI assistants (this repo) |
+| [crontinel/laravel](https://github.com/crontinel/crontinel) | Laravel package that reports the data this server reads |
+| [docs.crontinel.com](https://docs.crontinel.com) | Full documentation |
+
+## License
+
+[MIT](https://github.com/crontinel/mcp-server/blob/main/LICENSE)

package/dist/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const API_KEY = process.env.CRONTINEL_API_KEY;
+const API_URL = process.env.CRONTINEL_API_URL ?? 'https://app.crontinel.com';
+if (!API_KEY) {
+    console.error('Error: CRONTINEL_API_KEY environment variable is required');
+    process.exit(1);
+}
+const TOOLS = [
+    {
+        name: 'list_scheduled_jobs',
+        description: 'List all monitored cron commands with their last run status and timing',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'get_cron_status',
+        description: 'Get the last run status, exit code, and duration for a specific cron command',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: 'Command name or partial match (e.g. "send-invoices")' },
+            },
+            required: ['command'],
+        },
+    },
+    {
+        name: 'get_queue_status',
+        description: 'Get queue depth, failed job count, and oldest job age for all queues or a specific queue',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                queue: { type: 'string', description: 'Queue name (optional — returns all queues if omitted)' },
+            },
+        },
+    },
+    {
+        name: 'get_horizon_status',
+        description: 'Get a snapshot of Laravel Horizon health: supervisor states, paused status, failed jobs per minute',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'list_recent_alerts',
+        description: 'List alerts that have fired in the last N hours',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                hours: { type: 'integer', description: 'Look-back window in hours (default: 24)' },
+            },
+        },
+    },
+    {
+        name: 'acknowledge_alert',
+        description: 'Dismiss an active alert by its alert key',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                alert_key: { type: 'string', description: 'Alert key to dismiss (e.g. "horizon:paused", "queue:emails:depth")' },
+            },
+            required: ['alert_key'],
+        },
+    },
+    {
+        name: 'create_alert',
+        description: 'Create a new alert channel (slack, email, or webhook) for the app',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', enum: ['slack', 'email', 'webhook'], description: 'Alert channel type' },
+                webhook_url: { type: 'string', description: 'Slack incoming webhook URL (required when type=slack)' },
+                to: { type: 'string', description: 'Recipient email address (required when type=email)' },
+                url: { type: 'string', description: 'Webhook endpoint URL (required when type=webhook)' },
+            },
+            required: ['type'],
+        },
+    },
+];
+async function callCrontinel(method, params) {
+    const response = await fetch(`${API_URL}/api/mcp`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${API_KEY}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: Date.now(),
+            method,
+            params,
+        }),
+    });
+    if (!response.ok) {
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `Crontinel API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (data.error) {
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, data.error.message);
+    }
+    return data.result;
+}
+const server = new index_js_1.Server({ name: 'crontinel', version: '0.2.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await callCrontinel('tools/call', { name, arguments: args ?? {} });
+    return result;
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('Crontinel MCP server running');
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@crontinel/mcp-server",
+  "version": "0.2.0",
+  "description": "MCP server for Crontinel background job monitoring",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "bin": {
+    "crontinel-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "mcp",
+    "laravel",
+    "monitoring",
+    "cron",
+    "horizon",
+    "queue"
+  ],
+  "author": "Harun R Rayhan",
+  "license": "MIT",
+  "homepage": "https://crontinel.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crontinel/mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/crontinel/mcp-server/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "vitest": "^1.0.0",
+    "@vitest/coverage-v8": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}