prompt-scheduler-mcp/README.md

MCP server for managing Augment Prompt Scheduler tasks with local workspace storage and real-time countdown features

# Prompt Scheduler MCP Server

A Model Context Protocol (MCP) server that allows AI agents to directly create and manage tasks in the Augment Prompt Scheduler.

## Features

- **🏠 Workspace Isolation**: Tasks are isolated per VS Code workspace - no cross-workspace interference
- **Create Tasks**: AI agents can create scheduled prompts with custom timing and execution rules
- **Manage Tasks**: List, update, delete, and execute tasks programmatically
- **Individual Idle Thresholds**: Each task can have its own idle detection timing (1-60 minutes)
- **Execution Modes**: Support for once, limited, and infinite execution modes
- **Priority System**: High, medium, and low priority task management
- **Status Monitoring**: Get real-time scheduler status and task information
- **⏱️ Real-time Countdown**: Live countdown timers with smart reset on status changes

## Installation

```bash
npm install -g prompt-scheduler-mcp
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "prompt-scheduler": {
      "command": "prompt-scheduler-mcp"
    }
  }
}
```

### With Other MCP Clients

Run the server directly:

```bash
prompt-scheduler-mcp
```

## Available Tools

### `create_task`
Create a new scheduled task for the Augment Prompt Scheduler.

**Parameters:**
- `title` (required): Title of the task
- `prompt` (required): The prompt to send to Augment
- `priority` (optional): Task priority (low, medium, high) - default: medium
- `tags` (optional): Array of tags for categorization - default: []
- `executionMode` (optional): How many times to execute (once, limited, infinite) - default: infinite
- `maxExecutions` (optional): Maximum executions for limited mode - default: -1
- `idleThresholdMinutes` (optional): Minutes to wait when idle before execution - default: 5
- `isActive` (optional): Whether the task is active - default: true

**Example:**
```json
{
  "title": "Code Review Reminder",
  "prompt": "Please review the latest code changes and provide feedback",
  "priority": "high",
  "executionMode": "once",
  "idleThresholdMinutes": 10,
  "tags": ["code-review", "development"]
}
```

### `list_tasks`
List all scheduled tasks with optional filtering.

**Parameters:**
- `activeOnly` (optional): Only return active tasks - default: false
- `priority` (optional): Filter by priority (low, medium, high)

### `get_task`
Get details of a specific task.

**Parameters:**
- `id` (required): Task ID

### `update_task`
Update an existing scheduled task.

**Parameters:**
- `id` (required): Task ID to update
- All other parameters from `create_task` are optional

### `delete_task`
Delete a scheduled task.

**Parameters:**
- `id` (required): Task ID to delete

### `execute_task`
Manually execute a specific task immediately.

**Parameters:**
- `id` (required): Task ID to execute

### `get_scheduler_status`
Get the current status of the prompt scheduler.

**Returns:**
- `totalTasks`: Total number of tasks
- `activeTasks`: Number of active tasks
- `completedTasks`: Number of completed tasks
- `lastActivity`: Timestamp of last activity
- `isRunning`: Whether the scheduler is running

### `set_workspace`
Set the workspace for task isolation (matches VS Code workspace).

**Parameters:**
- `workspaceId` (required): Workspace identifier (usually the workspace folder path)

### `get_workspace_info`
Get current workspace information and storage paths.

**Returns:**
- `workspaceId`: Current workspace identifier
- `hash`: Workspace hash used for storage
- `tasksFile`: Path to the workspace-specific tasks file

## Integration with VS Code Extension

This MCP server works seamlessly with the Augment Prompt Scheduler VS Code extension with **complete workspace isolation**. Tasks created through the MCP server will appear in the VS Code extension's interface and vice versa, but only within the same workspace.

### 🏠 Workspace Isolation
- **Workspace-specific storage**: `~/.augment-prompt-scheduler/tasks_{hash}.json`
- **Automatic detection**: MCP server detects the correct workspace automatically
- **Hash-based isolation**: Uses MD5 hash of workspace path for unique storage
- **No interference**: Tasks in `/project-a` won't affect `/project-b`

### 🔄 Real-time Synchronization
- **Live countdown timers** update every second
- **Smart reset** when Augment status changes from idle to working
- **Responsive monitoring** checks status every 5 seconds
- **Instant updates** between MCP server and VS Code extension

## Example AI Agent Usage

```
AI Agent: "Create a task to remind me to review documentation every 2 hours"

MCP Call:
{
  "tool": "create_task",
  "arguments": {
    "title": "Documentation Review",
    "prompt": "Please review and update the project documentation",
    "priority": "medium",
    "executionMode": "infinite",
    "idleThresholdMinutes": 120,
    "tags": ["documentation", "maintenance"]
  }
}
```

## Development

```bash
# Clone the repository
git clone https://github.com/augment-community/prompt-scheduler-mcp.git
cd prompt-scheduler-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.