# Task Scheduler MCP Server

A cross-platform stdio MCP server that provides AI agents a controlled interface to OS-native task schedulers. Supports Windows (Task Scheduler), Linux (crontab), and macOS (launchd).

## Supported Platforms

| Platform | Scheduler | Trigger Support |
|----------|-----------|-----------------|
| Windows | Task Scheduler | `once`, `daily`, `weekly`, `on_logon`, `on_event` |
| Linux | crontab | `once`, `daily`, `weekly`, `on_logon` |
| macOS | launchd | `once`, `daily`, `weekly`, `on_logon` |

**Note:** `on_event` trigger is Windows-only. On Linux/macOS, use file watching or polling instead.

## Architecture

The server uses a platform abstraction layer with independent implementations per OS:

```
src/
├── index.ts                    # MCP server (OS-agnostic)
├── types.ts                    # Shared type definitions
├── xml-builder.ts              # Windows XML generation
└── platform/
    ├── interface.ts            # PlatformScheduler interface
    ├── factory.ts              # OS detection + factory
    ├── paths.ts                # Centralized path management
    ├── logger.ts               # Shared JSON-lines logger
    ├── lock.ts                 # File locking utilities
    ├── triggers.ts             # Trigger normalization
    ├── windows/
    │   ├── scheduler.ts        # Windows Task Scheduler
    │   └── credentials.ts      # Windows Credential Manager
    ├── linux/
    │   └── scheduler.ts        # crontab implementation
    └── macos/
        └── scheduler.ts        # launchd implementation
```

## Directory Structure

All data is stored in `~/.agentic_tasks/` (or `~\.agentic_tasks\` on Windows):

```
~/.agentic_tasks/
├── tasks/                      # Task definitions (JSON files)
├── logs/                       # JSON-lines logs
│   ├── agentic_tasks.log       # Full log
│   └── {task_name}.log         # Per-task logs
├── config/                     # Configuration
│   └── credentials.json        # Credentials (Linux/macOS)
└── dist/                       # Compiled TypeScript
```

## Prerequisites

### All Platforms
- Node.js 18+

### Windows
- PowerShell 5.1+
- Administrator privileges (for setup)

### Linux
- `crontab` command
- `at` command (for `once` trigger)

### macOS
- `launchctl` command (standard on macOS)

## Setup

### Windows

Run the setup script as Administrator:

```powershell
powershell -ExecutionPolicy Bypass -File setup.ps1
```

The setup script will:
1. Create the `agentic_worker` local user
2. Enable WinRM for PowerShell remoting
3. Create the `\agentic_tasks` Task Scheduler folder
4. Set folder permissions
5. Store credentials in Windows Credential Manager
6. Build the MCP server

### Linux

```bash
chmod +x setup-linux.sh
./setup-linux.sh
```

### macOS

```bash
chmod +x setup-macos.sh
./setup-macos.sh
```

## MCP Server Configuration

Add this to your `opencode.json`:

### Windows
```json
{
  "mcpServers": {
    "task-scheduler": {
      "command": "node",
      "args": ["C:\\Users\\<username>\\.agentic_tasks\\dist\\index.js"]
    }
  }
}
```

### Linux/macOS
```json
{
  "mcpServers": {
    "task-scheduler": {
      "command": "node",
      "args": ["/home/<username>/.agentic_tasks/dist/index.js"]
    }
  }
}
```

## Available Tools

### create_task

Create a new scheduled task.

**Parameters:**
- `name` (required): Task name (no path separators or invalid characters)
- `description` (optional): Task description
- `command` (required): Command to execute
- `arguments` (optional): Command arguments
- `working_directory` (optional): Working directory for the command
- `triggers` (required): Array of trigger definitions (see below)
- `conditions` (optional): Task conditions (`idle`, `ac_power`)
- `settings` (optional): Task settings
- `enabled` (optional): Whether the task is enabled (default: true)

**Trigger Types:**

```json
{ "type": "once", "datetime": "2024-12-25T10:00:00" }
{ "type": "daily", "time": "09:00", "interval_days": 1 }
{ "type": "weekly", "time": "09:00", "days_of_week": ["monday", "wednesday", "friday"], "interval_weeks": 1 }
{ "type": "on_logon" }
{ "type": "on_event", "channel": "Application", "id": 1000 }
```

**Example:**

```json
{
  "name": "daily_backup",
  "description": "Daily backup task",
  "command": "powershell.exe",
  "arguments": "-File C:\\Scripts\\backup.ps1",
  "triggers": [
    { "type": "daily", "time": "02:00" }
  ]
}
```

### delete_task

Delete a scheduled task.

**Parameters:**
- `name` (required): Task name

### update_task

Update an existing scheduled task.

**Parameters:**
- `name` (required): Task name
- All other parameters from `create_task` are optional (only specified fields are updated)

### list_tasks

List all scheduled tasks.

**Parameters:** None

### get_task

Get detailed information about a specific scheduled task.

**Parameters:**
- `name` (required): Task name

### get_task_log

Get execution log for a specific task.

**Parameters:**
- `name` (required): Task name
- `max_events` (optional): Maximum number of events to return (default: 50)
- `level` (optional): Filter by event level: `"information"`, `"warning"`, or `"error"`

### get_full_log

Get execution log for all tasks.

**Parameters:**
- `max_events` (optional): Maximum number of events to return (default: 100)
- `level` (optional): Filter by event level: `"information"`, `"warning"`, or `"error"`

## Testing

The project includes three types of tests:

### 1. Unit Tests (Vitest)

Test individual functions in isolation:

```bash
npm test                    # Run all unit tests
npm run test:watch          # Run tests in watch mode
npm run test:coverage       # Run tests with coverage report
```

Unit tests cover:
- Trigger conversion (cron, plist, Windows XML)
- Path resolution
- Logger operations
- File locking
- XML builder

### 2. Integration Tests

Test the full MCP server workflow via stdio JSON-RPC:

#### Windows
```powershell
powershell -ExecutionPolicy Bypass -File test_scripts\run_all_tests.ps1
```

#### Linux/macOS
```bash
./test_scripts/run_tests.sh
```

Integration tests cover:
- Task creation, update, deletion
- Task listing and retrieval
- Log retrieval
- Error handling

### 3. Manual Testing with MCP Inspector

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an official debugging tool for MCP servers. It provides a web UI for manually testing tools.

#### Running MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

This opens a web interface at `http://localhost:5173` where you can:

1. **View Available Tools**: See all 7 tools with their schemas
2. **Test Tools Manually**: Invoke tools with custom parameters
3. **Inspect Requests/Responses**: View the full JSON-RPC payloads
4. **Debug Issues**: See error messages and stack traces

#### Example: Testing create_task

1. Open the MCP Inspector web UI
2. Click on "Tools" tab
3. Select "create_task" from the dropdown
4. Enter parameters:
   ```json
   {
     "name": "test_manual",
     "command": "cmd.exe",
     "arguments": "/c echo manual test",
     "triggers": [
       { "type": "once", "datetime": "2099-01-01T00:00:00" }
     ]
   }
   ```
5. Click "Run Tool"
6. View the response in the right panel

#### Example: Testing list_tasks

1. Select "list_tasks" from the dropdown
2. Leave parameters empty (no parameters required)
3. Click "Run Tool"
4. View the list of tasks in the response

#### Troubleshooting with MCP Inspector

If a tool fails:
- Check the "Error" tab for detailed error messages
- Verify the request payload matches the tool schema
- Check server logs in the terminal where you ran the inspector
- Use the "Resources" tab to inspect server state

### Running All Tests

To run the complete test suite (unit + integration + error handling):

```bash
# Windows
powershell -ExecutionPolicy Bypass -File test_scripts\run_all_tests.ps1

# Linux/macOS
./test_scripts/run_tests.sh
```

## License

MIT