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

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

{
  "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:

   python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

3. Check logs:

   tail -f ~/Library/Logs/Claude/mcp-server-gitea.log
   

4. Manual sanity test:

   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

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