Lesstime/docs/superpowers/specs/2026-03-15-mcp-server-design.md

# MCP Server for Lesstime — Design Spec

**Date**: 2026-03-15
**Status**: Draft
**Scope**: Expose projects, tasks, and time tracking via MCP for AI clients (Claude Code local first)

## Context

Lesstime is a project management app (Symfony 8 + API Platform 4). We want AI assistants to interact with projects, tasks, and time entries via the Model Context Protocol (MCP).

**Phase 1 (this spec)**: STDIO transport for Claude Code local usage.
**Phase 2 (future)**: HTTP transport + API token auth + Cloudflare Tunnel for remote clients (Claude Web, ChatGPT, Codex).

## Technology Choice

**`symfony/mcp-bundle`** — the official Symfony MCP bundle, maintained by Symfony + PHP Foundation + Anthropic. Uses PHP attributes (`#[McpTool]`) for auto-discovery.

## Architecture

### File Structure

```
src/Mcp/
├── Tool/
│   ├── Project/
│   │   ├── ListProjectsTool.php
│   │   ├── GetProjectTool.php
│   │   ├── CreateProjectTool.php
│   │   └── UpdateProjectTool.php
│   ├── Task/
│   │   ├── ListTasksTool.php
│   │   ├── GetTaskTool.php
│   │   ├── CreateTaskTool.php
│   │   ├── UpdateTaskTool.php
│   │   └── DeleteTaskTool.php
│   ├── TaskMeta/
│   │   ├── ListStatusesTool.php
│   │   ├── ListPrioritiesTool.php
│   │   ├── ListEffortsTool.php
│   │   ├── ListTagsTool.php
│   │   └── ListGroupsTool.php
│   ├── TimeEntry/
│   │   ├── ListTimeEntriesTool.php
│   │   ├── CreateTimeEntryTool.php
│   │   ├── UpdateTimeEntryTool.php
│   │   └── DeleteTimeEntryTool.php
│   └── Reference/
│       ├── ListUsersTool.php
│       └── ListClientsTool.php
```

### Configuration

```yaml
# config/packages/mcp.yaml
mcp:
    app: 'lesstime'
    version: '1.0.0'
    description: 'Lesstime project management — projects, tasks, time tracking'
    instructions: |
        This server provides access to the Lesstime project management system.
        You can list/create/update/delete projects, tasks, and time entries.
        Tasks belong to projects and have statuses, priorities, efforts, tags, and groups.
        Statuses, priorities, efforts, and tags are GLOBAL (shared across all projects).
        Groups are PER-PROJECT (each group belongs to one project).
        Time entries track work duration and can be linked to projects and tasks.
        Use list-statuses, list-priorities, list-efforts, list-tags, list-groups to discover
        available metadata before creating or updating tasks.
        Use list-users and list-clients to discover valid user and client IDs.
    client_transports:
        stdio: true
        http: false  # Phase 2
```

### Claude Code Configuration

```json
// .claude/settings.json or project settings
{
  "mcpServers": {
    "lesstime": {
      "command": "docker",
      "args": ["exec", "-i", "php-lesstime-fpm", "php", "bin/console", "mcp:server"],
      "cwd": "/home/r-dev/Lesstime"
    }
  }
}
```

Note: The app runs in Docker (`php-lesstime-fpm` container), so the command uses `docker exec` to run inside the container.

### Security Model (Phase 1)

Phase 1 uses STDIO transport only (Claude Code local). The console command runs without a Symfony security context. All tools run with **full privileges** (equivalent to ROLE_ADMIN), since only the local developer has access. No authentication is needed.

Phase 2 will add API token authentication on the HTTP transport.

## Tools Specification

### Reference Tools (ID Discovery)

#### `list-users`
- **Description**: List all users (needed to resolve assignee/user IDs)
- **Returns**: Array of `{ id, username }`
- **Implementation**: `UserRepository::findBy([], ['username' => 'ASC'])`

#### `list-clients`
- **Description**: List all clients (needed to resolve client IDs for projects)
- **Returns**: Array of `{ id, name, email }`
- **Implementation**: `ClientRepository::findBy([], ['name' => 'ASC'])`

### Project Tools

#### `list-projects`
- **Description**: List all projects with optional archive filter
- **Parameters**: `archived` (bool, optional, default: false)
- **Returns**: Array of `{ id, code, name, description, color, client: { id, name } | null, archived }`
- **Implementation**: `ProjectRepository::findBy(['archived' => $archived], ['name' => 'ASC'])`

#### `get-project`
- **Description**: Get project details with task count summary per status
- **Parameters**: `id` (int, required)
- **Returns**: `{ id, code, name, description, color, client, archived, taskSummary: { statusLabel: count, ... }, totalTasks }`
- **Implementation**: `ProjectRepository::find($id)` + DQL count query grouped by status

#### `create-project`
- **Description**: Create a new project
- **Parameters**: `name` (string, required), `code` (string, required, 2-10 uppercase letters), `description` (string, optional), `color` (string, optional), `clientId` (int, optional)
- **Returns**: Created project object
- **Implementation**: Create `Project` entity, persist via `EntityManager`

#### `update-project`
- **Description**: Update an existing project (partial update)
- **Parameters**:
  - `id` (int, required)
  - `name` (string, optional)
  - `code` (string, optional)
  - `description` (string, optional)
  - `color` (string, optional)
  - `clientId` (int, optional)
  - `archived` (bool, optional)
- **Returns**: Updated project object
- **Implementation**: Find project, apply changes, flush

### Task Tools

#### `list-tasks`
- **Description**: List tasks with filters. Returns max 100 results, use filters to narrow down.
- **Parameters**:
  - `projectId` (int, optional) — filter by project
  - `statusId` (int, optional) — filter by status
  - `assigneeId` (int, optional) — filter by assignee
  - `priorityId` (int, optional) — filter by priority
  - `groupId` (int, optional) — filter by group
  - `tagIds` (int[], optional) — filter by tags
  - `archived` (bool, optional, default: false)
  - `limit` (int, optional, default: 100, max: 200)
- **Returns**: Array of `{ id, number, title, status: { id, label, color }, priority: { id, label, color } | null, assignee: { id, username } | null, effort: { id, label } | null, group: { id, title } | null, project: { id, code, name }, tags: [{ id, label }], archived }`
- **Implementation**: `TaskRepository` with QueryBuilder, conditional filters, and `setMaxResults($limit)`. Joins must include all relations: status, priority, assignee, project, effort, group, tags.

#### `get-task`
- **Description**: Get full task details
- **Parameters**: `id` (int, required)
- **Returns**: Full task object including `{ id, number, title, description, status, priority, effort, assignee, group, project, tags, documents: [{ id, originalName, mimeType, size, createdAt, uploadedBy: { id, username } }], archived }`
- **Implementation**: `TaskRepository::find($id)` with eager loading

#### `create-task`
- **Description**: Create a new task (number auto-generated per project)
- **Parameters**:
  - `projectId` (int, required)
  - `title` (string, required)
  - `description` (string, optional)
  - `statusId` (int, optional)
  - `priorityId` (int, optional)
  - `effortId` (int, optional)
  - `assigneeId` (int, optional)
  - `groupId` (int, optional)
  - `tagIds` (int[], optional)
- **Returns**: Created task with auto-generated number
- **Implementation**: Create `Task` entity, reuse `TaskRepository::findMaxNumberByProject()` for number generation (same logic as `TaskNumberProcessor`), set relations, persist

#### `update-task`
- **Description**: Update an existing task (partial update, only provided fields are changed)
- **Parameters**:
  - `id` (int, required)
  - `title` (string, optional)
  - `description` (string, optional)
  - `statusId` (int, optional)
  - `priorityId` (int, optional)
  - `effortId` (int, optional)
  - `assigneeId` (int, optional)
  - `groupId` (int, optional)
  - `tagIds` (int[], optional)
  - `archived` (bool, optional)
- **Returns**: Updated task object
- **Implementation**: Find task, apply changes, flush

#### `delete-task`
- **Description**: Delete a task permanently
- **Parameters**: `id` (int, required)
- **Returns**: `{ success: true, message: "Task PROJECT-123 deleted" }`
- **Implementation**: `EntityManager::remove()` + flush (cascade deletes documents)

### TaskMeta Tools (Read-Only)

Statuses, priorities, efforts, and tags are **global** (shared across all projects). Groups are **per-project**.

#### `list-statuses`
- **Description**: List all task statuses (needed to create/update tasks)
- **Returns**: Array of `{ id, label, color, position, isFinal }`
- **Implementation**: `TaskStatusRepository::findBy([], ['position' => 'ASC'])`

#### `list-priorities`
- **Description**: List all task priorities
- **Returns**: Array of `{ id, label, color }`
- **Implementation**: `TaskPriorityRepository::findBy([], ['label' => 'ASC'])`

#### `list-efforts`
- **Description**: List all task effort levels
- **Returns**: Array of `{ id, label }`
- **Implementation**: `TaskEffortRepository::findBy([], ['label' => 'ASC'])`

#### `list-tags`
- **Description**: List all task tags
- **Returns**: Array of `{ id, label, color }`
- **Implementation**: `TaskTagRepository::findBy([], ['label' => 'ASC'])`

#### `list-groups`
- **Description**: List task groups, optionally filtered by project. Groups are per-project.
- **Parameters**: `projectId` (int, optional), `archived` (bool, optional, default: false)
- **Returns**: Array of `{ id, title, description, color, project: { id, code, name }, archived }`
- **Implementation**: `TaskGroupRepository` with optional project filter

### TimeEntry Tools

#### `list-time-entries`
- **Description**: List time entries with filters
- **Parameters**:
  - `userId` (int, optional)
  - `projectId` (int, optional)
  - `taskId` (int, optional)
  - `startDate` (string, optional, format: YYYY-MM-DD)
  - `endDate` (string, optional, format: YYYY-MM-DD)
  - `limit` (int, optional, default: 100, max: 200)
- **Returns**: Array of `{ id, title, description, startedAt, stoppedAt, duration, user: { id, username }, project: { id, code, name } | null, task: { id, number, title } | null, tags: [{ id, label }] }`
- **Note**: `duration` is computed from `stoppedAt - startedAt` in minutes. Returns `null` for active timers (stoppedAt is null).
- **Implementation**: `TimeEntryRepository` with QueryBuilder, date range filter on `startedAt`

#### `create-time-entry`
- **Description**: Create a time entry
- **Parameters**:
  - `userId` (int, required)
  - `startedAt` (string, required, ISO 8601)
  - `title` (string, optional)
  - `stoppedAt` (string, optional, ISO 8601 — if null, creates active timer)
  - `projectId` (int, optional)
  - `taskId` (int, optional)
  - `tagIds` (int[], optional)
  - `description` (string, optional)
- **Returns**: Created time entry
- **Implementation**: Create `TimeEntry`, set relations, persist. Validate no other active timer for user if stoppedAt is null.

#### `update-time-entry`
- **Description**: Update a time entry (e.g., stop a running timer, correct start time)
- **Parameters**:
  - `id` (int, required)
  - `title` (string, optional)
  - `startedAt` (string, optional, ISO 8601)
  - `stoppedAt` (string, optional, ISO 8601)
  - `projectId` (int, optional)
  - `taskId` (int, optional)
  - `tagIds` (int[], optional)
  - `description` (string, optional)
- **Returns**: Updated time entry
- **Note**: `userId` is intentionally not updatable via MCP. Reassigning time entries to another user should be done through the app UI.
- **Implementation**: Find entry, apply changes, flush

#### `delete-time-entry`
- **Description**: Delete a time entry
- **Parameters**: `id` (int, required)
- **Returns**: `{ success: true, message: "Time entry deleted" }`
- **Implementation**: `EntityManager::remove()` + flush

## Tool Return Format

All tools return JSON strings. For consistency:

- **List tools**: Return a JSON array of objects
- **Get/Create/Update tools**: Return a single JSON object
- **Delete tools**: Return `{ success: true, message: "..." }`
- **Errors**: Throw exceptions (the MCP bundle handles error responses)
- **Duration**: Computed field (minutes), `null` for active timers

Example tool implementation pattern:

```php
<?php

declare(strict_types=1);

namespace App\Mcp\Tool\Task;

use App\Repository\TaskRepository;
use Mcp\Capability\Attribute\McpTool;

class ListTasksTool
{
    public function __construct(
        private readonly TaskRepository $taskRepository,
    ) {
    }

    #[McpTool(name: 'list-tasks', description: 'List tasks with optional filters by project, status, assignee, priority, group, tags, and archive state')]
    public function __invoke(
        ?int $projectId = null,
        ?int $statusId = null,
        ?int $assigneeId = null,
        ?int $priorityId = null,
        ?int $groupId = null,
        ?array $tagIds = null,
        bool $archived = false,
        int $limit = 100,
    ): string {
        $limit = min($limit, 200);

        $qb = $this->taskRepository->createQueryBuilder('t')
            ->leftJoin('t.status', 's')->addSelect('s')
            ->leftJoin('t.priority', 'p')->addSelect('p')
            ->leftJoin('t.assignee', 'a')->addSelect('a')
            ->leftJoin('t.project', 'pr')->addSelect('pr')
            ->leftJoin('t.effort', 'e')->addSelect('e')
            ->leftJoin('t.group', 'g')->addSelect('g')
            ->leftJoin('t.tags', 'tg')->addSelect('tg')
            ->where('t.archived = :archived')
            ->setParameter('archived', $archived)
            ->orderBy('t.id', 'DESC')
            ->setMaxResults($limit);

        if ($projectId !== null) {
            $qb->andWhere('pr.id = :projectId')->setParameter('projectId', $projectId);
        }
        if ($statusId !== null) {
            $qb->andWhere('s.id = :statusId')->setParameter('statusId', $statusId);
        }
        if ($assigneeId !== null) {
            $qb->andWhere('a.id = :assigneeId')->setParameter('assigneeId', $assigneeId);
        }
        if ($priorityId !== null) {
            $qb->andWhere('p.id = :priorityId')->setParameter('priorityId', $priorityId);
        }
        if ($groupId !== null) {
            $qb->andWhere('t.group = :groupId')->setParameter('groupId', $groupId);
        }

        $tasks = $qb->getQuery()->getResult();

        // Filter by tags in PHP (ManyToMany not easily filterable in DQL)
        if ($tagIds !== null) {
            $tasks = array_filter($tasks, function ($task) use ($tagIds) {
                $taskTagIds = $task->getTags()->map(fn($t) => $t->getId())->toArray();
                return !empty(array_intersect($tagIds, $taskTagIds));
            });
        }

        return json_encode(array_map(fn($task) => [
            'id' => $task->getId(),
            'number' => $task->getNumber(),
            'title' => $task->getTitle(),
            'status' => $task->getStatus() ? [
                'id' => $task->getStatus()->getId(),
                'label' => $task->getStatus()->getLabel(),
                'color' => $task->getStatus()->getColor(),
            ] : null,
            'priority' => $task->getPriority() ? [
                'id' => $task->getPriority()->getId(),
                'label' => $task->getPriority()->getLabel(),
                'color' => $task->getPriority()->getColor(),
            ] : null,
            'assignee' => $task->getAssignee() ? [
                'id' => $task->getAssignee()->getId(),
                'username' => $task->getAssignee()->getUsername(),
            ] : null,
            'effort' => $task->getEffort() ? [
                'id' => $task->getEffort()->getId(),
                'label' => $task->getEffort()->getLabel(),
            ] : null,
            'group' => $task->getGroup() ? [
                'id' => $task->getGroup()->getId(),
                'title' => $task->getGroup()->getTitle(),
            ] : null,
            'project' => [
                'id' => $task->getProject()->getId(),
                'code' => $task->getProject()->getCode(),
                'name' => $task->getProject()->getName(),
            ],
            'tags' => $task->getTags()->map(fn($t) => [
                'id' => $t->getId(),
                'label' => $t->getLabel(),
            ])->toArray(),
            'archived' => $task->isArchived(),
        ], array_values($tasks)));
    }
}
```

## Installation Steps

1. `composer require symfony/mcp-bundle` (inside Docker container)
2. Create `config/packages/mcp.yaml` with STDIO transport
3. Create tool classes in `src/Mcp/Tool/`
4. Test with `php bin/console mcp:server` (STDIO)
5. Configure Claude Code settings to point to the MCP server

Note: STDIO transport does not need HTTP routes. Routes are only needed for Phase 2 (HTTP transport).

## Phase 2 (Future)

When ready for remote clients:

1. Enable HTTP transport on `/_mcp`
2. Add MCP route: `config/routes/mcp.yaml`
3. Add `apiToken` field on `User` entity + migration
4. Create `ApiTokenAuthenticator` (Symfony custom authenticator)
5. Add firewall rule for `/_mcp` path
6. Set up Cloudflare Tunnel for external access
7. Configure Claude Web / ChatGPT / Codex with the tunnel URL + token