@cronicorn/mcp-server 1.22.3 → 1.23.0

package/README.md

@@ -1,7 +1,7 @@
 # Cronicorn MCP Server
 
 [![npm version](https://badge.fury.io/js/@cronicorn%2Fmcp-server.svg)](https://www.npmjs.com/package/@cronicorn/mcp-server)
-[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/servers/io.github.weskerllc/cronicorn-mcp-server)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.weskerllc%2Fcronicorn-mcp-server)
 
 Manage cron jobs by talking to your AI assistant.
 

package/dist/docs/api-reference.md

@@ -11,7 +11,7 @@ mcp:
   uri: file:///docs/api-reference.md
   mimeType: text/markdown
   priority: 0.90
-  lastModified: 2026-02-03T00:00:00Z
+  lastModified: 2026-02-11T00:00:00Z
 ---
 
 # API Reference
@@ -461,6 +461,37 @@ curl -H "x-api-key: YOUR_API_KEY" \
 }
 ```
 
+### Test Endpoint
+
+Execute an endpoint immediately and return the result. Creates a run record with `source: "test"` but does **not** affect scheduling state (`nextRunAt`, `lastRunAt`, `failureCount`). Works on paused endpoints. Blocked on archived endpoints.
+
+```bash
+curl -X POST -H "x-api-key: YOUR_API_KEY" \
+  https://cronicorn.com/api/endpoints/ep_xyz789/test
+```
+
+**Response:**
+```json
+{
+  "runId": "run_test_abc123",
+  "status": "success",
+  "durationMs": 234,
+  "statusCode": 200,
+  "responseBody": { "healthy": true }
+}
+```
+
+If the endpoint fails:
+```json
+{
+  "runId": "run_test_def456",
+  "status": "failed",
+  "durationMs": 5012,
+  "statusCode": 503,
+  "errorMessage": "HTTP 503 Service Unavailable"
+}
+```
+
 ### Get Dashboard Stats
 
 ```bash
@@ -470,6 +501,67 @@ curl -H "x-api-key: YOUR_API_KEY" \
 
 ---
 
+## Signing Keys API
+
+Manage your HMAC signing key for [webhook verification](./guides/webhook-verification.md). Each account has one signing key used to sign all outbound requests.
+
+### Get Signing Key Info
+
+```bash
+curl -H "x-api-key: YOUR_API_KEY" \
+  https://cronicorn.com/api/signing-keys
+```
+
+**Response:**
+```json
+{
+  "hasKey": true,
+  "keyPrefix": "sk_a1b2c3d4",
+  "createdAt": "2026-02-10T15:30:00.000Z",
+  "rotatedAt": null
+}
+```
+
+### Create Signing Key
+
+Generate a new signing key. Returns the raw key **once** — store it securely.
+
+```bash
+curl -X POST -H "x-api-key: YOUR_API_KEY" \
+  https://cronicorn.com/api/signing-keys
+```
+
+**Response (201):**
+```json
+{
+  "rawKey": "a1b2c3d4e5f6...64_hex_chars",
+  "keyPrefix": "sk_a1b2c3d4"
+}
+```
+
+Returns `409 Conflict` if a key already exists. Use rotate instead.
+
+### Rotate Signing Key
+
+Replace the current signing key. The old key is **immediately invalidated**.
+
+```bash
+curl -X POST -H "x-api-key: YOUR_API_KEY" \
+  https://cronicorn.com/api/signing-keys/rotate
+```
+
+**Response:**
+```json
+{
+  "rawKey": "f6e5d4c3b2a1...64_hex_chars",
+  "keyPrefix": "sk_f6e5d4c3"
+}
+```
+
+Returns `404` if no key exists. Use create first.
+
+---
+
 ## AI Analysis API
 
 Access AI scheduling explanations and analysis history.
@@ -666,4 +758,5 @@ Rate limit headers:
 
 - **[Quick Start](./quick-start.md)** - Create your first job via UI
 - **[MCP Server](./mcp-server.md)** - Manage jobs via AI assistant
+- **[Webhook Verification](./guides/webhook-verification.md)** - Verify request signatures in your endpoints
 - **[Technical Reference](./technical/reference.md)** - Schema and field details

package/dist/docs/guides/webhook-verification.md

@@ -0,0 +1,184 @@
+---
+title: Webhook Verification
+description: How to verify that incoming requests are genuinely from Cronicorn
+tags:
+  - user
+  - security
+  - webhooks
+sidebar_position: 1
+mcp:
+  uri: "cronicorn://guides/webhook-verification"
+  mimeType: text/markdown
+  priority: 0.85
+  lastModified: 2026-02-11T00:00:00Z
+---
+
+# Webhook Verification
+
+Every outbound request from Cronicorn includes HMAC-SHA256 signature headers that let your endpoints verify the request is genuine.
+
+## How It Works
+
+Each request includes two headers:
+
+| Header | Example | Description |
+|--------|---------|-------------|
+| `X-Cronicorn-Signature` | `sha256=a1b2c3...` | HMAC-SHA256 of `"{timestamp}.{body}"` |
+| `X-Cronicorn-Timestamp` | `1700000000` | Unix timestamp (seconds) when the request was signed |
+
+The signature is computed as:
+
+```
+HMAC-SHA256(your_signing_key, "{timestamp}.{body}")
+```
+
+Where `body` is the raw request body string (empty string for GET/HEAD requests).
+
+## Getting Your Signing Key
+
+Your signing key is automatically created when your account is set up. You can view, create, or rotate it via:
+
+- **API**: `GET /api/signing-keys`, `POST /api/signing-keys`, `POST /api/signing-keys/rotate`
+- **MCP**: `getSigningKey`, `createSigningKey`, `rotateSigningKey` tools
+
+The raw key is only shown once when created or rotated. Store it securely.
+
+## Verification Examples
+
+### Node.js
+
+```javascript
+import crypto from 'node:crypto';
+
+function verifySignature(req, signingKey) {
+  const signature = req.headers['x-cronicorn-signature'];
+  const timestamp = req.headers['x-cronicorn-timestamp'];
+
+  if (!signature || !timestamp) return false;
+
+  // Replay protection: reject requests older than 5 minutes
+  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
+  if (age > 300) return false;
+
+  // Compute expected signature
+  const body = req.body ? JSON.stringify(req.body) : '';
+  const payload = `${timestamp}.${body}`;
+  const expected = crypto.createHmac('sha256', signingKey)
+    .update(payload)
+    .digest('hex');
+
+  // Constant-time comparison to prevent timing attacks
+  const actual = signature.replace('sha256=', '');
+  return crypto.timingSafeEqual(
+    Buffer.from(expected),
+    Buffer.from(actual)
+  );
+}
+```
+
+### Python
+
+```python
+import hmac
+import hashlib
+import time
+
+def verify_signature(headers, body, signing_key):
+    signature = headers.get('X-Cronicorn-Signature', '')
+    timestamp = headers.get('X-Cronicorn-Timestamp', '')
+
+    if not signature or not timestamp:
+        return False
+
+    # Replay protection: reject requests older than 5 minutes
+    age = int(time.time()) - int(timestamp)
+    if age > 300:
+        return False
+
+    # Compute expected signature
+    payload = f"{timestamp}.{body}"
+    expected = hmac.new(
+        signing_key.encode(),
+        payload.encode(),
+        hashlib.sha256
+    ).hexdigest()
+
+    # Constant-time comparison
+    actual = signature.replace('sha256=', '')
+    return hmac.compare_digest(expected, actual)
+```
+
+### Go
+
+```go
+package main
+
+import (
+    "crypto/hmac"
+    "crypto/sha256"
+    "encoding/hex"
+    "fmt"
+    "net/http"
+    "strconv"
+    "strings"
+    "time"
+)
+
+func verifySignature(r *http.Request, body []byte, signingKey string) bool {
+    signature := r.Header.Get("X-Cronicorn-Signature")
+    timestamp := r.Header.Get("X-Cronicorn-Timestamp")
+
+    if signature == "" || timestamp == "" {
+        return false
+    }
+
+    // Replay protection
+    ts, err := strconv.ParseInt(timestamp, 10, 64)
+    if err != nil {
+        return false
+    }
+    if time.Now().Unix()-ts > 300 {
+        return false
+    }
+
+    // Compute expected signature
+    payload := fmt.Sprintf("%s.%s", timestamp, string(body))
+    mac := hmac.New(sha256.New, []byte(signingKey))
+    mac.Write([]byte(payload))
+    expected := hex.EncodeToString(mac.Sum(nil))
+
+    actual := strings.TrimPrefix(signature, "sha256=")
+    return hmac.Equal([]byte(expected), []byte(actual))
+}
+```
+
+## Replay Protection
+
+The `X-Cronicorn-Timestamp` header enables replay protection. Reject requests where the timestamp is older than your tolerance window (5 minutes recommended):
+
+```javascript
+const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
+if (age > 300) {
+  // Request is too old — possible replay attack
+  return res.status(401).send('Request expired');
+}
+```
+
+## Key Rotation
+
+When you rotate your signing key:
+
+1. The old key is **immediately invalidated**
+2. All subsequent requests use the new key
+3. Any in-flight requests signed with the old key will fail verification
+
+Plan rotation during low-traffic periods to minimize verification failures.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Signature mismatch | Body was modified (e.g., by middleware) | Verify against raw body before parsing |
+| All signatures fail | Wrong signing key | Check `GET /api/signing-keys` for key prefix |
+| Intermittent failures | Clock skew | Increase timestamp tolerance window |
+| No signature headers | No signing key configured | Create one via `POST /api/signing-keys` |

package/dist/docs/mcp-server.md

@@ -11,7 +11,7 @@ mcp:
   uri: file:///docs/mcp-server.md
   mimeType: text/markdown
   priority: 0.95
-  lastModified: 2026-02-03T00:00:00Z
+  lastModified: 2026-02-11T00:00:00Z
 ---
 
 # MCP Server
@@ -76,14 +76,15 @@ From first idea to production — your AI assistant knows Cronicorn inside and o
 "My app is getting more traffic — should I tighten my health check intervals?"
 ```
 
-## 21 Tools Available
+## 25 Tools Available
 
 | Category | Tools |
 |----------|-------|
 | **Jobs** | `createJob`, `listJobs`, `getJob`, `updateJob`, `archiveJob`, `pauseJob`, `resumeJob` |
 | **Endpoints** | `addEndpoint`, `listEndpoints`, `getEndpoint`, `updateEndpoint`, `archiveEndpoint`, `pauseResumeEndpoint` |
 | **AI Scheduling** | `applyIntervalHint`, `scheduleOneShot`, `clearHints`, `resetFailures` |
-| **Monitoring** | `listEndpointRuns`, `getRunDetails`, `getEndpointHealth`, `getDashboardStats` |
+| **Monitoring** | `listEndpointRuns`, `getRunDetails`, `getEndpointHealth`, `getDashboardStats`, `testEndpoint` |
+| **Security** | `getSigningKey`, `createSigningKey`, `rotateSigningKey` |
 
 ## Built-In Documentation
 

package/dist/index.js

@@ -12748,6 +12748,7 @@ __export(schemas_base_exports, {
   RunDetailsResponseBaseSchema: () => RunDetailsResponseBaseSchema,
   RunSummaryResponseBaseSchema: () => RunSummaryResponseBaseSchema,
   ScheduleOneShotRequestBaseSchema: () => ScheduleOneShotRequestBaseSchema,
+  TestEndpointResponseBaseSchema: () => TestEndpointResponseBaseSchema,
   UpdateEndpointRequestBaseSchema: () => UpdateEndpointRequestBaseSchema,
   UpdateJobRequestBaseSchema: () => UpdateJobRequestBaseSchema
 });
@@ -12904,6 +12905,14 @@ var HealthSummaryResponseBaseSchema = external_exports.object({
   }).nullable().describe("Last run information"),
   failureStreak: external_exports.number().int().describe("Current consecutive failure count")
 });
+var TestEndpointResponseBaseSchema = external_exports.object({
+  runId: external_exports.string().describe("ID of the test run record"),
+  status: external_exports.enum(["success", "failed"]).describe("Execution result"),
+  durationMs: external_exports.number().describe("Execution duration in milliseconds"),
+  statusCode: external_exports.number().int().optional().describe("HTTP status code"),
+  responseBody: external_exports.any().nullable().optional().describe("Response body (JSON, within size limit)"),
+  errorMessage: external_exports.string().optional().describe("Error message if failed")
+});
 
 // ../../packages/api-contracts/dist/jobs/schemas.js
 init_esm_shims();
@@ -13511,6 +13520,8 @@ var GetRunDetailsSummary = "Get run details";
 var GetRunDetailsDescription = "Get detailed information about a specific run. Includes full execution details, error messages, response body (if available), status code, and endpoint context.";
 var GetHealthSummarySummary = "Get endpoint health";
 var GetHealthSummaryDescription = "Get health summary for an endpoint. Returns success/failure counts, average duration, last run info, and current failure streak. Useful for monitoring and alerting.";
+var TestEndpointSummary = "Test endpoint";
+var TestEndpointDescription = "Execute an endpoint immediately and return the result. Creates a run record (source: 'test') but does NOT affect scheduling state (nextRunAt, lastRunAt, failureCount). Works on paused endpoints. Blocked on archived endpoints.";
 var RunDetailsResponseSchema = external_exports.object({
   id: external_exports.string().describe("Run ID"),
   endpointId: external_exports.string().describe("Endpoint ID"),
@@ -14207,6 +14218,60 @@ function registerGetRunDetails(server, apiClient) {
   });
 }
 
+// src/tools/api/get-signing-key.ts
+init_esm_shims();
+
+// ../../packages/api-contracts/dist/signing-keys/index.js
+init_esm_shims();
+
+// ../../packages/api-contracts/dist/signing-keys/schemas.base.js
+var schemas_base_exports3 = {};
+__export(schemas_base_exports3, {
+  CreateSigningKeyDescription: () => CreateSigningKeyDescription,
+  CreateSigningKeySummary: () => CreateSigningKeySummary,
+  GetSigningKeyDescription: () => GetSigningKeyDescription,
+  GetSigningKeySummary: () => GetSigningKeySummary,
+  RotateSigningKeyDescription: () => RotateSigningKeyDescription,
+  RotateSigningKeySummary: () => RotateSigningKeySummary,
+  SigningKeyCreatedResponseBaseSchema: () => SigningKeyCreatedResponseBaseSchema,
+  SigningKeyInfoResponseBaseSchema: () => SigningKeyInfoResponseBaseSchema
+});
+init_esm_shims();
+var SigningKeyInfoResponseBaseSchema = external_exports.object({
+  hasKey: external_exports.boolean(),
+  keyPrefix: external_exports.string().nullable(),
+  createdAt: external_exports.string().datetime().nullable(),
+  rotatedAt: external_exports.string().datetime().nullable()
+});
+var SigningKeyCreatedResponseBaseSchema = external_exports.object({
+  rawKey: external_exports.string(),
+  keyPrefix: external_exports.string()
+});
+var GetSigningKeySummary = "Get signing key info";
+var GetSigningKeyDescription = "Returns metadata about the user's signing key (prefix, dates). Never returns the raw key.";
+var CreateSigningKeySummary = "Generate signing key";
+var CreateSigningKeyDescription = "Generates a new HMAC-SHA256 signing key for outbound request verification. Returns the raw key once \u2014 store it securely. Returns 409 if a key already exists.";
+var RotateSigningKeySummary = "Rotate signing key";
+var RotateSigningKeyDescription = "Replaces the current signing key with a new one. The old key is immediately invalidated. Returns 404 if no key exists.";
+
+// src/tools/api/get-signing-key.ts
+var EmptyInputSchema = external_exports.object({});
+var SigningKeyInfoResponseSchema = schemas_base_exports3.SigningKeyInfoResponseBaseSchema;
+function registerGetSigningKey(server, apiClient) {
+  registerApiTool(server, apiClient, {
+    name: "getSigningKey",
+    title: GetSigningKeySummary,
+    description: GetSigningKeyDescription,
+    inputSchema: toShape(EmptyInputSchema),
+    outputSchema: toShape(SigningKeyInfoResponseSchema),
+    inputValidator: EmptyInputSchema,
+    outputValidator: SigningKeyInfoResponseSchema,
+    method: "GET",
+    path: "/signing-keys",
+    successMessage: (output) => output.hasKey ? `Signing key exists (prefix: ${output.keyPrefix}, created: ${output.createdAt})` : "No signing key configured. Use createSigningKey to generate one."
+  });
+}
+
 // src/tools/api/list-endpoints.ts
 init_esm_shims();
 var ListEndpointsRequestSchema = external_exports.object({
@@ -14509,6 +14574,68 @@ function registerPostResetFailures(server, apiClient) {
   });
 }
 
+// src/tools/api/post-rotate-signing-key.ts
+init_esm_shims();
+var EmptyInputSchema2 = external_exports.object({});
+var SigningKeyCreatedResponseSchema = schemas_base_exports3.SigningKeyCreatedResponseBaseSchema;
+function registerRotateSigningKey(server, apiClient) {
+  registerApiTool(server, apiClient, {
+    name: "rotateSigningKey",
+    title: RotateSigningKeySummary,
+    description: RotateSigningKeyDescription,
+    inputSchema: toShape(EmptyInputSchema2),
+    outputSchema: toShape(SigningKeyCreatedResponseSchema),
+    inputValidator: EmptyInputSchema2,
+    outputValidator: SigningKeyCreatedResponseSchema,
+    method: "POST",
+    path: "/signing-keys/rotate",
+    transformInput: () => ({}),
+    successMessage: (output) => `Signing key rotated (new prefix: ${output.keyPrefix}). Old key is immediately invalid. Save the new raw key securely \u2014 it will not be shown again: ${output.rawKey}`
+  });
+}
+
+// src/tools/api/post-signing-key.ts
+init_esm_shims();
+var EmptyInputSchema3 = external_exports.object({});
+var SigningKeyCreatedResponseSchema2 = schemas_base_exports3.SigningKeyCreatedResponseBaseSchema;
+function registerCreateSigningKey(server, apiClient) {
+  registerApiTool(server, apiClient, {
+    name: "createSigningKey",
+    title: CreateSigningKeySummary,
+    description: CreateSigningKeyDescription,
+    inputSchema: toShape(EmptyInputSchema3),
+    outputSchema: toShape(SigningKeyCreatedResponseSchema2),
+    inputValidator: EmptyInputSchema3,
+    outputValidator: SigningKeyCreatedResponseSchema2,
+    method: "POST",
+    path: "/signing-keys",
+    transformInput: () => ({}),
+    successMessage: (output) => `Signing key created (prefix: ${output.keyPrefix}). IMPORTANT: Save this raw key securely \u2014 it will not be shown again: ${output.rawKey}`
+  });
+}
+
+// src/tools/api/post-test-endpoint.ts
+init_esm_shims();
+var TestEndpointInputSchema = external_exports.object({
+  id: external_exports.string().describe("Endpoint ID to test")
+});
+var TestEndpointResponseSchema = schemas_base_exports.TestEndpointResponseBaseSchema;
+function registerPostTestEndpoint(server, apiClient) {
+  registerApiTool(server, apiClient, {
+    name: "testEndpoint",
+    title: TestEndpointSummary,
+    description: TestEndpointDescription,
+    inputSchema: toShape(TestEndpointInputSchema),
+    outputSchema: toShape(TestEndpointResponseSchema),
+    inputValidator: TestEndpointInputSchema,
+    outputValidator: TestEndpointResponseSchema,
+    method: "POST",
+    path: (input) => `/endpoints/${input.id}/test`,
+    transformInput: () => ({}),
+    successMessage: (output) => output.status === "success" ? `\u2705 Endpoint test passed (${output.durationMs}ms, HTTP ${output.statusCode ?? "?"})` : `\u274C Endpoint test failed: ${output.errorMessage ?? "unknown error"} (${output.durationMs}ms)`
+  });
+}
+
 // src/tools/index.ts
 function registerTools(server, apiUrl, credentials) {
   const apiClient = createHttpApiClient({
@@ -14535,7 +14662,11 @@ function registerTools(server, apiUrl, credentials) {
   registerGetEndpointRuns(server, apiClient);
   registerGetRunDetails(server, apiClient);
   registerGetEndpointHealth(server, apiClient);
+  registerPostTestEndpoint(server, apiClient);
   registerGetDashboardStats(server, apiClient);
+  registerGetSigningKey(server, apiClient);
+  registerCreateSigningKey(server, apiClient);
+  registerRotateSigningKey(server, apiClient);
 }
 
 // src/index.ts
@@ -14546,7 +14677,7 @@ async function main() {
     {
       name: "cronicorn",
       // eslint-disable-next-line node/no-process-env
-      version: "1.22.3"
+      version: "1.23.0"
     },
     {
       instructions: [
@@ -14562,19 +14693,19 @@ async function main() {
         "",
         "## How to Help Users",
         "",
-        "When users ask about Cronicorn concepts, integration patterns, self-hosting, or how scheduling works, read the bundled documentation resources on this server. Key resources:",
+        "When users ask about Cronicorn concepts, integration patterns, self-hosting, or how scheduling works, read the bundled documentation resources on this server. Use the `file:///docs/` URI scheme to read resources. Key resources:",
         "",
-        "- `introduction.md` \u2014 What Cronicorn is and why it exists",
-        "- `quick-start.md` \u2014 Creating your first job",
-        "- `core-concepts.md` \u2014 Jobs, endpoints, schedules, AI adaptation explained",
-        "- `recipes.md` \u2014 Common patterns with working examples",
-        "- `use-cases.md` \u2014 Real-world scenarios (health checks, data sync, auto-remediation)",
-        "- `api-reference.md` \u2014 Complete REST API documentation",
-        "- `code-examples.md` \u2014 Integration examples in multiple languages",
-        "- `troubleshooting.md` \u2014 Common issues and solutions",
-        "- `technical/how-ai-adaptation-works.md` \u2014 Deep dive into AI scheduling",
-        "- `technical/how-scheduling-works.md` \u2014 Scheduling mechanics and backoff behavior",
-        "- `self-hosting/index.md` \u2014 Docker Compose deployment guide",
+        "- `file:///docs/introduction.md` \u2014 What Cronicorn is and why it exists",
+        "- `file:///docs/quick-start.md` \u2014 Creating your first job",
+        "- `file:///docs/core-concepts.md` \u2014 Jobs, endpoints, schedules, AI adaptation explained",
+        "- `file:///docs/recipes.md` \u2014 Common patterns with working examples",
+        "- `file:///docs/use-cases.md` \u2014 Real-world scenarios (health checks, data sync, auto-remediation)",
+        "- `file:///docs/api-reference.md` \u2014 Complete REST API documentation",
+        "- `file:///docs/code-examples.md` \u2014 Integration examples in multiple languages",
+        "- `file:///docs/troubleshooting.md` \u2014 Common issues and solutions",
+        "- `file:///docs/technical/how-ai-adaptation-works.md` \u2014 Deep dive into AI scheduling",
+        "- `file:///docs/technical/how-scheduling-works.md` \u2014 Scheduling mechanics and backoff behavior",
+        "- `file:///docs/self-hosting/index.md` \u2014 Docker Compose deployment guide",
         "",
         "Read the relevant resources before answering conceptual or integration questions. The docs are comprehensive \u2014 use them."
       ].join("\n")