@cronicorn/mcp-server 1.15.0 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/dist/docs/developers/authentication.md +56 -112
  2. package/dist/docs/developers/environment-configuration.md +50 -144
  3. package/dist/docs/developers/quick-start.md +28 -20
  4. package/dist/index.js +138 -1
  5. package/dist/index.js.map +1 -1
  6. package/package.json +1 -1
package/dist/docs/developers/authentication.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  id: developer-authentication
3
3
  title: Authentication Configuration
4
- description: Configure authentication methods for your Cronicorn deployment
4
+ description: Configure GitHub OAuth, API keys, and programmatic access
5
5
  tags:
6
6
  - developer
7
7
  - configuration
@@ -14,45 +14,22 @@ mcp:
14
14
 
15
15
  # Authentication Configuration
16
16
 
17
- Cronicorn supports two authentication methods. At least one must be enabled.
17
+ > **Getting started?** See [Quick Start](./quick-start.md) - no configuration required for local development.
18
18
 
19
- ## Quick Reference
19
+ This guide covers advanced authentication setup: GitHub OAuth for production, API keys, and programmatic access.
20
20
 
21
- ```bash
22
- # Admin User (local dev, CI/CD)
23
- ADMIN_USER_EMAIL=admin@example.com
24
- ADMIN_USER_PASSWORD=your-secure-password-min-8-chars
25
-
26
- # GitHub OAuth (production)
27
- GITHUB_CLIENT_ID=your_github_client_id
28
- GITHUB_CLIENT_SECRET=your_github_client_secret
29
- ```
30
-
31
- **Choose based on your use case:**
32
- - **Local Dev**: Admin user only (no OAuth setup needed)
33
- - **Production**: GitHub OAuth (for multiple users)
34
- - **Hybrid**: Both (admins use email, users use GitHub)
35
-
36
- ## Admin User Setup
37
-
38
- Perfect for development and self-hosting.
39
-
40
- **1. Edit `.env`:**
41
- ```bash
42
- ADMIN_USER_EMAIL=admin@example.com
43
- ADMIN_USER_PASSWORD=your-secure-password
44
- ADMIN_USER_NAME=Admin # Optional
45
- ```
46
-
47
- **2. Restart the app** - admin user auto-created on startup
21
+ ## Authentication Methods
48
22
 
49
- **3. Login** at `http://localhost:5173/login` with your email/password
50
-
51
- **Benefits**: ✅ No OAuth app needed, ✅ Works offline, ✅ Perfect for CI/CD
23
+ | Method | Use Case | Setup Required |
24
+ |--------|----------|----------------|
25
+ | Admin User | Local dev, self-hosting | None (works by default) |
26
+ | GitHub OAuth | Production with multiple users | GitHub OAuth app |
27
+ | API Keys | Service-to-service | Generate in web UI |
28
+ | Bearer Tokens | CLI/AI agents | Device authorization flow |
52
29
 
53
30
  ## GitHub OAuth Setup
54
31
 
55
- Best for production with multiple users.
32
+ Best for production deployments with multiple users.
56
33
 
57
34
  **1. [Create GitHub OAuth app](https://github.com/settings/developers)**
58
35
 
@@ -60,7 +37,7 @@ Best for production with multiple users.
60
37
  ```
61
38
  ${BETTER_AUTH_URL}/api/auth/callback/github
62
39
  ```
63
- Example: `http://localhost:3333/api/auth/callback/github`
40
+ Example: `https://api.yourdomain.com/api/auth/callback/github`
64
41
 
65
42
  **3. Add to `.env`:**
66
43
  ```bash
@@ -68,110 +45,77 @@ GITHUB_CLIENT_ID=your_client_id
68
45
  GITHUB_CLIENT_SECRET=your_client_secret
69
46
  ```
70
47
 
71
- **4. Login** - click "Sign in with GitHub" button
72
-
73
- ## Validation Rules
48
+ **4. Restart the app** - "Sign in with GitHub" button will appear
74
49
 
75
- **At least one method required.** App validates on startup:
76
-
77
- | Configuration | Status |
78
- |---------------|--------|
79
- | Admin user only | ✅ Works |
80
- | GitHub OAuth only | ✅ Works |
81
- | Both enabled | ✅ Works |
82
- | Neither enabled | ❌ Fails |
50
+ ## Programmatic Access
83
51
 
84
- ## Required Environment Variables
52
+ ### API Keys
85
53
 
86
- ### Base Config (Always Required)
54
+ Generate in web UI at `/settings/api-keys`:
87
55
 
88
56
  ```bash
89
- DATABASE_URL=postgresql://user:password@localhost:6666/db
90
- BETTER_AUTH_SECRET=$(openssl rand -base64 32)
91
- BETTER_AUTH_URL=http://localhost:3333
92
- WEB_URL=http://localhost:5173
57
+ curl -H "X-API-Key: your-api-key" \
58
+ http://localhost:3333/api/jobs
93
59
  ```
94
60
 
95
- ### Admin User (Optional*)
96
-
97
- | Variable | Description |
98
- |----------|-------------|
99
- | `ADMIN_USER_EMAIL` | Valid email address |
100
- | `ADMIN_USER_PASSWORD` | Minimum 8 characters |
101
- | `ADMIN_USER_NAME` | Display name (optional) |
102
-
103
- *Required if GitHub OAuth not configured
104
-
105
- ### GitHub OAuth (Optional*)
106
-
107
- | Variable | Description |
108
- |----------|-------------|
109
- | `GITHUB_CLIENT_ID` | From GitHub OAuth app |
110
- | `GITHUB_CLIENT_SECRET` | From GitHub OAuth app |
111
-
112
- *Required if admin user not configured
113
-
114
- ## Common Issues
115
-
116
- ### Admin user not created
61
+ ### Bearer Tokens (CLI/AI Agents)
117
62
 
118
- 1. Check both `ADMIN_USER_EMAIL` and `ADMIN_USER_PASSWORD` are in `.env`
119
- 2. Restart the application
120
- 3. Check logs for "Admin user created successfully"
63
+ Use the OAuth device authorization flow:
121
64
 
122
- ### Login returns 404
65
+ ```bash
66
+ # 1. Initiate device flow
67
+ curl -X POST http://localhost:3333/api/auth/device/code
123
68
 
124
- 1. Restart API server after changing `.env`
125
- 2. Verify: `curl http://localhost:3333/api/auth/config`
69
+ # 2. User authorizes in browser at the provided URL
126
70
 
127
- ### Wrong credentials
71
+ # 3. Poll for token
72
+ curl -X POST http://localhost:3333/api/auth/device/token \
73
+ -d "device_code=DEVICE_CODE"
128
74
 
129
- 1. Check email/password match `.env` exactly (case-sensitive)
130
- 2. Password must be at least 8 characters
131
- 3. Remove any extra whitespace
75
+ # 4. Use in API requests
76
+ curl -H "Authorization: Bearer TOKEN" \
77
+ http://localhost:3333/api/jobs
78
+ ```
132
79
 
133
80
  ## Production Configuration
134
81
 
135
- **Admin for emergency access:**
136
82
  ```bash
83
+ # Required: Secure secret (generate with: openssl rand -base64 32)
84
+ BETTER_AUTH_SECRET=your-secure-random-secret-min-32-chars
85
+
86
+ # Required: Production URLs
87
+ BETTER_AUTH_URL=https://api.yourdomain.com
88
+ WEB_URL=https://yourdomain.com
89
+
90
+ # Option A: Admin user for emergency access
137
91
  ADMIN_USER_EMAIL=admin@yourdomain.com
138
92
  ADMIN_USER_PASSWORD=${SECRET_FROM_VAULT}
139
- ```
140
93
 
141
- **GitHub for regular users:**
142
- ```bash
94
+ # Option B: GitHub OAuth for regular users
143
95
  GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
144
96
  GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
145
- BETTER_AUTH_URL=https://api.yourdomain.com
146
- WEB_URL=https://yourdomain.com
147
97
  ```
148
98
 
149
- **Security**: Use secrets manager, not plain `.env` files
99
+ > ⚠️ **Security**: Use a secrets manager in production, not plain `.env` files.
150
100
 
151
- ## Programmatic Access
152
-
153
- ### Bearer Tokens (CLI/AI Agents)
154
-
155
- ```bash
156
- # 1. Initiate device flow
157
- curl -X POST http://localhost:3333/api/auth/device/code
101
+ ## Validation Rules
158
102
 
159
- # 2. User authorizes in browser
103
+ At least one authentication method must be configured:
160
104
 
161
- # 3. Poll for token
162
- curl -X POST http://localhost:3333/api/auth/device/token \
163
- -d "device_code=DEVICE_CODE"
105
+ | Configuration | Status |
106
+ |---------------|--------|
107
+ | Admin user only | ✅ Works |
108
+ | GitHub OAuth only | ✅ Works |
109
+ | Both enabled | ✅ Works |
110
+ | Neither enabled | ❌ App won't start |
164
111
 
165
- # 4. Use in API requests
166
- curl -H "Authorization: Bearer TOKEN" \
167
- http://localhost:3333/api/jobs
168
- ```
112
+ ## Troubleshooting
169
113
 
170
- ### API Keys
114
+ **Login returns 404?**
115
+ → Restart API server after changing `.env`
171
116
 
172
- Generate in web UI at `/settings/api-keys`:
117
+ **Admin user not created?**
118
+ → Run `pnpm db:seed` or check logs for "Admin user created"
173
119
 
174
- ```bash
175
- curl -H "X-API-Key: your-api-key" \
176
- http://localhost:3333/api/jobs
177
- ```
120
+ **GitHub OAuth not working?**
121
+ → Verify callback URL matches `${BETTER_AUTH_URL}/api/auth/callback/github`
package/dist/docs/developers/environment-configuration.md CHANGED
@@ -1,197 +1,103 @@
1
1
  ---
2
2
  id: environment-configuration
3
3
  title: Environment Configuration
4
- description: Understanding Cronicorn's zero-config approach and environment variables
4
+ description: Complete reference for all Cronicorn environment variables
5
5
  tags:
6
6
  - developer
7
7
  - configuration
8
- - setup
9
- sidebar_position: 2
8
+ - reference
9
+ sidebar_position: 3
10
10
  ---
11
11
 
12
12
  # Environment Configuration
13
13
 
14
- ## Zero-Config Local Development
14
+ > **Getting started?** See [Quick Start](./quick-start.md) - no configuration required for local development.
15
15
 
16
- Cronicorn is designed for **zero-configuration local development**. All environment variables have sensible defaults, so you can run the entire stack without creating a `.env` file.
16
+ This is the complete reference for all environment variables. Local development works out of the box with sensible defaults.
17
17
 
18
- ```bash
19
- # That's it - no .env file needed!
20
- pnpm install
21
- pnpm db
22
- pnpm db:migrate
23
- pnpm dev
24
- ```
25
-
26
- Login at http://localhost:5173 with:
27
- - Email: `admin@example.com`
28
- - Password: `devpassword`
29
-
30
- ## How It Works
31
-
32
- ### Centralized Defaults
18
+ ## Default Values
33
19
 
34
- All default values are maintained in a single package: `@cronicorn/config-defaults`
20
+ All defaults are maintained in `@cronicorn/config-defaults` for consistency across apps.
35
21
 
36
- This ensures:
37
- - **Consistency** - Same defaults across all apps (API, scheduler, ai-planner, web)
38
- - **Maintainability** - One place to update defaults
39
- - **Type safety** - TypeScript constants prevent typos
40
- - **Security** - Production validation prevents using dev defaults
22
+ ### Development Defaults (No .env Required)
41
23
 
42
- ### Development Defaults
24
+ | Category | Variable | Default |
25
+ |----------|----------|---------|
26
+ | **Auth** | `ADMIN_USER_EMAIL` | `admin@example.com` |
27
+ | | `ADMIN_USER_PASSWORD` | `devpassword` |
28
+ | | `BETTER_AUTH_SECRET` | `dev-secret-DO-NOT-USE...` |
29
+ | **Database** | `DATABASE_URL` | `postgresql://user:password@localhost:6666/db` |
30
+ | **URLs** | `BETTER_AUTH_URL` | `http://localhost:3333` |
31
+ | | `WEB_URL` | `http://localhost:5173` |
32
+ | | `API_URL` | `http://localhost:3333` |
33
+ | **Ports** | `API_PORT` | `3333` |
34
+ | | `WEB_PORT` | `5173` |
35
+ | | `DB_PORT` | `6666` |
36
+ | **Stripe** | `STRIPE_SECRET_KEY` | `sk_test_dummy_key...` |
37
+ | | `STRIPE_WEBHOOK_SECRET` | `whsec_test_dummy...` |
43
38
 
44
- | Category | Variable | Default Value |
45
- |----------|----------|---------------|
46
- | **Ports** | API_PORT | 3333 |
47
- | | WEB_PORT | 5173 |
48
- | | DB_PORT | 6666 |
49
- | **Database** | DATABASE_URL | postgresql://user:password@localhost:6666/db |
50
- | **Auth** | ADMIN_USER_EMAIL | admin@example.com |
51
- | | ADMIN_USER_PASSWORD | devpassword |
52
- | | BETTER_AUTH_SECRET | dev-secret-DO-NOT-USE-IN-PRODUCTION-min32chars |
53
- | **URLs** | BETTER_AUTH_URL | http://localhost:3333 |
54
- | | WEB_URL | http://localhost:5173 |
55
- | | API_URL | http://localhost:3333 |
56
- | **Stripe** | STRIPE_SECRET_KEY | sk_test_dummy_key_for_local_dev_only |
57
- | | STRIPE_WEBHOOK_SECRET | whsec_test_dummy_secret_for_local_dev |
39
+ ⚠️ **Security**: These defaults are for local development only. Production must override them.
58
40
 
59
- ⚠️ **Security Warning**: These are insecure defaults for local development only. Production deployments MUST override these values.
41
+ ## Customizing for Local Development
60
42
 
61
- ## Customizing Configuration
62
-
63
-
64
- ### Full Configuration (.env.example)
65
-
66
- For production or advanced setup:
43
+ To override defaults locally, create a `.env` file:
67
44
 
68
45
  ```bash
69
- # Copy the full example
70
46
  cp .env.example .env
71
-
72
- # Edit with your production values
73
- vim .env
47
+ # Edit only the variables you need to change
74
48
  ```
75
49
 
76
- See all available variables with descriptions in `.env.example`.
77
-
78
50
  ## Production Deployment
79
51
 
80
- ### Required Changes
81
-
82
- Production deployments MUST set these variables:
52
+ Production deployments MUST override these variables:
83
53
 
84
54
  ```bash
85
55
  # 1. Secure auth secret (generate with: openssl rand -base64 32)
86
56
  BETTER_AUTH_SECRET=your-secure-random-secret-min-32-chars
87
57
 
88
- # 2. Choose authentication method:
89
- # Option A: Admin User
58
+ # 2. Production URLs
59
+ WEB_URL=https://yourdomain.com
60
+ API_URL=https://api.yourdomain.com
61
+ BETTER_AUTH_URL=https://api.yourdomain.com
62
+
63
+ # 3. Authentication (at least one required)
90
64
  ADMIN_USER_EMAIL=admin@yourcompany.com
91
65
  ADMIN_USER_PASSWORD=strong-unique-password
92
-
93
- # Option B: GitHub OAuth
66
+ # OR
94
67
  GITHUB_CLIENT_ID=your_github_client_id
95
68
  GITHUB_CLIENT_SECRET=your_github_client_secret
96
69
 
97
- # 3. Real Stripe keys (if using payments)
70
+ # 4. Stripe (if using payments)
98
71
  STRIPE_SECRET_KEY=sk_live_your_production_key
99
72
  STRIPE_WEBHOOK_SECRET=whsec_your_production_webhook_secret
100
- STRIPE_PRICE_PRO=price_live_pro_monthly
101
- STRIPE_PRICE_ENTERPRISE=price_live_enterprise_monthly
102
-
103
- # 4. Production URLs
104
- BASE_URL=https://your-production-domain.com
105
- WEB_URL=https://your-production-domain.com
106
- API_URL=https://api.your-production-domain.com
107
- BETTER_AUTH_URL=https://api.your-production-domain.com
108
73
  ```
109
74
 
110
- ### Production Validation
75
+ The app validates on startup and exits if dev defaults are used in production.
111
76
 
112
- The application automatically validates that dev defaults are not used in production:
113
-
114
- ```typescript
115
- // Automatically runs on startup in production
116
- if (NODE_ENV === "production") {
117
- // Checks BETTER_AUTH_SECRET, ADMIN_USER_PASSWORD, STRIPE_SECRET_KEY
118
- // Exits with error if using dev defaults
119
- }
120
- ```
77
+ ## Architecture
121
78
 
122
- ## Configuration Architecture
123
-
124
- ### Per-App Config Files
125
-
126
- Each app has its own configuration file that imports shared defaults:
79
+ Defaults are centralized in `@cronicorn/config-defaults` and imported by each app:
127
80
 
128
81
  ```
129
- apps/
130
- api/src/lib/config.ts # API server config
131
- scheduler/src/index.ts # Scheduler worker config
132
- ai-planner/src/index.ts # AI planner config
133
- web/src/config.ts # Web app config
82
+ packages/config-defaults/src/index.ts # Single source of truth
83
+ apps/api/src/lib/config.ts # API imports defaults
84
+ apps/scheduler/src/index.ts # Scheduler imports defaults
85
+ apps/web/src/config.ts # Web imports defaults
134
86
  ```
135
87
 
136
- ### Shared Defaults Package
137
-
138
- ```
139
- packages/
140
- config-defaults/
141
- src/index.ts # Single source of truth
142
- README.md # Usage documentation
143
- ```
144
-
145
- ## Best Practices
146
-
147
- ### Local Development
148
- - ✅ Use defaults (empty .env or .env.minimal)
149
- - ✅ Override only what you need to test
150
- - ✅ Keep .env out of git (already in .gitignore)
151
-
152
- ### Production
153
- - ✅ Set all required variables explicitly
154
- - ✅ Use secure secrets (never dev defaults)
155
- - ✅ Validate with `NODE_ENV=production` locally first
156
- - ✅ Use environment-specific .env files (.env.production, .env.staging)
157
-
158
- ### Team Development
159
- - ✅ Document custom local overrides in team wiki (not in .env)
160
- - ✅ Keep .env.example up to date
161
- - ✅ Use the same default ports to avoid conflicts
162
- - ✅ Update shared defaults in config-defaults package only
163
-
164
88
  ## Troubleshooting
165
89
 
166
- ### "Cannot find module @cronicorn/config-defaults"
167
-
168
- Run `pnpm build:packages` to build the shared config package:
169
-
170
- ```bash
171
- pnpm build:packages
172
- ```
173
-
174
- ### "Environment variable validation failed"
175
-
176
- Check the error message for which variable is invalid:
90
+ **"Cannot find module @cronicorn/config-defaults"**
91
+ → Run `pnpm build:packages`
177
92
 
178
- ```bash
179
- # See current environment
180
- pnpm exec dotenv -e .env -- env | grep -E "(DATABASE_URL|STRIPE|ADMIN|GITHUB)"
181
- ```
93
+ **"Environment variable validation failed"**
94
+ → Check the error message for which variable is invalid
182
95
 
183
- ### "Auth not working in production"
184
-
185
- Ensure you've overridden the dev defaults:
186
-
187
- ```bash
188
- # Never use these in production:
189
- ADMIN_USER_PASSWORD=devpassword # ❌
190
- BETTER_AUTH_SECRET=dev-secret-DO-NOT-USE-IN-PRODUCTION-min32chars # ❌
191
- ```
96
+ **"Auth not working in production"**
97
+ → Ensure you've overridden `BETTER_AUTH_SECRET` and `ADMIN_USER_PASSWORD`
192
98
 
193
99
  ## Related
194
100
 
195
- - **[Quick Start](./quick-start.md)** - Get started with development
196
- - **[Quality Checks](./quality-checks.md)** - Testing and validation
101
+ - **[Quick Start](./quick-start.md)** - Get running with zero config
102
+ - **[Authentication](./authentication.md)** - GitHub OAuth, API keys, programmatic access
197
103
  - **[Workspace Structure](./workspace-structure.md)** - Project organization
package/dist/docs/developers/quick-start.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  id: developer-quick-start
3
3
  title: Developer Quick Start
4
- description: Set up your Cronicorn development environment in 4 steps
4
+ description: Set up your Cronicorn development environment with zero configuration
5
5
  tags:
6
6
  - developer
7
7
  - essential
@@ -14,44 +14,46 @@ mcp:
14
14
 
15
15
  # Developer Quick Start
16
16
 
17
- Get Cronicorn running locally in 4 steps.
17
+ Get Cronicorn running locally with **zero configuration**.
18
18
 
19
19
  ## Prerequisites
20
20
 
21
21
  - Node.js 24+ and pnpm 10+
22
22
  - Docker (for PostgreSQL)
23
23
 
24
- ## Setup
24
+ ## Setup (No .env Required)
25
25
 
26
26
  ```bash
27
27
  # 1. Clone and install
28
28
  git clone https://github.com/weskerllc/cronicorn.git
29
29
  cd cronicorn
30
- pnpm install # Auto-builds packages
30
+ pnpm install
31
31
 
32
- # 2. Configure authentication (optional - use defaults)
33
- cp .env.example .env
34
- # Edit .env and uncomment ADMIN_USER_EMAIL and ADMIN_USER_PASSWORD
35
- # Or leave as-is to use GitHub OAuth (requires setup)
36
-
37
- # 3. Start database
32
+ # 2. Start database
38
33
  pnpm db
39
34
 
40
- # 4. Run migrations
35
+ # 3. Run migrations
41
36
  pnpm db:migrate
42
37
 
38
+ # 4. Seed demo data (OPTIONAL: seeds sample data)
39
+ pnpm db:seed
40
+
43
41
  # 5. Start development
44
42
  pnpm dev
45
43
  ```
46
44
 
47
- **Login**: Open http://localhost:5173
45
+ **That's it!** No `.env` file needed for local development.
46
+
47
+ ## Login
48
48
 
49
- - **Admin User**: Use email/password from your `.env` file
50
- - **GitHub OAuth**: Click "Sign in with GitHub" (if configured)
49
+ Open http://localhost:5173 and login with:
51
50
 
52
- > 💡 **Tip**: For local dev, uncomment the admin user credentials in `.env` for instant login without OAuth setup.
51
+ | Field | Value |
52
+ |-------|-------|
53
+ | Email | `admin@example.com` |
54
+ | Password | `devpassword` |
53
55
 
54
- > ⚠️ You'll see a warning about `OPENAI_API_KEY` - this is normal. AI features are optional.
56
+ > 💡 **For AI Agents**: The app works out of the box with default credentials. No environment variables or configuration required.
55
57
 
56
58
  ## Common Commands
57
59
 
@@ -62,18 +64,24 @@ pnpm dev
62
64
  | `pnpm dev:web` | Web app only |
63
65
  | `pnpm db` | Start PostgreSQL |
64
66
  | `pnpm db:migrate` | Run migrations |
65
- | `pnpm db:reset` | Reset db |
66
- | `pnpm db:generate` | Generate migrations when you make schema changes |
67
- | `pnpm studio` | Database Browser |
67
+ | `pnpm db:seed` | Seed demo data |
68
+ | `pnpm db:reset` | Reset database |
69
+ | `pnpm db:generate` | Generate migrations after schema changes |
70
+ | `pnpm studio` | Database browser |
68
71
  | `pnpm build` | Production build |
69
72
 
70
73
  ## Troubleshooting
71
74
 
72
75
  **Can't login?**
73
- → Check `.env` has either admin user credentials uncommented OR GitHub OAuth configured
76
+ → Run `pnpm db:seed` to create the admin user
74
77
 
75
78
  **Module errors?**
76
79
  → `pnpm build:packages`
77
80
 
78
81
  **Database errors?**
79
82
  → Ensure Docker is running, then `pnpm db`
83
+
84
+ ## Next Steps
85
+
86
+ - **[Environment Configuration](./environment-configuration.md)** - Customize settings or configure for production
87
+ - **[Authentication](./authentication.md)** - Set up GitHub OAuth or API keys