@cronicorn/mcp-server 1.4.5 → 1.5.0

package/dist/docs/README.md

@@ -0,0 +1,133 @@
+---
+id: docs-readme
+title: Cronicorn Documentation
+description: Documentation overview and navigation guide
+tags:
+  - user
+  - assistant
+  - essential
+sidebar_position: 10
+mcp:
+  uri: file:///docs/README.md
+  mimeType: text/markdown
+  priority: 1.0
+  lastModified: 2025-11-02T00:00:00Z
+---
+
+# Cronicorn Documentation
+
+Welcome to the Cronicorn documentation! This guide will help you find the right documentation for your needs.
+
+## Quick Navigation
+
+### 🚀 Getting Started (SaaS Users)
+
+Using Cronicorn as a hosted service? Start here:
+
+1. **[Introduction](./introduction.md)** - What is Cronicorn and why use it
+2. **[Quick Start](./quick-start.md)** - Create your first scheduled job in 5 minutes
+3. **[Core Concepts](./core-concepts.md)** - Understand jobs, endpoints, and AI scheduling
+
+**Perfect for:**
+- SaaS developers monitoring APIs
+- Teams running scheduled tasks
+- Anyone using Cronicorn as a service
+
+### 🔧 Self-Hosting (Developers)
+
+Want to deploy Cronicorn yourself? See technical docs:
+
+1. **[System Architecture](./technical/system-architecture.md)** - How Cronicorn works internally
+2. **[How Scheduling Works](./technical/how-scheduling-works.md)** - The governor algorithm
+3. **[How AI Adaptation Works](./technical/how-ai-adaptation-works.md)** - Optional AI features
+4. **[Configuration & Constraints](./technical/configuration-and-constraints.md)** - Safety and limits
+
+**Perfect for:**
+- DevOps engineers deploying Cronicorn
+- Contributors to the open-source project
+- Advanced users customizing the system
+
+### 🤖 AI Assistant Integration
+
+Using Cronicorn with Claude, Cursor, or other AI assistants?
+
+- **[MCP Server](https://www.npmjs.com/package/@cronicorn/mcp-server)** - Model Context Protocol integration
+- Install with: `npm install -g @cronicorn/mcp-server`
+- See [Quick Start MCP Section](./quick-start.md#using-with-ai-assistants) for setup
+
+**Perfect for:**
+- Claude Desktop users
+- VS Code with GitHub Copilot
+- Cursor, Cline, Continue users
+
+## Documentation Tags
+
+Documents are tagged for different audiences:
+
+- **`user`** - End users of the Cronicorn service
+- **`assistant`** - AI assistants accessing via MCP
+- **`essential`** - Core documentation everyone should read
+
+## Available Documentation
+
+### User Documentation
+- ✅ [Introduction](./introduction.md) - Overview and key features
+- ✅ [Core Concepts](./core-concepts.md) - Jobs, endpoints, scheduling, AI hints
+- ✅ [Quick Start](./quick-start.md) - Get started in 5 minutes
+
+### Technical Documentation (Self-Hosting)
+- ✅ [System Architecture](./technical/system-architecture.md) - Hexagonal architecture overview
+- ✅ [How Scheduling Works](./technical/how-scheduling-works.md) - Governor algorithm details
+- ✅ [How AI Adaptation Works](./technical/how-ai-adaptation-works.md) - AI planner internals
+- ✅ [Coordinating Multiple Endpoints](./technical/coordinating-multiple-endpoints.md) - Advanced patterns
+- ✅ [Configuration & Constraints](./technical/configuration-and-constraints.md) - Safety mechanisms
+- ✅ [Technical Reference](./technical/reference.md) - API contracts and database schema
+
+## About This Documentation
+
+This directory (`docs-v2/`) serves as the **single source of truth** for Cronicorn documentation, consumed by:
+
+- **Docusaurus website** - Human-readable documentation site
+- **MCP server** - AI assistants accessing documentation via Model Context Protocol
+
+### Frontmatter Structure
+
+Each document includes metadata for both humans and AI:
+
+```yaml
+---
+id: unique-identifier
+title: Human-Readable Title
+description: Brief description
+tags:
+  - user          # For end users
+  - assistant     # For AI assistants  
+  - essential     # Core documentation
+sidebar_position: 1
+mcp:
+  uri: file:///docs/filename.md
+  mimeType: text/markdown
+  priority: 0.9   # 0.0-1.0, higher = more important
+  lastModified: 2025-11-02T00:00:00Z
+---
+```
+
+## Contributing
+
+Found an issue or want to improve the docs?
+
+1. **Report issues**: [GitHub Issues](https://github.com/weskerllc/cronicorn/issues)
+2. **Suggest improvements**: [GitHub Discussions](https://github.com/weskerllc/cronicorn/discussions)
+3. **Submit PRs**: See our contributing guidelines on GitHub
+
+## Getting Help
+
+- 📖 [Documentation Site](https://cronicorn.com/docs)
+- 💬 [Discord Community](https://discord.gg/cronicorn)
+- 📧 [Email Support](mailto:support@cronicorn.com)
+
+## Related Resources
+
+- **[MCP Server Package](https://www.npmjs.com/package/@cronicorn/mcp-server)** - AI assistant integration
+- **[GitHub Repository](https://github.com/weskerllc/cronicorn)** - Source code and issues
+- **[API Documentation](https://app.cronicorn.com/docs/api)** - REST API reference

package/dist/docs/core-concepts.md

@@ -0,0 +1,233 @@
+---
+id: core-concepts
+title: Core Concepts
+description: Key terminology for using Cronicorn
+tags:
+  - user
+  - assistant
+  - essential
+sidebar_position: 2
+mcp:
+  uri: file:///docs/core-concepts.md
+  mimeType: text/markdown
+  priority: 0.95
+  lastModified: 2025-11-02T00:00:00Z
+---
+
+# Core Concepts
+
+Understand the key concepts for working with Cronicorn.
+
+## Jobs and Endpoints
+
+### Job
+
+A **Job** is a container that groups related endpoints together.
+
+**Example**: A "Data Sync" job might contain endpoints for syncing users, products, and orders from different APIs.
+
+**Properties:**
+- **Name**: Descriptive label (e.g., "API Health Checks")
+- **Description**: Optional details about what this job does
+- **Status**: Active, paused, or archived
+
+### Endpoint
+
+An **Endpoint** is the actual work to be executed - an HTTP request that runs on a schedule.
+
+**Example**: `POST https://api.example.com/sync/users` that runs every 5 minutes.
+
+**Required:**
+- **Name**: What this endpoint does (e.g., "Sync Users")
+- **URL**: The HTTP endpoint to call
+- **Method**: GET, POST, PUT, PATCH, or DELETE
+- **Schedule**: Either a cron expression OR an interval in milliseconds
+
+**Optional:**
+- **Headers**: Custom HTTP headers
+- **Body**: Request body (for POST/PUT/PATCH)
+- **Min/Max Intervals**: Safety constraints (see below)
+- **Timeout**: Maximum execution time
+
+## Scheduling
+
+### Baseline Schedule
+
+Your **baseline schedule** is the default timing for an endpoint. You must choose ONE:
+
+**Option 1: Cron Expression**
+```
+"0 */5 * * *"  // Every 5 minutes
+"0 2 * * *"    // Daily at 2am
+"0 9 * * 1"    // Mondays at 9am
+```
+
+**Option 2: Interval (milliseconds)**
+```
+60000      // Every 60 seconds
+300000     // Every 5 minutes
+3600000    // Every hour
+```
+
+The baseline schedule is always active and provides a fallback when AI hints expire.
+
+### AI Hints (Optional)
+
+When AI is enabled, it can suggest temporary scheduling adjustments called **hints**:
+
+**AI Interval Hint** - Adjust how often the endpoint runs:
+- "Run every 30 seconds for the next hour" (instead of every 5 minutes)
+- "Run every 15 minutes for the next 4 hours" (instead of every 5 minutes)
+- Hints expire automatically (TTL) and revert to baseline
+
+**AI One-Shot Hint** - Schedule a single immediate or future run:
+- "Run once right now" (for immediate execution)
+- "Run once at 2:30 PM" (for specific time)
+- Happens once, then endpoint returns to baseline schedule
+
+**How AI Decides:**
+- Analyzes recent execution history (last 24 hours)
+- Looks at success rates, failure patterns, response times
+- Suggests adjustments while respecting your min/max constraints
+- All hints have expiration times (TTL) - typically 15-60 minutes
+
+### Pause State
+
+You can temporarily **pause** an endpoint:
+
+- Stops all execution until a specified time
+- Useful for maintenance windows or debugging
+- Set to `null` to resume immediately
+- Overrides all other scheduling (baseline and AI hints)
+
+## How Scheduling Works
+
+The system picks the next run time using this priority order:
+
+1. **Paused?** → If yes, return the pause-until time
+2. **AI one-shot hint active?** → If yes, use that time
+3. **AI interval hint active?** → If yes, use last run + AI interval
+4. **Baseline cron configured?** → If yes, calculate next cron time
+5. **Baseline interval configured?** → Use last run + baseline interval
+
+**Then apply safety constraints:**
+- Clamp to minimum interval (if configured)
+- Clamp to maximum interval (if configured)
+
+This ensures AI suggestions always stay within your safety boundaries.
+
+## Safety Constraints
+
+### Minimum Interval
+
+Prevents over-execution:
+
+```
+minIntervalMs: 30000  // At least 30 seconds between runs
+```
+
+**Use when:**
+- Protecting API rate limits
+- Preventing database overload
+- Avoiding costs from too-frequent polling
+
+**Example**: Health check every 5 minutes, but AI can't go faster than every 30 seconds.
+
+### Maximum Interval
+
+Ensures timely execution:
+
+```
+maxIntervalMs: 3600000  // At most 1 hour between runs
+```
+
+**Use when:**
+- Data must stay fresh (max 1 hour old)
+- SLAs require regular checks
+- Compliance needs frequent execution
+
+**Example**: Sync every 5 minutes, but even if AI backs off, run at least every hour.
+
+### Execution Timeout
+
+Maximum time for the HTTP request:
+
+```
+timeoutMs: 30000  // Request must complete within 30 seconds
+```
+
+If the request takes longer, it's cancelled and marked as timeout.
+
+## Execution Tracking
+
+### Run History
+
+Every execution creates a **run** record with:
+
+- **Status**: success, failure, timeout, or cancelled
+- **Duration**: How long the execution took (milliseconds)
+- **Timestamps**: When it started and finished
+- **Error**: Error message (if failed)
+- **Source**: Why it ran (baseline-cron, baseline-interval, ai-interval, ai-oneshot, etc.)
+
+### Failure Tracking
+
+Endpoints track consecutive failures:
+
+- **Failure count**: Increments on failure, resets to 0 on success
+- **AI uses this**: To decide on backoff strategies
+- **You see this**: In the UI for monitoring health
+
+## Multi-Tenancy
+
+Every job and endpoint belongs to your account (tenant):
+
+- **Complete isolation**: You only see your own jobs and data
+- **Secure execution**: Endpoints run with your credentials
+- **Per-account quotas**: Usage limits apply per account
+
+## Common Patterns
+
+### Health Check with Adaptive Frequency
+
+```
+Baseline: Every 5 minutes (300000ms)
+Min: 30 seconds (30000ms)
+Max: 15 minutes (900000ms)
+
+AI behavior:
+- Normal: Runs every 5 minutes
+- Errors detected: Increases to every 30 seconds
+- All healthy: Backs off to every 15 minutes
+```
+
+### Daily Maintenance with Safety Net
+
+```
+Baseline: "0 2 * * *" (daily at 2am)
+Max: 26 hours
+
+Behavior:
+- Normally runs at 2am daily
+- If it fails, max interval ensures retry within 26 hours
+- Won't accidentally skip days
+```
+
+### API Polling with Rate Limit Protection
+
+```
+Baseline: Every minute (60000ms)
+Min: 30 seconds (30000ms) - protects rate limit
+Max: 5 minutes (300000ms) - keeps data fresh
+
+AI behavior:
+- Adjusts between 30s and 5min based on data changes
+- 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/introduction.md

@@ -0,0 +1,152 @@
+---
+id: introduction
+title: Introduction to Cronicorn
+description: AI-powered adaptive scheduling for modern applications
+tags:
+  - user
+  - assistant
+  - essential
+sidebar_position: 1
+mcp:
+  uri: file:///docs/introduction.md
+  mimeType: text/markdown
+  priority: 0.9
+  lastModified: 2025-11-02T00:00:00Z
+---
+
+# Introduction to Cronicorn
+
+**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.
+
+## What is Cronicorn?
+
+Cronicorn is a scheduling service that combines:
+
+- **Traditional cron scheduling** - Set fixed intervals or cron expressions
+- **AI-powered adaptation** (optional) - Automatically adjust timing based on success rates, failure patterns, and performance
+- **HTTP endpoint execution** - Call any HTTP endpoint on your schedule
+- **Real-time monitoring** - Track execution history, success rates, and performance
+
+## Why Use Cronicorn?
+
+### Problems with Static Schedulers
+
+Traditional cron jobs have limitations:
+
+- **Fixed timing** - Run every 5 minutes whether needed or not
+- **No learning** - Repeated failures don't trigger automatic backoff
+- **Manual intervention** - You adjust schedules manually based on metrics
+- **Resource waste** - Over-polling wastes API rate limits and costs
+
+### How Cronicorn Helps
+
+**For all users:**
+- Set it and forget it - Define baseline schedules that just work
+- Real-time visibility - Track all executions with detailed history
+- Flexible scheduling - Use cron expressions or simple intervals
+- Constraint protection - Set min/max intervals to prevent over/under execution
+
+**With AI enabled (optional):**
+- Automatic adaptation - Schedules adjust based on actual performance
+- Intelligent backoff - Reduces frequency after failures automatically
+- Dynamic optimization - Increases frequency when needed, decreases when idle
+- Always respects your constraints - AI suggestions stay within your min/max limits
+
+## Key Features
+
+### 🗓️ Flexible Scheduling
+
+- **Cron expressions**: `"0 */5 * * *"` for traditional cron syntax
+- **Simple intervals**: `300000` (milliseconds) for straightforward timing
+- **One-time runs**: Schedule immediate or future single executions
+- **Pause/resume**: Temporarily disable endpoints for maintenance
+
+### 🤖 AI Adaptation (Optional)
+
+When enabled, the AI planner:
+
+- Analyzes execution patterns (success rates, failure streaks, response times)
+- Suggests interval adjustments with expiration times (TTL)
+- Respects your configured min/max constraints
+- Gracefully degrades - baseline schedule continues if AI is unavailable
+
+**Note**: Cronicorn works perfectly without AI. The baseline scheduler is production-ready and reliable.
+
+### 📊 Complete Visibility
+
+- **Run history**: Every execution with timestamps, duration, status
+- **Error tracking**: Detailed error messages for failures
+- **Success metrics**: Track success rates and identify patterns
+- **Scheduling transparency**: See why each run happened (baseline, AI hint, etc.)
+
+### 🛡️ Production Ready
+
+- **Reliable execution**: Database-backed with distributed locking
+- **Constraint protection**: Min/max intervals prevent runaway schedules
+- **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
+2. **Add Endpoints** - HTTP endpoints with baseline schedules
+3. **Set Constraints** (optional) - Min/max intervals for safety
+4. **Enable AI** (optional) - Let AI optimize timing automatically
+5. **Monitor** - Track execution history and performance
+
+## Who Is Cronicorn For?
+
+- **SaaS developers** monitoring API health across services
+- **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