# taskboard-mcp

A small MCP server for task/todo tracking — structured, deterministic, no AI involved in
the tool itself. Built for LLM agents (or anyone) that need to track work across
sessions without paying the token cost of hand-editing a growing text file on every
status change.

## Why

Text-file task trackers (a `TASKS.md` you hand-edit) work, but get expensive to maintain
as they grow — every update means finding and rewriting a chunk of existing text. A
proper tool takes a few structured arguments (`task_update(id, state="done")`) instead,
and does the file/DB I/O itself.

## Design

- TypeScript, built on the official [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk).
- SQLite-backed storage (`better-sqlite3`) — structured, queryable, deterministic.
- Tasks are scoped by project/board, so one server instance can track work across many
  unrelated projects — `scope` is a first-class filter on every tool.
- Communicates over stdio, like any standard MCP server.

## Tools

| Tool | Arguments | Description |
| --- | --- | --- |
| `task_add` | `scope`, `content` | Create a new task (starts in state `open`). |
| `task_update` | `id`, and any of `scope`, `content`, `state` | Update fields on an existing task. |
| `task_list` | optional `scope`, `state` | List tasks, filtered by scope and/or state. |
| `task_complete` | `id` | Shorthand for `task_update(id, state="done")`. |
| `task_delete` | `id` | Permanently delete a task. |

Valid `state` values: `open`, `in_progress`, `done`.

Every task has: `id`, `scope`, `content`, `state`, `created_at`, `updated_at`,
`completed_at`.

## Install

```bash
git clone https://github.com/fellam/taskboard-mcp.git
cd taskboard-mcp
npm install
npm run build
```

This produces `dist/index.js`, a runnable Node entrypoint that speaks MCP over stdio.

## Usage

### Storage location

By default, data is stored in a SQLite file at `~/.taskboard-mcp/tasks.db`. Override with
the `TASKBOARD_DB_PATH` environment variable to point at a different file (or `:memory:`
for an ephemeral in-process database, mainly useful for testing).

### Wiring into Claude Code (`.mcp.json`)

Add this to your project's `.mcp.json` (or `claude_desktop_config.json` for Claude
Desktop):

```json
{
  "mcpServers": {
    "taskboard": {
      "command": "node",
      "args": ["/absolute/path/to/taskboard-mcp/dist/index.js"],
      "env": {
        "TASKBOARD_DB_PATH": "/absolute/path/to/your/tasks.db"
      }
    }
  }
}
```

Omit `env.TASKBOARD_DB_PATH` to use the default location. Restart your MCP client after
editing the config.

### Running directly

```bash
npm start          # runs the built server (dist/index.js) over stdio
npm run dev         # runs src/index.ts directly via tsx, no build step
```

## Development

```bash
npm test            # runs the test suite (node's built-in test runner + tsx)
npm run build        # type-checks and compiles src/ to dist/
```

## License

MIT — see [LICENSE](LICENSE).