crewli/dev-docs/CLAUDE_DESKTOP_SETUP.md

# Claude Desktop setup voor Crewli

Deze pagina beschrijft hoe Claude Desktop (de architect/PM-chat)
toegang krijgt tot deze repository. Geldt voor Bert's lokale werkomgeving.

Voor Claude Code (de terminal tool) is geen aparte setup nodig — die leest
de repo direct van de filesystem waarin hij wordt gestart.

## Architectuur in één regel

Claude Desktop → Gitea MCP server (Docker, lokaal op Mac) → HTTPS → `https://gitea.hausmans.cloud`

Project knowledge in Claude Desktop is bewust **leeg** voor dit project.
Alle dev-docs worden live gelezen uit de `main` branch via de Gitea MCP
connector, zodat Claude altijd met de actuele waarheid werkt en er geen
hand-sync nodig is bij elke commit.

## Wat is er geconfigureerd

### 1. Gitea Personal Access Token

Gegenereerd onder `bert.hausmans` in Gitea:
- Settings → Applications → Generate New Token
- Naam: `claude-desktop` (of vergelijkbaar)
- Scopes: `read:repository`, `read:user`, `read:organization`, `write:repository`

De token is plaintext opgeslagen in de Claude Desktop config.

### 2. Docker image

```bash
docker pull docker.gitea.com/gitea-mcp-server
```

Docker Desktop moet draaien op de Mac. Als Docker Desktop niet actief is,
werkt de MCP-connector niet en krijgt Claude een transport error in de logs.

### 3. Claude Desktop config

Locatie: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gitea": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITEA_HOST",
        "-e",
        "GITEA_ACCESS_TOKEN",
        "docker.gitea.com/gitea-mcp-server",
        "/app/gitea-mcp",
        "-t",
        "stdio"
      ],
      "env": {
        "GITEA_HOST": "https://gitea.hausmans.cloud",
        "GITEA_ACCESS_TOKEN": "PASTE_PAT_HERE"
      }
    }
  }
}
```

**Let op de `/app/gitea-mcp` regel** — de Docker image heeft geen
`ENTRYPOINT`, alleen een `CMD` op `/app/gitea-mcp`. Zonder dit expliciete
pad gooit Docker een `executable file not found in $PATH` error.

Na elke config-wijziging: **⌘Q om Claude Desktop volledig te sluiten**,
daarna opnieuw starten. Het rode kruis-knopje sluit alleen het venster
— MCP-subprocessen blijven dan op de oude config hangen.

Bestandspermissies: `chmod 600` op de config-file.

### 4. Project instructions in Claude Desktop

Onder dit Claude project (Claude Desktop sidebar → klik op project →
Project instructions) staat een notitie die toekomstige sessies briefst
dat uploads leeg zijn en dev-docs via Gitea MCP opgehaald moeten worden.

## Beschikbare Gitea tools in Claude

De connector exposeert onder andere:

- `gitea:get_me` — bevestig PAT werkt
- `gitea:get_file_contents` — haal een specifieke file op
- `gitea:get_dir_contents` — lijst entries in een directory
- `gitea:get_repository_tree` — recursieve tree
- `gitea:search_issues` — zoek issues en PRs
- `gitea:create_or_update_file` — schrijf een file (vereist `write:repository`)
- `gitea:issue_write` / `gitea:pull_request_write` — create/edit issues en PRs
- En ca. 40 andere tools voor labels, milestones, releases, actions, etc.

## Wat er in project knowledge NIET meer zit

Bewust verwijderd uit Claude Desktop project knowledge (23 april 2026):

```
.cursorrules
CLAUDE.md
VUEXY_COMPONENTS.md
VIBE_CODING_CHECKLIST.md
UX_SPEC_FESTIVAL_HIERARCHY.md
S3a-public-form-api.md
TEST_SCENARIO.md
start-guide.md
SETUP.md
SECURITY_AUDIT.md
SCHEMA.md
form-builder-migration-playbook.md
form-builder-getting-started.md
design-document.md
COPY_CATALOGUE.md
BACKLOG.md
AUTH_ARCHITECTURE.md
ARCH-FORM-BUILDER.md
API.md
```

Al deze documenten staan in `dev-docs/` of `/.cursorrules` en worden direct
uit Gitea gelezen. Niet opnieuw uploaden — dat leidt alleen tot twee
waarheidsbronnen die uit sync kunnen raken.

## Troubleshooting

### Tool slider toont geen Gitea tools

1. Check of Docker Desktop draait (whale-icoon in menubar)
2. Validate de JSON config:
   ```bash
   python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```
3. Check logs:
   ```bash
   tail -f ~/Library/Logs/Claude/mcp-server-gitea.log
   ```
4. Manual sanity test:
   ```bash
   docker run -i --rm \
     -e GITEA_HOST=https://gitea.hausmans.cloud \
     -e GITEA_ACCESS_TOKEN=jouw_pat \
     docker.gitea.com/gitea-mcp-server \
     /app/gitea-mcp -t stdio
   ```
   Mag niks doen (wacht op stdin). Ctrl+C om te stoppen.
5. Vergeet niet `⌘Q` op Claude Desktop na config-aanpassing.

### Authenticatie-errors (401)

PAT verlopen of ingetrokken. Genereer een nieuwe, update
`GITEA_ACCESS_TOKEN` in config, ⌘Q + restart.

## Updaten van de MCP server

```bash
docker pull docker.gitea.com/gitea-mcp-server
```

Claude Desktop gebruikt de laatst-gepulde image op z'n eerstvolgende
subprocess-spawn (bij volgende tool call).

## Gerelateerd

- `CLAUDE.md` (repo root) — instructies voor Claude Code, niet Claude Desktop
- `dev-docs/SETUP.md` — ontwikkelworkflow