# TaskMCP

A personal task management system with a lightweight Web UI and a Model Context Protocol (MCP) server.

## Features

- Local-first SQLite storage.
- MCP server for LLM clients (stdio transport).
- Terminal-inspired Web UI with **React + Tailwind CSS v4**.
- Drag-and-drop task cards across status columns.
- Inline card editing and per-column task creation.
- Projects, tasks, labels, and comments.
- Both LLM and browser write to the same database.

## Architecture

TaskMCP runs as **two independent processes** that share a single SQLite file:

- `npm run mcp` — MCP server on stdio for LLM clients.
- `npm run web` — Hono web server on `http://localhost:3000`.

Both processes open the same `better-sqlite3` database configured with WAL mode and a 5 second busy timeout, so they can run concurrently without blocking each other.

## Installation

```bash
npm install
```

## Scripts

- `npm run build` — Compile TypeScript.
- `npm run typecheck` — Run TypeScript without emitting files.
- `npm run test` — Run Vitest tests.
- `npm run mcp` — Start the MCP server (stdio).
- `npm run web:build` — Build the React client and Tailwind CSS output.
- `npm run web:watch` — Run the web server with automatic client rebuilds on file changes.
- `npm run web:serve` — Start only the Hono API/static server.
- `npm run web` — Build and start the web UI on `http://localhost:3000`.
- `npm run css:build` — Build the Tailwind CSS output.
- `npm run design:lint` — Validate `DESIGN.md`.
- `npm run design:export` — Export design tokens to `src/web/static/theme.css`.
- `npm run lint` — Run ESLint.
- `npm run format` — Format files with Prettier.

## Design System

Visual tokens are defined in `DESIGN.md`. Export them and rebuild CSS with:

```bash
npm run design:export
npm run css:build
```

The front-end is built with React, bundled by esbuild, and styled with Tailwind CSS v4 classes generated from `src/web/client/index.css`.

> Note: The `@google/design.md` v0.3.0 `export` CLI does not emit CSS correctly, so `design:export` runs a small local script (`scripts/generate-theme.js`) that parses `DESIGN.md` and generates the equivalent Tailwind v4 `@theme` block.

## Configuration

Set `TASKMCP_DB_PATH` to override the default SQLite database location (`.data/taskmcp.db`).

## API Endpoints

All endpoints are mounted under `/api`:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/projects` | List all projects |
| GET | `/api/labels` | List all labels |
| GET | `/api/tasks` | List tasks (query: `projectId`, `status`, `label`, `query`) |
| GET | `/api/tasks/:id` | Get a single task |
| POST | `/api/tasks` | Create a task |
| PATCH | `/api/tasks/:id` | Update a task |
| DELETE | `/api/tasks/:id` | Delete a task |
| POST | `/api/tasks/:id/comments` | Add a comment |

## Usage Workflows

### Add a task through your LLM client

1. Configure the MCP client (see below).
2. Ask it to create a task:
   ```text
   在收件箱项目里创建一个标题为 "Review design system" 的高优先级任务。
   ```
3. The task is written to `.data/taskmcp.db`.

### View and edit tasks in the browser

1. Start the web server:
   ```bash
   npm run web
   ```
2. Open `http://localhost:3000`.
3. Use the search box, status filter, or label filter to find tasks.
4. Click a task card to edit, change status, add comments, or delete it.

### Both interfaces share the same data

Because MCP and Web open the same SQLite file, any change from one side appears in the other immediately after a refresh.

## MCP Clients

Replace `/path/to/CcTaskMCP` with the actual project path.

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "taskmcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/CcTaskMCP/src/mcp/index.ts"]
    }
  }
}
```

### opencode (`opencode.json`)

```json
{
  "mcp": {
    "taskmcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/CcTaskMCP/src/mcp/index.ts"]
    }
  }
}
```

## Note on the MCP SDK

The plan originally referenced `@modelcontextprotocol/sdk@^2.x`; npm currently ships `1.29.0` as the latest stable release. The server is implemented with the v1 `McpServer` API and is functionally equivalent for this project.

## License

MIT