@cronicorn/mcp-server 1.5.9 → 1.6.1

package/dist/docs/competitive-analysis.md

@@ -0,0 +1,324 @@
+---
+id: competitive-analysis
+title: How Cronicorn Compares
+description: Understand how Cronicorn stacks up against other job scheduling platforms
+sidebar_label: Competitive Analysis
+sidebar_position: 5
+tags:
+  - user
+  - comparison
+  - features
+mcp:
+  uri: file:///docs/competitive-analysis.md
+  mimeType: text/markdown
+  priority: 0.7
+  lastModified: 2025-11-04T00:00:00Z
+---
+
+# How Cronicorn Compares to Other Job Schedulers
+
+**TL;DR**: Cronicorn is the only platform that automatically adapts job schedules based on real-time performance. While others offer static cron or complex workflow orchestration, Cronicorn learns from your endpoints and optimizes timing automatically—all while staying within your safety constraints.
+
+Cronicorn is purpose-built for **adaptive HTTP job scheduling**—a unique position in the workflow automation landscape. Here's how we compare to popular alternatives.
+
+## Quick Comparison
+
+| Feature | Cronicorn | Trigger.dev | Inngest | Temporal | QStash | n8n | Windmill |
+|---------|-----------|-------------|---------|----------|--------|-----|----------|
+| **AI-Adaptive Scheduling** | ✅ Core Feature | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **HTTP Endpoint Execution** | ✅ | ✅ | ✅ | ⚠️ Manual | ✅ | ✅ | ✅ |
+| **Cron/Interval Scheduling** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| **Self-Hosted** | ✅ Free | ✅ Complex | ✅ Free | ✅ Complex | ❌ | ✅ Free | ✅ Free |
+| **Entry Price** | Free (soon) | $10/mo | Free | $100/mo | Free | Free | Free |
+| **Learning Curve** | Low | Medium | Medium | High | Low | Low | High |
+| **Best For** | HTTP health checks, API polling, adaptive workflows | AI workflows, TypeScript apps | Event-driven serverless | Enterprise orchestration | Simple webhooks | Visual workflows, integrations | Internal tools |
+
+### At a Glance
+
+**Cronicorn** = Cron that learns and adapts automatically  
+**Trigger.dev** = Code-first workflow orchestration for TypeScript  
+**Inngest** = Event-driven serverless background jobs  
+**Temporal** = Enterprise workflow engine for distributed systems  
+**QStash** = Serverless HTTP message queue  
+**n8n** = Visual workflow automation with 400+ integrations  
+**Windmill** = Developer platform for internal tools  
+
+---
+
+## 🎯 Why Choose Cronicorn?
+
+### 1. **True AI-Powered Adaptation**
+
+**Cronicorn is the only platform that automatically adjusts job timing based on real-world performance.**
+
+While other platforms offer static scheduling or complex workflow orchestration, Cronicorn learns from your endpoints:
+
+- **Backs off automatically** when detecting rate limits or failures
+- **Speeds up** when detecting backlogs or increased activity
+- **Maintains stability** by slowing execution during idle periods
+- **Stays within your constraints** - AI respects your min/max limits
+
+**Example**: Your health check runs every 5 minutes baseline. When errors spike, Cronicorn adapts to every 30 seconds. When everything's stable for hours, it backs off to every 15 minutes—all automatically.
+
+**Competitors**: Static schedules that run regardless of conditions. You manually adjust based on metrics.
+
+---
+
+### 2. **Simplicity for HTTP Job Scheduling**
+
+**Cronicorn is purpose-built for HTTP endpoints. Others require complex setup.**
+
+- **Trigger.dev**: Requires writing TypeScript code, deploying functions, managing builds
+- **Inngest**: Event-driven model adds complexity for simple polling
+- **Temporal**: Heavy enterprise framework, steep learning curve
+- **Windmill**: Powerful but requires learning workflow DSL and script management
+
+**Cronicorn**: Define a URL, set baseline schedule, done. Optional AI optimization with zero code changes.
+
+```json
+{
+  "name": "Health Check",
+  "url": "https://api.example.com/health",
+  "method": "GET",
+  "baselineIntervalMs": 300000,
+  "minIntervalMs": 30000,
+  "maxIntervalMs": 900000
+}
+```
+
+---
+
+### 3. **Transparent, Explainable Scheduling**
+
+**Every scheduling decision is explained in plain English.**
+
+Cronicorn shows you exactly why each job ran when it did:
+
+- "Baseline cron schedule (every 5 minutes)"
+- "AI increased frequency—3 consecutive failures detected"
+- "AI decreased interval—stable for 2 hours, no errors"
+- "Clamped to minimum interval (rate limit protection)"
+
+**Competitors**: Black-box scheduling. You see *when* jobs run, but not *why* the timing was chosen.
+
+---
+
+### 4. **Constraint Protection Built-In**
+
+**Safety constraints prevent runaway costs and rate limit violations.**
+
+Set min/max intervals, and Cronicorn guarantees:
+- ✅ Jobs never run faster than your minimum (protects rate limits)
+- ✅ Jobs never run slower than your maximum (ensures freshness)
+- ✅ AI suggestions are always clamped to safe ranges
+
+**Example**: API allows 100 requests/hour. Set min interval to 36 seconds—Cronicorn will never exceed your quota, even with AI enabled.
+
+**Competitors**: QStash and Trigger.dev have rate limiting, but not adaptive constraint-aware scheduling.
+
+---
+
+### 5. **Works Without AI** 
+
+**Cronicorn is a production-ready scheduler even without AI.**
+
+The baseline scheduler is:
+- Reliable (database-backed with distributed locks)
+- Flexible (cron expressions or simple intervals)
+- Complete (pause/resume, run history, error tracking)
+
+Enable AI when you want optimization. Disable it if you prefer predictable behavior.
+
+**Competitors**: All-or-nothing. You get their workflow model or nothing.
+
+---
+
+## Platform-by-Platform Comparison
+
+### 🆚 Cronicorn vs. Trigger.dev
+
+**Trigger.dev** is excellent for complex, multi-step workflows and AI agent orchestration in TypeScript.
+
+| What Trigger.dev Does Better | What Cronicorn Does Better |
+|------------------------------|---------------------------|
+| Multi-step workflow orchestration | Automatic schedule adaptation |
+| Built-in AI SDK integrations | Zero-code HTTP job scheduling |
+| TypeScript-native development | Transparent scheduling decisions |
+| Real-time streaming to frontend | Constraint-based safety |
+| Long-running background jobs | Simple setup for HTTP endpoints |
+
+**Choose Trigger.dev if**: You need complex, code-based workflows with multiple steps, retries, and AI integration.
+
+**Choose Cronicorn if**: You want HTTP endpoints to run on adaptive schedules with minimal setup and automatic optimization.
+
+**Use both**: Cronicorn schedules your Trigger.dev workflow endpoints, adapting their timing based on performance.
+
+---
+
+### 🆚 Cronicorn vs. Inngest
+
+**Inngest** excels at event-driven architectures and serverless background jobs.
+
+| What Inngest Does Better | What Cronicorn Does Better |
+|-------------------------|---------------------------|
+| Event-driven workflows | Time-based adaptive scheduling |
+| Durable step functions | Explainable scheduling decisions |
+| Built-in retry/recovery | AI learns from job performance |
+| Multi-language SDKs (TS/Python/Go) | Simpler setup for cron jobs |
+| Webhook transformations | Transparent min/max constraints |
+
+**Choose Inngest if**: You have event-driven workflows triggered by user actions, webhooks, or app events.
+
+**Choose Cronicorn if**: You need scheduled HTTP jobs that adapt their timing based on success rates and patterns.
+
+**Use both**: Inngest handles event-driven logic; Cronicorn schedules the periodic data syncs and health checks.
+
+---
+
+### 🆚 Cronicorn vs. Temporal
+
+**Temporal** is the gold standard for distributed workflow orchestration in enterprise environments.
+
+| What Temporal Does Better | What Cronicorn Does Better |
+|--------------------------|---------------------------|
+| Long-running sagas and distributed transactions | Simple HTTP job scheduling |
+| Enterprise-grade reliability | AI-powered schedule adaptation |
+| Multi-language SDKs | Easy setup and maintenance |
+| Fine-grained workflow control | Transparent, explainable timing |
+| Advanced replay and versioning | Lower operational complexity |
+
+**Pricing**: Temporal Cloud starts at $100/month; Cronicorn plans to be free for basic usage.
+
+**Choose Temporal if**: You need bulletproof workflow orchestration for mission-critical distributed systems.
+
+**Choose Cronicorn if**: You want HTTP endpoints to run on smart schedules without enterprise-level complexity.
+
+**Use both**: Temporal orchestrates complex business processes; Cronicorn handles the adaptive scheduled triggers.
+
+---
+
+### 🆚 Cronicorn vs. QStash (Upstash)
+
+**QStash** is a great serverless message queue for simple HTTP job delivery.
+
+| What QStash Does Better | What Cronicorn Does Better |
+|------------------------|---------------------------|
+| Simple serverless pricing | AI-adaptive scheduling |
+| Fan-out to multiple endpoints | Schedule optimization based on performance |
+| Integration with Upstash ecosystem | Explainable scheduling decisions |
+| Lower operational overhead | Constraint-aware adaptation |
+| HTTP-first message queue | Real-time monitoring dashboard |
+
+**Pricing**: QStash free tier (1k messages/day); paid plans start at $1 per 100k messages. Cronicorn plans similar affordability.
+
+**Choose QStash if**: You need a simple message queue with retries and don't need adaptive scheduling.
+
+**Choose Cronicorn if**: You want your scheduled jobs to automatically optimize timing based on real-world conditions.
+
+**Use both**: QStash handles message delivery; Cronicorn schedules when those messages should be sent.
+
+---
+
+### 🆚 Cronicorn vs. Windmill
+
+**Windmill** is a powerful open-source platform for internal tools and workflow automation.
+
+| What Windmill Does Better | What Cronicorn Does Better |
+|--------------------------|---------------------------|
+| Script-to-UI generation | Focused HTTP job scheduling |
+| Multi-language support (Python, Go, Rust, etc.) | AI-adaptive timing |
+| Internal app builder | Simpler learning curve |
+| Git-based workflow versioning | Transparent scheduling explanations |
+| Extensive integrations library | Purpose-built for HTTP endpoints |
+
+**Choose Windmill if**: You need a full developer platform for building internal tools, scripts, and complex workflows.
+
+**Choose Cronicorn if**: You specifically need HTTP endpoints to run on adaptive, intelligent schedules.
+
+**Use both**: Windmill builds your internal automation scripts; Cronicorn schedules them with adaptive timing.
+
+---
+
+### 🆚 Cronicorn vs. n8n
+
+**n8n** is a popular open-source workflow automation platform with a visual node-based editor and 400+ integrations.
+
+| What n8n Does Better | What Cronicorn Does Better |
+|---------------------|---------------------------|
+| Visual workflow builder (drag-and-drop) | AI-adaptive scheduling |
+| 400+ pre-built integrations | Purpose-built for HTTP endpoints |
+| Multi-app workflow orchestration | Automatic schedule optimization |
+| Low-code/no-code friendly | Explainable scheduling decisions |
+| Custom JavaScript/Python in workflows | Constraint-aware adaptation |
+
+**Pricing**: n8n free (self-hosted); Cloud starts at $20/mo (2,500 executions). Cronicorn plans similar affordability.
+
+**Choose n8n if**: You need to connect multiple apps together in visual workflows, especially for non-developers.
+
+**Choose Cronicorn if**: You need HTTP endpoints with intelligent, adaptive scheduling that learns from performance.
+
+**Use both**: n8n orchestrates multi-step workflows; Cronicorn provides the adaptive scheduling trigger with webhooks. Many teams use Cronicorn to trigger n8n workflows at optimized times based on real conditions.
+
+---
+
+## What Makes Cronicorn Unique?
+
+### The "Adaptive Cron" Gap
+
+Every existing tool falls into one of two categories:
+
+1. **Static cron schedulers** - Run jobs at fixed intervals, regardless of conditions
+2. **Complex workflow engines** - Powerful orchestration, but require significant setup
+
+**Cronicorn is the first to offer adaptive, intelligent scheduling for HTTP endpoints without the complexity.**
+
+We fill the gap between "too simple" and "too complex":
+
+1. **Simpler than workflow engines** - No code deployment, no learning DSLs, just configure a URL
+2. **Smarter than static cron** - Learns and adapts automatically based on actual performance
+3. **Safer than manual tuning** - Built-in constraints prevent runaway schedules and rate limit violations
+4. **More transparent than black boxes** - Every decision is explained in plain English
+
+### When Cronicorn Shines
+
+**Perfect for these use cases:**
+
+✅ **API Health Monitoring** - Automatically increase check frequency when errors occur, back off when stable  
+✅ **Data Synchronization** - Speed up during business hours when changes are frequent, slow down overnight  
+✅ **Web Scraping** - Intelligently back off when rate-limited, resume optimal frequency when quota resets  
+✅ **Webhook Retries** - Adaptive exponential backoff based on downstream service patterns  
+✅ **Scheduled Maintenance** - Run within maintenance windows while adapting to system load  
+✅ **External API Polling** - Optimize request frequency based on data freshness and change patterns  
+
+### When to Consider Alternatives
+
+**Consider these platforms when you need:**
+
+- **Trigger.dev**: Multi-step TypeScript workflows, AI agent orchestration, complex retry logic
+- **Inngest**: Event-driven serverless architectures triggered by user actions or webhooks
+- **Temporal**: Enterprise-grade distributed workflow orchestration with saga patterns
+- **QStash**: Simple serverless message queue without adaptive scheduling needs
+- **n8n**: Visual workflow automation connecting multiple apps with drag-and-drop interface
+- **Windmill**: Full internal tool platform with script-to-UI generation
+
+**Or combine them**: Many teams use Cronicorn for adaptive scheduling alongside these platforms for workflow orchestration.  
+
+---
+
+## Pricing Comparison (Early 2025)
+
+| Platform | Free Tier | Starter Plan | Enterprise |
+|----------|-----------|--------------|------------|
+| **Cronicorn** | Coming soon | Coming soon | Contact |
+| **Trigger.dev** | 5 credits/mo | $10/mo (10 credits) | Custom |
+| **Inngest** | 50k executions/mo | $75/mo (1M executions) | Custom |
+| **Temporal Cloud** | Self-host only | $100/mo | Custom |
+| **QStash** | 1k messages/day | Pay-as-you-go ($1/100k) | Custom |
+| **n8n** | Self-host free | $20/mo (2,500 executions) | Custom |
+| **Windmill** | Self-host free | $120/mo cloud | $170/mo self-hosted |
+
+**Cronicorn's pricing philosophy**: Simple, affordable, transparent. Coming soon.
+
+---
+
+*Last updated: November 2025. Competitor information based on publicly available documentation and pricing as of this date.*

package/dist/docs/developers/README.md

@@ -0,0 +1,29 @@
+---
+id: developers-overview
+title: Developer Overview
+description: Documentation for developers contributing to Cronicorn
+tags:
+  - developer
+sidebar_position: 0
+mcp:
+  uri: file:///docs/developers/overview.md
+---
+
+# Developer Documentation
+
+Documentation for developers contributing to Cronicorn's codebase or building AI agents that interact with Cronicorn.
+
+## Getting Started
+
+- **[Quick Start](./quick-start.md)** - Set up your development environment in 4 steps
+- **[Authentication](./authentication.md)** - Configure admin user or GitHub OAuth
+- **[Workspace Structure](./workspace-structure.md)** - Monorepo organization (apps and packages)
+- **[Quality Checks](./quality-checks.md)** - Required checks before committing and merging
+
+## Architecture & Design
+
+- **[System Architecture](../technical/system-architecture.md)** - Core concepts and design patterns
+
+## Contributing
+
+For contributors working on Cronicorn's codebase, additional technical guidelines are available in the repository's `.github/instructions/` directory.

package/dist/docs/developers/authentication.md

@@ -0,0 +1,177 @@
+---
+id: developer-authentication
+title: Authentication Configuration
+description: Configure authentication methods for your Cronicorn deployment
+tags:
+  - developer
+  - configuration
+sidebar_position: 2
+mcp:
+  uri: file:///docs/developers/authentication.md
+  mimeType: text/markdown
+  priority: 0.8
+---
+
+# Authentication Configuration
+
+Cronicorn supports two authentication methods. At least one must be enabled.
+
+## Quick Reference
+
+```bash
+# Admin User (local dev, CI/CD)
+ADMIN_USER_EMAIL=admin@example.com
+ADMIN_USER_PASSWORD=your-secure-password-min-8-chars
+
+# GitHub OAuth (production)
+GITHUB_CLIENT_ID=your_github_client_id
+GITHUB_CLIENT_SECRET=your_github_client_secret
+```
+
+**Choose based on your use case:**
+- **Local Dev**: Admin user only (no OAuth setup needed)
+- **Production**: GitHub OAuth (for multiple users)
+- **Hybrid**: Both (admins use email, users use GitHub)
+
+## Admin User Setup
+
+Perfect for development and self-hosting.
+
+**1. Edit `.env`:**
+```bash
+ADMIN_USER_EMAIL=admin@example.com
+ADMIN_USER_PASSWORD=your-secure-password
+ADMIN_USER_NAME=Admin  # Optional
+```
+
+**2. Restart the app** - admin user auto-created on startup
+
+**3. Login** at `http://localhost:5173/login` with your email/password
+
+**Benefits**: ✅ No OAuth app needed, ✅ Works offline, ✅ Perfect for CI/CD
+
+## GitHub OAuth Setup
+
+Best for production with multiple users.
+
+**1. [Create GitHub OAuth app](https://github.com/settings/developers)**
+
+**2. Set callback URL:**
+```
+${BETTER_AUTH_URL}/api/auth/callback/github
+```
+Example: `http://localhost:3333/api/auth/callback/github`
+
+**3. Add to `.env`:**
+```bash
+GITHUB_CLIENT_ID=your_client_id
+GITHUB_CLIENT_SECRET=your_client_secret
+```
+
+**4. Login** - click "Sign in with GitHub" button
+
+## Validation Rules
+
+**At least one method required.** App validates on startup:
+
+| Configuration | Status |
+|---------------|--------|
+| Admin user only | ✅ Works |
+| GitHub OAuth only | ✅ Works |
+| Both enabled | ✅ Works |
+| Neither enabled | ❌ Fails |
+
+## Required Environment Variables
+
+### Base Config (Always Required)
+
+```bash
+DATABASE_URL=postgresql://user:password@localhost:6666/db
+BETTER_AUTH_SECRET=$(openssl rand -base64 32)
+BETTER_AUTH_URL=http://localhost:3333
+WEB_URL=http://localhost:5173
+```
+
+### Admin User (Optional*)
+
+| Variable | Description |
+|----------|-------------|
+| `ADMIN_USER_EMAIL` | Valid email address |
+| `ADMIN_USER_PASSWORD` | Minimum 8 characters |
+| `ADMIN_USER_NAME` | Display name (optional) |
+
+*Required if GitHub OAuth not configured
+
+### GitHub OAuth (Optional*)
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_CLIENT_ID` | From GitHub OAuth app |
+| `GITHUB_CLIENT_SECRET` | From GitHub OAuth app |
+
+*Required if admin user not configured
+
+## Common Issues
+
+### Admin user not created
+
+1. Check both `ADMIN_USER_EMAIL` and `ADMIN_USER_PASSWORD` are in `.env`
+2. Restart the application
+3. Check logs for "Admin user created successfully"
+
+### Login returns 404
+
+1. Restart API server after changing `.env`
+2. Verify: `curl http://localhost:3333/api/auth/config`
+
+### Wrong credentials
+
+1. Check email/password match `.env` exactly (case-sensitive)
+2. Password must be at least 8 characters
+3. Remove any extra whitespace
+
+## Production Configuration
+
+**Admin for emergency access:**
+```bash
+ADMIN_USER_EMAIL=admin@yourdomain.com
+ADMIN_USER_PASSWORD=${SECRET_FROM_VAULT}
+```
+
+**GitHub for regular users:**
+```bash
+GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
+GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
+BETTER_AUTH_URL=https://api.yourdomain.com
+WEB_URL=https://yourdomain.com
+```
+
+**Security**: Use secrets manager, not plain `.env` files
+
+## Programmatic Access
+
+### Bearer Tokens (CLI/AI Agents)
+
+```bash
+# 1. Initiate device flow
+curl -X POST http://localhost:3333/api/auth/device/code
+
+# 2. User authorizes in browser
+
+# 3. Poll for token
+curl -X POST http://localhost:3333/api/auth/device/token \
+  -d "device_code=DEVICE_CODE"
+
+# 4. Use in API requests
+curl -H "Authorization: Bearer TOKEN" \
+  http://localhost:3333/api/jobs
+```
+
+### API Keys
+
+Generate in web UI at `/settings/api-keys`:
+
+```bash
+curl -H "X-API-Key: your-api-key" \
+  http://localhost:3333/api/jobs
+```