# Super Productivity — MCP Server

Integrates Claude with [Super Productivity](https://super-productivity.com/) using the Model Context Protocol.
This server targets the desktop app's Local REST API on `http://127.0.0.1:3876`.

Only tested on macOS. Contributions and bug reports are welcome!

## Structure

```
src/
├── index.ts          ← entry point, starts the MCP server
├── sp-client.ts      ← wrapper for Super Productivity REST API
├── resources.ts      ← resources readable by Claude (tasks, projects, tags)
├── prompts.ts        ← reusable prompt templates
└── tools/
    ├── tasks.ts      ← CRUD tools for tasks
    └── projects.ts   ← tools for projects and tags
```

## Setup

### 1. Install dependencies
```bash
npm install
```

### 2. Build
```bash
npm run build
# or use watch mode during development:
npm run dev
```

### 3. Enable the API in Super Productivity
In Super Productivity → Settings → Misc → **Enable local REST API**.
The desktop app listens on `127.0.0.1:3876`.

### 4. Register in Claude Desktop
Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
and add the block from `claude_desktop_config.snippet.json`,
replacing `/ABSOLUTE/PATH/` with the real project path:

```json
{
  "mcpServers": {
    "super-productivity": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/super-productivity-mcp/dist/index.js"],
      "env": {
        "SP_API_URL": "http://127.0.0.1:3876"
      }
    }
  }
}
```

Restart Claude Desktop. You should see the 🔧 icon in chat — this means the tools are active.

### 4a. Quick smoke test
Before opening Claude, verify the local API:

```bash
curl http://127.0.0.1:3876/health
curl http://127.0.0.1:3876/tasks
```

### 5. (Optional) Debug with MCP Inspector
```bash
npm run inspect
```
This opens a web interface for manually testing each tool.

## Available Tools

| Tool | Description |
|---|---|
| `health_check` | Checks that the local REST API is up and ready |
| `list_tasks` | Lists tasks with optional filters (`query`, `projectId`, `projectName`, `tagId`, `tagName`, `includeDone`, `source`) |
| `search_tasks` | Searches tasks by title text with the same optional filters |
| `get_task` | Retrieves the details of a single task |
| `get_status` | Returns current status: active task and task counts |
| `get_current_task` | Returns the currently running task |
| `create_task` | Creates a new task; accepts `projectName` and `tagNames` in addition to IDs |
| `update_task` | Updates fields of an existing task; also supports `projectName` and `tagNames` |
| `complete_task` | Marks a task as completed |
| `start_task` | Starts a task as the current task |
| `set_current_task` | Sets or clears the current task |
| `stop_current_task` | Stops the current task |
| `archive_task` | Archives a task |
| `restore_task` | Restores an archived task |
| `delete_task` | Deletes a task |
| `get_projects` | Lists projects |
| `get_tags` | Lists tags |

## Available Resources

| URI | Description |
|---|---|
| `sp://status` | Current status in text format |
| `sp://tasks/active` | Active tasks in text format |
| `sp://tasks/archived` | Archived tasks in text format |
| `sp://task/current` | Current task in JSON |
| `sp://projects` | All projects in JSON |
| `sp://tags` | All tags in JSON |

## Available Prompts

| Name | Description |
|---|---|
| `daily-planning` | Daily planning session |
| `weekly-review` | Weekly review |
| `break-down-task` | Breaks down a complex task into subtasks |

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `SP_API_URL` | `http://127.0.0.1:3876` | Base URL for the Super Productivity API |

## Development

```bash
npm test
```

This runs the TypeScript build and the Node test suite.