@cronicorn/mcp-server 1.6.1 → 1.7.1

package/README.md

@@ -145,6 +145,135 @@ On first run, the server will:
 
 Subsequent runs will use the stored access token automatically.
 
+## Prompts (Slash Commands)
+
+Prompts are interactive conversation starters that guide you through common Cronicorn workflows. They're triggered using slash commands in your AI assistant.
+
+### Available Prompts
+
+#### `/setup-first-job` - Get Started with Cronicorn
+
+Interactive guide for creating your first scheduled job. Works for all scenarios including new users and migrations from other cron systems.
+
+**Optional Arguments:**
+- `task_description`: What the job should do
+- `endpoint_url`: HTTP endpoint to call
+- `schedule_type`: "interval" or "cron"
+
+**Example Usage (GitHub Copilot):**
+
+In GitHub Copilot Chat, type:
+```
+@cronicorn /setup-first-job
+```
+
+Or with arguments:
+```
+@cronicorn /setup-first-job task_description="check API health every 5 minutes" endpoint_url="https://api.myapp.com/health"
+```
+
+The prompt will guide you through:
+1. Understanding jobs vs endpoints
+2. Creating a job container
+3. Adding your HTTP endpoint
+4. Configuring baseline schedules
+5. Setting safety constraints
+6. Enabling AI adaptation
+
+**What You'll Learn:**
+- Jobs vs endpoints (containers vs execution units)
+- Baseline schedules (cron vs interval)
+- AI hints for dynamic scheduling
+- Safety constraints (min/max intervals)
+- Response body instrumentation
+
+---
+
+#### `/troubleshoot-failures` - Debug Failing Endpoints
+
+Debug failing job executions and identify solutions.
+
+**Optional Arguments:**
+- `job_or_endpoint_name`: Name/ID of failing endpoint
+- `error_description`: Error symptoms
+- `when_started`: "just-now", "today", "this-week", or "longer"
+
+**Example Usage (GitHub Copilot):**
+
+```
+@cronicorn /troubleshoot-failures job_or_endpoint_name="payment-processor" error_description="timeout errors" when_started="today"
+```
+
+The prompt will guide you through:
+1. Identifying the failing endpoint
+2. Reviewing run history for patterns
+3. Analyzing error details (status codes, messages)
+4. Checking AI hints and scheduling state
+5. Inspecting response bodies
+6. Applying fixes (constraints, pausing, configuration)
+
+**Common Issues Covered:**
+- Timeout errors (increase timeout/execution time)
+- Rate limiting (429 errors, adjust min interval)
+- Service unavailable (500/503, pause endpoint)
+- Authentication failures (401/403, fix headers)
+- Network issues (connection refused, DNS)
+- Response body problems (size limits, structure)
+
+---
+
+### Using Prompts in GitHub Copilot
+
+**In VS Code with GitHub Copilot Chat:**
+
+1. Open GitHub Copilot Chat (Click the chat icon or `Ctrl+Shift+I` / `Cmd+Shift+I`)
+
+2. Use the `@cronicorn` agent with a slash command:
+   ```
+   @cronicorn /setup-first-job
+   ```
+
+3. Copilot will run the prompt and guide you through the workflow
+
+4. Provide arguments inline:
+   ```
+   @cronicorn /migrate-from-cron current_system="vercel-cron" job_count="10"
+   ```
+
+5. Follow the interactive guidance to complete your task
+
+**Tips for Best Results:**
+
+- **Start broad**: Use prompts without arguments to get full guidance
+- **Provide context**: Include arguments when you have specific info
+- **Follow suggestions**: Prompts reference specific tools to use next
+- **Check resources**: Prompts include doc links for deeper learning
+
+**Note:** GitHub Copilot doesn't automatically load bundled resources like Claude Desktop does, but prompts include embedded summaries and hosted doc URLs for universal access.
+
+---
+
+### Using Prompts in Claude Desktop
+
+**In Claude Desktop:**
+
+1. Type a slash command in the chat:
+   ```
+   /setup-first-job
+   ```
+
+2. Claude will execute the prompt and start guiding you
+
+3. Prompts can reference bundled documentation resources:
+   ```
+   file:///docs/quick-start.md
+   file:///docs/core-concepts.md
+   ```
+
+4. Claude automatically loads these resources for additional context
+
+---
+
 ## Keeping Updated
 
 The MCP server does not automatically update. When using `npx` or global installation, you'll continue using the cached version until you manually update.
@@ -345,6 +474,21 @@ git push --follow-tags
 
 **Note**: Only production dependency is `@modelcontextprotocol/sdk` - everything else is bundled.
 
+## Alternative: Context7 Documentation Access
+
+If you have the [Context7 MCP server](https://context7.com) installed alongside Cronicorn MCP, you can access Cronicorn documentation directly in your AI assistant:
+
+```
+@context7 /weskerllc/cronicorn
+```
+
+This provides an alternative way to access up-to-date Cronicorn documentation without leaving your conversation. Context7 complements the Cronicorn MCP server's prompts and bundled resources.
+
+**Use cases:**
+- Quick doc lookups while working with Cronicorn MCP tools
+- Access to the latest documentation updates
+- Cross-reference between different sections of the docs
+
 ## Security
 
 - OAuth 2.0 Device Authorization Grant for secure authentication

package/dist/docs/core-concepts.md

@@ -225,9 +225,3 @@ AI behavior:
 - Never exceeds API rate limits (min)
 - Ensures data freshness (max)
 ```
-
-## Next Steps
-
-- **[Introduction](./introduction.md)** - Why use Cronicorn
-- **[Quick Start](./quick-start.md)** - Create your first job
-- **[Technical Documentation](./technical/system-architecture.md)** - For developers and self-hosters

package/dist/docs/developers/quick-start.md

@@ -77,8 +77,3 @@ pnpm dev
 
 **Database errors?**  
 → Ensure Docker is running, then `pnpm db`
-
-## Next Steps
-
--  [Authentication](./authentication.md) - Configure authentication methods
--  [Architecture](../technical/system-architecture.md) - System design

package/dist/docs/developers/workspace-structure.md

@@ -172,8 +172,3 @@ Central docs folder that is used by the docs app and mcp-server
 | AI prompts | `packages/worker-ai-planner/src/` |
 | HTTP dispatcher | `packages/adapter-http/` |
 | Business logic | `packages/services/` |
-
-## Next Steps
-
-- **[System Architecture](../technical/system-architecture.md)** - How components interact at runtime
-- **[Quick Start](./quick-start.md)** - Set up your dev environment

package/dist/docs/introduction.md

@@ -21,6 +21,40 @@ mcp:
 
 **Cronicorn** is an intelligent scheduler that automatically adapts to your application's behavior. Set baseline schedules and let AI optimize execution timing based on real-world patterns.
 
+---
+
+## 🤖 Recommended: Use the MCP Server
+
+**The easiest way to use Cronicorn is through your AI assistant.** Just chat to create jobs, monitor executions, and debug issues—no forms, no clicking.
+
+[![npm version](https://badge.fury.io/js/@cronicorn%2Fmcp-server.svg)](https://www.npmjs.com/package/@cronicorn/mcp-server)
+
+```bash
+npm install -g @cronicorn/mcp-server
+```
+
+Configure it with GitHub Copilot, Claude Desktop, or any MCP-compatible AI assistant. Then just talk:
+
+- *"Set up a job that checks my API health every 5 minutes"*
+- *"Show me why that endpoint is failing"*
+- *"Migrate my 10 Vercel cron jobs to Cronicorn"*
+
+**[→ Learn more about the MCP Server](./mcp-server.md)**
+
+---
+
+## Quick Navigation
+
+**Getting Started**
+- [Quick Start](./quick-start.md) - Create your first scheduled job in 5 minutes
+- [Core Concepts](./core-concepts.md) - Understand jobs, endpoints, and scheduling
+
+**Learn More**
+- [Use Cases & Examples](./use-cases.md) - Real-world scenarios across industries
+- [Technical Architecture](./technical/system-architecture.md) - Deep dive - How Cronicorn works behind the scenes
+
+---
+
 ## What is Cronicorn?
 
 Cronicorn is a scheduling service that combines:
@@ -89,44 +123,6 @@ When enabled, the AI planner:
 - **Multi-tenant isolation**: Secure separation between accounts
 - **API & Web UI**: Manage jobs programmatically or visually
 
-## Use Cases
-
-### API Health Monitoring
-
-Monitor your APIs with adaptive frequency:
-
-- Baseline: Check every 5 minutes
-- AI increases to every 30 seconds when errors detected
-- AI backs off to every 15 minutes when stable
-- Stays within your min (30s) and max (15min) constraints
-
-### Data Synchronization
-
-Sync data between systems efficiently:
-
-- Baseline: Sync every hour
-- AI increases during business hours when changes are frequent
-- AI decreases overnight when activity is low
-- Respects API rate limits with max interval constraints
-
-### Scheduled Maintenance
-
-Run cleanup and maintenance tasks:
-
-- Baseline: Daily at 2am via cron expression
-- Pause during known maintenance windows
-- Monitor execution duration trends over time
-- Track success/failure for audit compliance
-
-### Webhook Retry Logic
-
-Retry failed webhooks intelligently:
-
-- Baseline: Immediate retry, then exponential backoff
-- AI adjusts retry timing based on downstream service patterns
-- Automatic pause after sustained failures
-- Resume when downstream recovers
-
 ## How It Works
 
 1. **Create a Job** - Logical container for related endpoints
@@ -141,15 +137,3 @@ Retry failed webhooks intelligently:
 - **E-commerce teams** syncing inventory and order data
 - **DevOps engineers** running scheduled maintenance tasks
 - **Integration developers** managing webhook retries and polling
-
-## Getting Started
-
-- **Using Cronicorn as a service**: See [Quick Start](./quick-start.md)
-- **Self-hosting Cronicorn**: See [Technical Documentation](./technical/system-architecture.md)
-- **AI assistant integration**: Use our [MCP Server](https://www.npmjs.com/package/@cronicorn/mcp-server)
-
-## Next Steps
-
-- **[Core Concepts](./core-concepts.md)** - Understand jobs, endpoints, and scheduling
-- **[Quick Start](./quick-start.md)** - Create your first scheduled job
-- **[Technical Deep Dive](./technical/system-architecture.md)** - For developers and self-hosters

package/dist/docs/mcp-server.md

@@ -0,0 +1,127 @@
+---
+id: mcp-server
+title: MCP Server
+description: Control Cronicorn through your AI assistant - no forms, no clicking, just conversation
+tags:
+  - getting-started
+  - integrations
+  - ai
+sidebar_position: 3
+mcp:
+  uri: file:///docs/mcp-server.md
+  mimeType: text/markdown
+  priority: 0.9
+---
+
+# Chat Your Way to Scheduled Jobs
+
+[![npm version](https://badge.fury.io/js/@cronicorn%2Fmcp-server.svg)](https://www.npmjs.com/package/@cronicorn/mcp-server)
+
+**What if you could manage cron jobs by just talking to your AI assistant?**
+
+```
+You: "Set up a job that checks my API health every 5 minutes"
+
+AI: *Creates the job, adds the endpoint, configures the schedule*
+    ✅ Done! Your health check is now running every 5 minutes.
+```
+
+**No forms. No clicking. Just conversation.**
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @cronicorn/mcp-server
+```
+
+### Configure Your AI Assistant
+
+Add the Cronicorn MCP server to your AI assistant's configuration. The exact setup varies by tool:
+
+- **GitHub Copilot**: Add to VS Code settings
+- **Claude Desktop**: Add to `claude_desktop_config.json`
+- **Cline/Continue/Cursor**: Check your extension's MCP settings
+
+See the [full installation guide](https://github.com/weskerllc/cronicorn/tree/main/apps/mcp-server#installation) for platform-specific instructions.
+
+### Authenticate
+
+First time you use it, you'll authenticate once via OAuth (browser opens, you approve, done). The MCP server remembers you for 30 days.
+
+## What You Can Do
+
+**Create jobs instantly:**
+```
+"Check https://api.myapp.com/health every 5 minutes"
+```
+
+**Debug failures:**
+```
+"My payment-processor job is timing out - fix it"
+```
+
+**Monitor everything:**
+```
+"Show me my dashboard stats"
+"What's wrong with that failing endpoint?"
+```
+
+**Migrate from other systems:**
+```
+"Help me move my 15 Vercel cron jobs to Cronicorn"
+```
+
+## Built-In Guides
+
+The MCP server includes interactive slash commands that guide you through common workflows:
+
+**`/setup-first-job`** - Perfect for getting started or migrating
+- Learn jobs vs endpoints, baseline schedules, AI adaptation, safety constraints
+- Get step-by-step guidance for your first scheduled task
+
+**`/troubleshoot-failures`** - Debug failing endpoints
+- Systematic diagnostic process
+- Common issues and fixes (timeouts, rate limits, auth)
+- Emergency actions when needed
+
+## 30+ Tools Available
+
+Your AI assistant has access to tools for:
+
+- **Job Management** - Create, list, update, pause, resume, delete
+- **Endpoint Control** - Add, configure, update URLs/timeouts/schedules
+- **AI Scheduling** - Apply hints, trigger immediate runs, pause/resume
+- **Monitoring** - Health summaries, execution history, run details, dashboard stats
+
+[See all available tools →](https://github.com/weskerllc/cronicorn/tree/main/apps/mcp-server#available-tools)
+
+## Example Use Cases
+
+**Health monitoring with AI adaptation:**
+```
+"Monitor https://api.acme.com/health every minute. 
+Check more frequently if slow, relax to 5 minutes when healthy."
+```
+→ AI auto-adjusts interval based on latency in response
+
+**Data sync with queue monitoring:**
+```
+"Sync https://api.acme.com/sync every 5 minutes.
+Speed up when queue_depth > 100, slow down when < 10."
+```
+→ AI monitors queue_depth and adjusts schedule dynamically
+
+**Daily cleanup:**
+```
+"Run cleanup at https://api.acme.com/cleanup daily at 2 AM Pacific"
+```
+→ Simple cron-based schedule
+
+## Security & Compatibility
+
+**Secure authentication** via OAuth 2.0 Device Flow (same as AWS CLI, GitHub CLI). Credentials stored locally with strict permissions. Tokens refresh automatically, re-auth every 30 days.
+
+**Works with** GitHub Copilot, Claude Desktop, Cline, Continue, Cursor, and any MCP-compatible AI assistant.
+

package/dist/docs/quick-start.md

@@ -217,16 +217,3 @@ If you're hitting rate limits:
 1. Increase **Min Interval** (e.g., from 30s to 60s)
 2. Adjust **Baseline Schedule** to be less frequent
 3. Let AI adapt (it will back off automatically)
-
-## Next Steps
-
-- **[Core Concepts](./core-concepts.md)** - Understand jobs, endpoints, and AI scheduling
-- **[API Reference](https://cronicorn.com/docs/api)** - Full API documentation
-- **[Self-Hosting Guide](./technical/system-architecture.md)** - Deploy Cronicorn yourself
-
-## Getting Help
-
-- 📖 [Documentation](https://cronicorn.com/docs)
-- 💬 [Discord Community](https://discord.gg/cronicorn)
-- 📧 [Email Support](mailto:support@cronicorn.com)
-- 🐛 [Report Issues](https://github.com/weskerllc/cronicorn/issues)

package/dist/docs/technical/configuration-and-constraints.md

@@ -407,9 +407,3 @@ Expensive operation runs every 10 minutes normally, AI can relax to hourly or ti
 7. **Min/max apply relative to `now`, not `lastRunAt`**
 
 Configure conservatively. The system is designed to be safe by default. Add constraints when you encounter real problems, not anticipated ones.
-
-## Next Steps
-
-- **[How Scheduling Works](./how-scheduling-works.md)** - Understand how Governor applies constraints
-- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Learn how AI proposes intervals
-- **[Reference](./reference.md)** - Quick lookup for defaults and field ranges

package/dist/docs/technical/coordinating-multiple-endpoints.md

@@ -449,9 +449,3 @@ When coordination isn't working:
 7. **Cross-job coordination**: Embed external status checks in responses
 
 These patterns give you the building blocks for complex workflows. Mix and match based on your needs.
-
-## Next Steps
-
-- **[Configuration and Constraints](./configuration-and-constraints.md)** - Set up endpoints for optimal coordination
-- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Understand how AI reads and acts on signals
-- **[Reference](./reference.md)** - Quick lookup for tools and response body patterns

package/dist/docs/technical/how-ai-adaptation-works.md

@@ -445,9 +445,3 @@ This ensures that even if AI becomes unavailable or too expensive, your jobs kee
 9. **Quota controls costs**: AI unavailable ≠ jobs stop running
 
 Understanding how AI adaptation works helps you design endpoints that benefit from intelligent scheduling, structure response bodies effectively, and debug unexpected schedule changes.
-
-## Next Steps
-
-- **[Coordinating Multiple Endpoints](./coordinating-multiple-endpoints.md)** - Use AI to orchestrate workflows
-- **[Configuration and Constraints](./configuration-and-constraints.md)** - Set up endpoints for optimal AI behavior
-- **[Reference](./reference.md)** - Quick lookup for tools, fields, and defaults

package/dist/docs/technical/how-scheduling-works.md

@@ -260,9 +260,3 @@ This is the power of database-mediated communication: the Scheduler and AI Plann
 6. **Sources provide auditability**: Every decision is traceable
 
 Understanding how scheduling works gives you the foundation to configure endpoints effectively, debug unexpected behavior, and reason about how AI adaptation affects execution timing.
-
-## Next Steps
-
-- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Learn how the AI Planner writes hints
-- **[Configuration and Constraints](./configuration-and-constraints.md)** - Guide to setting up endpoints safely
-- **[Reference](./reference.md)** - Quick lookup for fields, defaults, and sources

package/dist/docs/technical/reference.md

@@ -394,11 +394,3 @@ Calculate current backoff multiplier:
 ```
 failureCount > 0 ? 2^min(failureCount, 5) : 1
 ```
-
-## Next Steps
-
-For detailed explanations, see:
-- **[System Architecture](./system-architecture.md)** - Understand the big picture
-- **[How Scheduling Works](./how-scheduling-works.md)** - Deep-dive into Governor and Scheduler
-- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Learn about hints and tools
-- **[Configuration Guide](./configuration-and-constraints.md)** - Set up endpoints correctly

package/dist/docs/technical/system-architecture.md

@@ -292,14 +292,6 @@ To use Cronicorn effectively, you need to understand:
 
 5. **The system is eventually consistent**: Don't expect instant reactions to every change. The AI analyzes every 5 minutes, and hints apply on the next execution. Plan for minutes, not seconds.
 
-## Next Steps
-
-Now that you understand the architecture, you can dive deeper:
-
-- **[How Scheduling Works](./how-scheduling-works.md)** - Deep-dive into the Scheduler worker and Governor logic
-- **[How AI Adaptation Works](./how-ai-adaptation-works.md)** - Deep-dive into the AI Planner and hint system
-- **[Coordinating Multiple Endpoints](./coordinating-multiple-endpoints.md)** - Patterns for building workflows
-- **[Configuration and Constraints](./configuration-and-constraints.md)** - How to configure endpoints effectively
 
 ---