task-scheduler-mcp 0.1.0__tar.gz
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.
- task_scheduler_mcp-0.1.0/.gitignore +10 -0
- task_scheduler_mcp-0.1.0/.python-version +1 -0
- task_scheduler_mcp-0.1.0/Makefile +68 -0
- task_scheduler_mcp-0.1.0/Makefile.build +52 -0
- task_scheduler_mcp-0.1.0/PKG-INFO +382 -0
- task_scheduler_mcp-0.1.0/README.md +370 -0
- task_scheduler_mcp-0.1.0/__main__.py +16 -0
- task_scheduler_mcp-0.1.0/install.sh +26 -0
- task_scheduler_mcp-0.1.0/main.py +6 -0
- task_scheduler_mcp-0.1.0/mcpb.json +49 -0
- task_scheduler_mcp-0.1.0/pyproject.toml +35 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/__init__.py +84 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/__main__.py +16 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/_mcpb.yaml +36 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/cli.py +225 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/executor/__init__.py +12 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/executor/base.py +35 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/executor/mock.py +30 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/executor/process.py +73 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/models/__init__.py +14 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/models/job.py +137 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/models/schedule.py +77 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/__init__.py +19 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/calculator.py +195 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/parser.py +92 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/server.py +178 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/__init__.py +48 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/job_service.py +239 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/launchagent.py +195 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/service_manager.py +40 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/systemd.py +170 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/services/windows.py +223 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/storage/__init__.py +12 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/storage/base.py +37 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/storage/file.py +111 -0
- task_scheduler_mcp-0.1.0/scheduler_mcp/storage/memory.py +49 -0
- task_scheduler_mcp-0.1.0/scripts/install_linux.sh +52 -0
- task_scheduler_mcp-0.1.0/scripts/install_mac.sh +133 -0
- task_scheduler_mcp-0.1.0/scripts/install_windows.ps1 +58 -0
- task_scheduler_mcp-0.1.0/tests/test_scheduler.py +355 -0
- task_scheduler_mcp-0.1.0/uv.lock +1564 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.13
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Scheduler MCP Makefile
|
|
2
|
+
# Cross-platform build and development targets
|
|
3
|
+
|
|
4
|
+
.PHONY: help install linux mac windows clean check test
|
|
5
|
+
|
|
6
|
+
SHELL := /bin/bash
|
|
7
|
+
|
|
8
|
+
help:
|
|
9
|
+
@echo "Scheduler MCP - Build Targets"
|
|
10
|
+
@echo ""
|
|
11
|
+
@echo "Usage:"
|
|
12
|
+
@echo " make install Install dependencies (platform-specific)"
|
|
13
|
+
@echo " make build Build for current platform"
|
|
14
|
+
@echo " make build-linux Build for Linux"
|
|
15
|
+
@echo " make build-mac Build for macOS"
|
|
16
|
+
@echo " make build-win Build for Windows"
|
|
17
|
+
@echo " make clean Remove build artifacts"
|
|
18
|
+
@echo " make check Run checks (lint, type checking)"
|
|
19
|
+
@echo ""
|
|
20
|
+
|
|
21
|
+
install:
|
|
22
|
+
ifeq ($(PLATFORM),darwin)
|
|
23
|
+
@bash scripts/install_mac.sh
|
|
24
|
+
else ifeq ($(PLATFORM),linux)
|
|
25
|
+
@bash scripts/install_linux.sh
|
|
26
|
+
else
|
|
27
|
+
@pwsh scripts/install_windows.ps1
|
|
28
|
+
endif
|
|
29
|
+
|
|
30
|
+
build:
|
|
31
|
+
@$(MAKE) build-mac
|
|
32
|
+
|
|
33
|
+
build-linux:
|
|
34
|
+
@$(MAKE) -f Makefile.build install PLATFORM=linux ARCH=$(if $(BUILD_LINUX_ARCH),$(BUILD_LINUX_ARCH),x64)
|
|
35
|
+
|
|
36
|
+
build-mac:
|
|
37
|
+
@$(MAKE) -f Makefile.build install PLATFORM=darwin ARCH=$(if $(BUILD_MAC_ARCH),$(BUILD_MAC_ARCH),arm64)
|
|
38
|
+
|
|
39
|
+
build-win:
|
|
40
|
+
@$(MAKE) -f Makefile.build install PLATFORM=windows ARCH=$(if $(BUILD_WIN_ARCH),$(BUILD_WIN_ARCH),x64)
|
|
41
|
+
|
|
42
|
+
# Python detection
|
|
43
|
+
PYTHON ?= $(shell if [ -f "./.venv/bin/python" ]; then echo "./.venv/bin/python"; elif which python3 >/dev/null 2>&1; then echo "python3"; else echo "python"; fi)
|
|
44
|
+
|
|
45
|
+
clean:
|
|
46
|
+
@rm -rf dist/ build/ *.egg-info
|
|
47
|
+
@echo "✓ Cleaned build artifacts"
|
|
48
|
+
|
|
49
|
+
check:
|
|
50
|
+
@echo "Running checks..."
|
|
51
|
+
@$(PYTHON) -m mypy scheduler_mcp/ --ignore-missing-imports 2>/dev/null || echo "mypy not installed (optional)"
|
|
52
|
+
@$(PYTHON) -m pyright --version 2>/dev/null || echo "pyright not installed (optional)"
|
|
53
|
+
|
|
54
|
+
test:
|
|
55
|
+
@echo "Running tests..."
|
|
56
|
+
@$(PYTHON) -m unittest discover tests -v
|
|
57
|
+
|
|
58
|
+
# Platform detection
|
|
59
|
+
PLATFORM := $(shell uname -s | tr '[:upper:]' '[:lower:]')
|
|
60
|
+
ARCH := $(shell uname -m)
|
|
61
|
+
|
|
62
|
+
ifeq ($(PLATFORM),linux)
|
|
63
|
+
LINUX_ARCH ?= x64
|
|
64
|
+
else ifeq ($(PLATFORM),darwin)
|
|
65
|
+
MAC_ARCH ?= arm64
|
|
66
|
+
else ifeq ($(PLATFORM),windows)
|
|
67
|
+
WIN_ARCH ?= x64
|
|
68
|
+
endif
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# Build configuration for all platforms
|
|
2
|
+
# Include this in each platform-specific Makefile
|
|
3
|
+
|
|
4
|
+
.PHONY: help build install check cross
|
|
5
|
+
|
|
6
|
+
SHELL := /bin/bash
|
|
7
|
+
|
|
8
|
+
help:
|
|
9
|
+
@echo "Scheduler MCP - Build Targets"
|
|
10
|
+
@echo ""
|
|
11
|
+
@echo "Usage:"
|
|
12
|
+
@echo " make build Build for current platform (detects OS automatically)"
|
|
13
|
+
@echo " make install Install built package"
|
|
14
|
+
@echo " make check Run linting checks"
|
|
15
|
+
|
|
16
|
+
# Auto-detect platform
|
|
17
|
+
PLATFORM := $(shell uname -s | tr '[:upper:]' '[:lower:]')
|
|
18
|
+
ARCH ?= $(shell uname -m)
|
|
19
|
+
|
|
20
|
+
build:
|
|
21
|
+
ifeq ($(PLATFORM),linux)
|
|
22
|
+
$(MAKE) build-linux ARCH=$(ARCH)
|
|
23
|
+
else ifeq ($(PLATFORM),darwin)
|
|
24
|
+
$(MAKE) build-mac ARCH=$(ARCH)
|
|
25
|
+
else ifeq ($(PLATFORM),windows)
|
|
26
|
+
$(MAKE) build-win ARCH=$(WIN_ARCH)
|
|
27
|
+
endif
|
|
28
|
+
|
|
29
|
+
# Build and install from current platform's Makefile
|
|
30
|
+
build-install: build
|
|
31
|
+
@if [ "$(PLATFORM)" = "linux" ]; then \
|
|
32
|
+
chmod +x scripts/install_linux.sh && ./scripts/install_linux.sh; \
|
|
33
|
+
elif [ "$(PLATFORM)" = "darwin" ]; then \
|
|
34
|
+
chmod +x scripts/install_mac.sh && ./scripts/install_mac.sh; \
|
|
35
|
+
else \
|
|
36
|
+
pwsh scripts/install_windows.ps1; \
|
|
37
|
+
fi
|
|
38
|
+
|
|
39
|
+
install:
|
|
40
|
+
@echo "Installing..."
|
|
41
|
+
ifeq ($(PLATFORM),linux)
|
|
42
|
+
@chmod +x scripts/install_linux.sh && bash scripts/install_linux.sh
|
|
43
|
+
else ifeq ($(PLATFORM),darwin)
|
|
44
|
+
@chmod +x scripts/install_mac.sh && bash scripts/install_mac.sh
|
|
45
|
+
else ifeq ($(PLATFORM),windows)
|
|
46
|
+
pwsh scripts/install_windows.ps1
|
|
47
|
+
endif
|
|
48
|
+
|
|
49
|
+
check:
|
|
50
|
+
@echo "Running lint checks..."
|
|
51
|
+
@$(PYTHON) -m mypy scheduler_mcp/ --ignore-missing-imports 2>/dev/null || echo "mypy not installed (optional)"
|
|
52
|
+
@echo "Check complete."
|
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: task-scheduler-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A cross-platform job scheduler MCP server for Linux, Mac and Windows
|
|
5
|
+
Requires-Python: >=3.13
|
|
6
|
+
Requires-Dist: fastmcp>=4.2.4
|
|
7
|
+
Provides-Extra: dev
|
|
8
|
+
Requires-Dist: mypy>=1.0.0; extra == 'dev'
|
|
9
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
10
|
+
Requires-Dist: ruff>=0.1.0; extra == 'dev'
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
|
|
13
|
+
# Task Scheduler MCP Server (`task-scheduler-mcp`)
|
|
14
|
+
|
|
15
|
+
A cross-platform job and task scheduler MCP (Model Context Protocol) server for creating, managing, and executing scheduled tasks locally. Supports macOS, Linux, and Windows with local persistent storage, autonomous background scheduling, and cross-platform login service (systemd on Linux, LaunchAgent on macOS, Task Scheduler on Windows).
|
|
16
|
+
|
|
17
|
+
PyPI: `task-scheduler-mcp` | Repository: [https://github.com/SankalpPimpalkar/scheduler-mcp](https://github.com/SankalpPimpalkar/scheduler-mcp)
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Quick Start: One-Command Installation
|
|
22
|
+
|
|
23
|
+
After cloning the repository, install and configure everything with a single command:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
git clone https://github.com/SankalpPimpalkar/scheduler-mcp.git
|
|
27
|
+
cd scheduler-mcp
|
|
28
|
+
./install.sh
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
*(Alternatively, you can run `make install`)*
|
|
32
|
+
|
|
33
|
+
### What the Installer Does Automatically:
|
|
34
|
+
|
|
35
|
+
1. **Virtual Environment**: Provisions an isolated environment with dependencies using `uv` (or falls back to `python3 -m venv`).
|
|
36
|
+
2. **CLI Executable Wrapper**: Generates and links the `scheduler-mcp` binary into `~/.local/bin` and `~/Library/Application Support/scheduler/bin`.
|
|
37
|
+
3. **Login Auto-Start (macOS)**: Registers `com.scheduler.mcp.plist` in `~/Library/LaunchAgents/` with `RunAtLoad` and `KeepAlive` enabled. The scheduler daemon starts immediately and stays active across all login sessions.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 🔌 Connecting to MCP Clients
|
|
42
|
+
|
|
43
|
+
`scheduler-mcp` connects to any Model Context Protocol compliant client using the standard `stdio` transport.
|
|
44
|
+
|
|
45
|
+
> [!TIP]
|
|
46
|
+
> **Recommended Cross-Platform Configuration (`uvx`):**
|
|
47
|
+
> Just like `npx` for Node.js, `uvx` runs on macOS, Linux, and Windows without requiring virtual environment activation or hardcoded paths:
|
|
48
|
+
> ```json
|
|
49
|
+
> {
|
|
50
|
+
> "mcpServers": {
|
|
51
|
+
> "scheduler": {
|
|
52
|
+
> "command": "uvx",
|
|
53
|
+
> "args": ["task-scheduler-mcp", "start"]
|
|
54
|
+
> }
|
|
55
|
+
> }
|
|
56
|
+
> }
|
|
57
|
+
> ```
|
|
58
|
+
> *(Or during local development before publishing: `"args": ["--from", "/path/to/project", "task-scheduler-mcp", "start"]`)*
|
|
59
|
+
>
|
|
60
|
+
> **Other options:**
|
|
61
|
+
> - **Virtualenv binary**: `"/path/to/scheduler-mcp/.venv/bin/scheduler-mcp"`
|
|
62
|
+
> - **Global install**: `"command": "scheduler-mcp"` (if installed in system PATH)
|
|
63
|
+
|
|
64
|
+
### 1. Claude Desktop
|
|
65
|
+
|
|
66
|
+
Add the server to your Claude configuration file:
|
|
67
|
+
|
|
68
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
69
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
70
|
+
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"scheduler": {
|
|
76
|
+
"command": "scheduler-mcp",
|
|
77
|
+
"args": ["start"]
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
### 2. Cursor
|
|
84
|
+
|
|
85
|
+
Add to your project's `.cursor/mcp.json` or through **Cursor Settings > Features > MCP**:
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"scheduler": {
|
|
91
|
+
"command": "scheduler-mcp",
|
|
92
|
+
"args": ["start"]
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 3. Claude Code CLI
|
|
99
|
+
|
|
100
|
+
Add the server directly from the command line:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
claude mcp add scheduler scheduler-mcp start
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 4. Windsurf
|
|
107
|
+
|
|
108
|
+
Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"mcpServers": {
|
|
113
|
+
"scheduler": {
|
|
114
|
+
"command": "scheduler-mcp",
|
|
115
|
+
"args": ["start"]
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### 5. Zed Editor
|
|
122
|
+
|
|
123
|
+
Add to `settings.json`:
|
|
124
|
+
|
|
125
|
+
```json
|
|
126
|
+
{
|
|
127
|
+
"context_servers": {
|
|
128
|
+
"scheduler": {
|
|
129
|
+
"command": {
|
|
130
|
+
"path": "scheduler-mcp",
|
|
131
|
+
"args": ["start"]
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
### 6. Cline / Roo Code (VS Code Extension)
|
|
139
|
+
|
|
140
|
+
Add to your extension's MCP configuration (`cline_mcp_settings.json`):
|
|
141
|
+
|
|
142
|
+
```json
|
|
143
|
+
{
|
|
144
|
+
"mcpServers": {
|
|
145
|
+
"scheduler": {
|
|
146
|
+
"command": "scheduler-mcp",
|
|
147
|
+
"args": ["start"]
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## MCP Tools & Resources
|
|
156
|
+
|
|
157
|
+
### Available Tools
|
|
158
|
+
|
|
159
|
+
| Tool | Parameters | Description |
|
|
160
|
+
| -------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
161
|
+
| `create_job` | `task: str`, `schedule: Optional[str]`, `enabled: bool` | Create a new scheduled task. |
|
|
162
|
+
| `list_jobs` | `filter_status: Optional[str]`, `enabled_only: bool` | List jobs with optional filtering. |
|
|
163
|
+
| `get_job` | `job_id: str` | Retrieve details for a specific job. |
|
|
164
|
+
| `update_job` | `job_id: str`, `task: Optional[str]`, `schedule: Optional[str]`, `enabled: Optional[bool]` | Update an existing job's parameters. |
|
|
165
|
+
| `delete_job` | `job_id: str` | Delete a job permanently. |
|
|
166
|
+
| `run_job` | `job_id: str`, `force: bool` | Execute a job immediately and capture output/exit codes. |
|
|
167
|
+
| `pause_job` | `job_id: str` | Temporarily pause an active job. |
|
|
168
|
+
| `resume_job` | `job_id: str` | Re-enable a paused job. |
|
|
169
|
+
|
|
170
|
+
### Available Resources
|
|
171
|
+
|
|
172
|
+
- `scheduler://status/jobs`: Returns live counts of total, active, and paused jobs.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## CLI Usage
|
|
177
|
+
|
|
178
|
+
`scheduler-mcp` can also be operated directly from the terminal:
|
|
179
|
+
|
|
180
|
+
### Interactive MCP Web UI (Inspector)
|
|
181
|
+
|
|
182
|
+
You can explore and interactively test all tools and resources in your browser using the MCP Inspector Web UI:
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
# Option 1: Directly using the scheduler-mcp CLI
|
|
186
|
+
scheduler-mcp ui
|
|
187
|
+
|
|
188
|
+
# Option 2: Using FastMCP's built-in dev inspector
|
|
189
|
+
fastmcp dev inspector scheduler_mcp/server.py:mcp
|
|
190
|
+
|
|
191
|
+
# Option 3: Using npx directly
|
|
192
|
+
npx @modelcontextprotocol/inspector scheduler-mcp start
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Managing Jobs
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
# Create a scheduled task (supports natural language intervals and cron expressions)
|
|
199
|
+
scheduler-mcp create "echo 'Hello World'" --schedule "every 1 hour"
|
|
200
|
+
scheduler-mcp create "python /path/to/backup.py" --schedule "0 2 * * *"
|
|
201
|
+
scheduler-mcp create "curl -s https://api.example.com/heartbeat" --schedule "every 30 minutes"
|
|
202
|
+
scheduler-mcp create "npm run sync" --schedule "15m"
|
|
203
|
+
|
|
204
|
+
# List jobs
|
|
205
|
+
scheduler-mcp list
|
|
206
|
+
scheduler-mcp list --status pending
|
|
207
|
+
scheduler-mcp list --enabled-only
|
|
208
|
+
|
|
209
|
+
# Check scheduler summary
|
|
210
|
+
scheduler-mcp status
|
|
211
|
+
|
|
212
|
+
# Manually trigger a job immediately
|
|
213
|
+
scheduler-mcp run <job_id>
|
|
214
|
+
|
|
215
|
+
# Delete a job
|
|
216
|
+
scheduler-mcp delete <job_id>
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Schedule Syntax & Natural Language Rules
|
|
220
|
+
|
|
221
|
+
The `--schedule` option in CLI and the `schedule` parameter in MCP tools accept flexible schedule expressions:
|
|
222
|
+
|
|
223
|
+
#### 1. Natural Language Intervals
|
|
224
|
+
|
|
225
|
+
Format: `[every|each] [<amount>] <unit>` or shorthand `<amount><unit>`
|
|
226
|
+
|
|
227
|
+
| Format / Pattern | Examples | Interval Seconds | Description |
|
|
228
|
+
| :--- | :--- | :--- | :--- |
|
|
229
|
+
| **Full words (`every` / `each`)** | `every 30 seconds`, `each 10 secs` | 30s, 10s | Runs recurringly every N seconds |
|
|
230
|
+
| **Minutes** | `every 5 minutes`, `every min`, `each 15 mins` | 300s, 60s, 900s | Runs every N minutes |
|
|
231
|
+
| **Hours** | `every hour`, `each 2 hours`, `every 6 hrs` | 3600s, 7200s, 21600s | Runs every N hours (amount defaults to 1 if omitted) |
|
|
232
|
+
| **Days** | `every day`, `each 3 days` | 86400s, 259200s | Runs every N days |
|
|
233
|
+
| **Weeks** | `every week`, `each 2 weeks` | 604800s, 1209600s | Runs every N weeks |
|
|
234
|
+
| **Short notation** | `10s`, `5m`, `2h`, `1d`, `1w` | 10s, 300s, 7200s, 86400s, 604800s | Compact unit notation (`s` = seconds, `m` = minutes, `h` = hours, `d` = days, `w` = weeks) |
|
|
235
|
+
| **Keywords** | `hourly`, `daily`, `weekly` | 3600s, 86400s, 604800s | Common recurrence shorthand words |
|
|
236
|
+
|
|
237
|
+
> **Interval Rules:**
|
|
238
|
+
> - The prefix `every` or `each` is optional (e.g. `30 minutes` and `every 30 minutes` both work).
|
|
239
|
+
> - If amount is omitted (e.g. `every hour`, `every day`), it defaults to `1`.
|
|
240
|
+
> - Units are case-insensitive and support singular, plural, and abbreviations (`sec`/`secs`/`second`/`seconds`, `min`/`mins`/`minute`/`minutes`, `hr`/`hrs`/`hour`/`hours`, `day`/`days`, `week`/`weeks`).
|
|
241
|
+
|
|
242
|
+
#### 2. Standard 5-Field Cron Syntax
|
|
243
|
+
|
|
244
|
+
Format: `minute hour day month weekday`
|
|
245
|
+
|
|
246
|
+
| Field | Allowed Values | Allowed Special Characters |
|
|
247
|
+
| :--- | :--- | :--- |
|
|
248
|
+
| **Minute** | `0-59` | `*` `,` `-` `/` |
|
|
249
|
+
| **Hour** | `0-23` | `*` `,` `-` `/` |
|
|
250
|
+
| **Day of Month** | `1-31` | `*` `,` `-` `/` |
|
|
251
|
+
| **Month** | `1-12` | `*` `,` `-` `/` |
|
|
252
|
+
| **Day of Week** | `0-6` (0 = Sunday, 1 = Monday ... 6 = Saturday) | `*` `,` `-` `/` |
|
|
253
|
+
|
|
254
|
+
**Cron Examples:**
|
|
255
|
+
- `"0 9 * * *"`: Run daily at 09:00 UTC
|
|
256
|
+
- `"*/15 * * * *"`: Run every 15 minutes
|
|
257
|
+
- `"0 0 * * 0"`: Run every Sunday at midnight
|
|
258
|
+
- `"0 2 1 * *"`: Run on the 1st of every month at 02:00 UTC
|
|
259
|
+
- `"30 8 * * 1-5"`: Run Monday through Friday at 08:30 UTC
|
|
260
|
+
|
|
261
|
+
#### 3. Immediate / One-off Execution
|
|
262
|
+
|
|
263
|
+
- Omitting `--schedule` or passing an empty string (`""`) configures the task for **immediate execution** (runs once when processed, with no subsequent recurring runs).
|
|
264
|
+
|
|
265
|
+
### Running the Background Daemon
|
|
266
|
+
|
|
267
|
+
The daemon runs continuously, checking for due tasks and executing them:
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
scheduler-mcp daemon --interval 1.0
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Alternatively, to run it as a detached background process in Linux:
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
nohup scheduler-mcp daemon --interval 1.0 > ~/.scheduler/logs/daemon.log 2>&1 &
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### Managing the Background Login Service (macOS, Linux & Windows)
|
|
280
|
+
|
|
281
|
+
`scheduler-mcp service` automatically configures cross-platform auto-start on login:
|
|
282
|
+
- **macOS**: Configures a launchd LaunchAgent (`~/Library/LaunchAgents/com.scheduler.mcp.plist`)
|
|
283
|
+
- **Linux**: Configures a systemd user service (`~/.config/systemd/user/scheduler-mcp.service`)
|
|
284
|
+
- **Windows**: Configures a Windows Task Scheduler task (`SchedulerMCP` via `schtasks`)
|
|
285
|
+
|
|
286
|
+
```bash
|
|
287
|
+
# Check service status (running PID, log paths, installation status)
|
|
288
|
+
scheduler-mcp service status
|
|
289
|
+
|
|
290
|
+
# Install and enable the background service to start automatically on login
|
|
291
|
+
scheduler-mcp service install
|
|
292
|
+
|
|
293
|
+
# Start / stop the background service
|
|
294
|
+
scheduler-mcp service start
|
|
295
|
+
scheduler-mcp service stop
|
|
296
|
+
|
|
297
|
+
# Uninstall the service
|
|
298
|
+
scheduler-mcp service uninstall
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Service logs are stored at:
|
|
302
|
+
|
|
303
|
+
- **macOS**: `~/Library/Logs/scheduler-mcp.{stdout,stderr}.log`
|
|
304
|
+
- **Linux**: `~/.scheduler/logs/scheduler-mcp.{stdout,stderr}.log`
|
|
305
|
+
- **Windows**: `%USERPROFILE%\.scheduler\logs\scheduler-mcp.{stdout,stderr}.log`
|
|
306
|
+
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
## Architecture
|
|
310
|
+
|
|
311
|
+
The project is structured into clear, decoupled layers:
|
|
312
|
+
|
|
313
|
+
```
|
|
314
|
+
scheduler-mcp/
|
|
315
|
+
├── scheduler_mcp/
|
|
316
|
+
│ ├── models/ # Domain models & entities
|
|
317
|
+
│ │ ├── job.py # Job entity & lifecycle states (pending, running, completed, paused, failed)
|
|
318
|
+
│ │ └── schedule.py # Schedule configuration (cron expressions, intervals, immediate)
|
|
319
|
+
│ ├── scheduler/ # Scheduling engine
|
|
320
|
+
│ │ ├── parser.py # Schedule parser for natural language and cron syntax
|
|
321
|
+
│ │ └── calculator.py # Next run calculation strategies
|
|
322
|
+
│ ├── storage/ # Persistence layer
|
|
323
|
+
│ │ ├── base.py # Abstract repository interface
|
|
324
|
+
│ │ ├── file.py # Atomic JSON filesystem storage
|
|
325
|
+
│ │ └── memory.py # In-memory storage for testing and ephemeral runs
|
|
326
|
+
│ ├── executor/ # Task execution engine
|
|
327
|
+
│ │ ├── base.py # Abstract executor interface and execution results
|
|
328
|
+
│ │ ├── process.py # Asynchronous subprocess shell execution with timeouts
|
|
329
|
+
│ │ └── mock.py # Deterministic mock executor for test suites
|
|
330
|
+
│ ├── services/ # Orchestration & background services
|
|
331
|
+
│ │ ├── job_service.py # Application service coordinating storage, scheduler, and executor
|
|
332
|
+
│ │ └── launchagent.py # macOS LaunchAgent lifecycle manager
|
|
333
|
+
│ ├── server.py # FastMCP server definition & tool/resource bindings
|
|
334
|
+
│ ├── cli.py # Command-line interface
|
|
335
|
+
│ ├── __init__.py # Public package exports
|
|
336
|
+
│ └── __main__.py # Standard entry point (python -m scheduler_mcp)
|
|
337
|
+
├── tests/
|
|
338
|
+
│ └── test_scheduler.py # Unit and integration test suite
|
|
339
|
+
├── scripts/ # Platform installation scripts
|
|
340
|
+
│ ├── install_mac.sh # macOS installer with LaunchAgent configuration
|
|
341
|
+
│ ├── install_linux.sh # Linux installer
|
|
342
|
+
│ └── install_windows.ps1 # Windows installer
|
|
343
|
+
├── install.sh # Root cross-platform one-command installer
|
|
344
|
+
├── Makefile # Build automation
|
|
345
|
+
├── pyproject.toml # Dependencies and package metadata
|
|
346
|
+
└── README.md
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
---
|
|
350
|
+
|
|
351
|
+
## Platform Support & Storage
|
|
352
|
+
|
|
353
|
+
### Supported Operating Systems
|
|
354
|
+
|
|
355
|
+
- **macOS** (Apple Silicon `arm64` & Intel `x86_64`)
|
|
356
|
+
- **Linux** (`x86_64` & `arm64` / `aarch64`)
|
|
357
|
+
- **Windows** (`x64` & `arm64`)
|
|
358
|
+
|
|
359
|
+
### Storage Locations
|
|
360
|
+
|
|
361
|
+
Job definitions and execution logs are stored locally:
|
|
362
|
+
|
|
363
|
+
- **macOS**: `~/Library/Application Support/scheduler/jobs/`
|
|
364
|
+
- **Linux**: `~/.local/share/scheduler/jobs/` (or `$XDG_DATA_HOME/scheduler/jobs/`)
|
|
365
|
+
- **Windows**: `%APPDATA%\scheduler\jobs\`
|
|
366
|
+
- **Fallback**: `./.storage/jobs/`
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Testing
|
|
371
|
+
|
|
372
|
+
Run the test suite:
|
|
373
|
+
|
|
374
|
+
```bash
|
|
375
|
+
make test
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
Or using Python's built-in `unittest`:
|
|
379
|
+
|
|
380
|
+
```bash
|
|
381
|
+
python3 -m unittest discover tests -v
|
|
382
|
+
```
|