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.
Files changed (41) hide show
  1. task_scheduler_mcp-0.1.0/.gitignore +10 -0
  2. task_scheduler_mcp-0.1.0/.python-version +1 -0
  3. task_scheduler_mcp-0.1.0/Makefile +68 -0
  4. task_scheduler_mcp-0.1.0/Makefile.build +52 -0
  5. task_scheduler_mcp-0.1.0/PKG-INFO +382 -0
  6. task_scheduler_mcp-0.1.0/README.md +370 -0
  7. task_scheduler_mcp-0.1.0/__main__.py +16 -0
  8. task_scheduler_mcp-0.1.0/install.sh +26 -0
  9. task_scheduler_mcp-0.1.0/main.py +6 -0
  10. task_scheduler_mcp-0.1.0/mcpb.json +49 -0
  11. task_scheduler_mcp-0.1.0/pyproject.toml +35 -0
  12. task_scheduler_mcp-0.1.0/scheduler_mcp/__init__.py +84 -0
  13. task_scheduler_mcp-0.1.0/scheduler_mcp/__main__.py +16 -0
  14. task_scheduler_mcp-0.1.0/scheduler_mcp/_mcpb.yaml +36 -0
  15. task_scheduler_mcp-0.1.0/scheduler_mcp/cli.py +225 -0
  16. task_scheduler_mcp-0.1.0/scheduler_mcp/executor/__init__.py +12 -0
  17. task_scheduler_mcp-0.1.0/scheduler_mcp/executor/base.py +35 -0
  18. task_scheduler_mcp-0.1.0/scheduler_mcp/executor/mock.py +30 -0
  19. task_scheduler_mcp-0.1.0/scheduler_mcp/executor/process.py +73 -0
  20. task_scheduler_mcp-0.1.0/scheduler_mcp/models/__init__.py +14 -0
  21. task_scheduler_mcp-0.1.0/scheduler_mcp/models/job.py +137 -0
  22. task_scheduler_mcp-0.1.0/scheduler_mcp/models/schedule.py +77 -0
  23. task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/__init__.py +19 -0
  24. task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/calculator.py +195 -0
  25. task_scheduler_mcp-0.1.0/scheduler_mcp/scheduler/parser.py +92 -0
  26. task_scheduler_mcp-0.1.0/scheduler_mcp/server.py +178 -0
  27. task_scheduler_mcp-0.1.0/scheduler_mcp/services/__init__.py +48 -0
  28. task_scheduler_mcp-0.1.0/scheduler_mcp/services/job_service.py +239 -0
  29. task_scheduler_mcp-0.1.0/scheduler_mcp/services/launchagent.py +195 -0
  30. task_scheduler_mcp-0.1.0/scheduler_mcp/services/service_manager.py +40 -0
  31. task_scheduler_mcp-0.1.0/scheduler_mcp/services/systemd.py +170 -0
  32. task_scheduler_mcp-0.1.0/scheduler_mcp/services/windows.py +223 -0
  33. task_scheduler_mcp-0.1.0/scheduler_mcp/storage/__init__.py +12 -0
  34. task_scheduler_mcp-0.1.0/scheduler_mcp/storage/base.py +37 -0
  35. task_scheduler_mcp-0.1.0/scheduler_mcp/storage/file.py +111 -0
  36. task_scheduler_mcp-0.1.0/scheduler_mcp/storage/memory.py +49 -0
  37. task_scheduler_mcp-0.1.0/scripts/install_linux.sh +52 -0
  38. task_scheduler_mcp-0.1.0/scripts/install_mac.sh +133 -0
  39. task_scheduler_mcp-0.1.0/scripts/install_windows.ps1 +58 -0
  40. task_scheduler_mcp-0.1.0/tests/test_scheduler.py +355 -0
  41. task_scheduler_mcp-0.1.0/uv.lock +1564 -0
@@ -0,0 +1,10 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+
9
+ # Virtual environments
10
+ .venv
@@ -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
+ ```