zebbern-kali-mcp: Instructions file for Claude Code

CLAUDE.md

Operational notes for this repo. Everything here is a mistake that has actually been made, not general advice.

Two release tracks, and they are not the same

The wheel ships only mcp_server.py and mcp_tools/* (pyproject.toml py-modules / packages.find). Everything under zebbern-kali/ ships in the Docker image instead, and reaches users when docker-publish.yml rebuilds — not when you publish to PyPI.

Before proposing a release, check which track the change is on:

git diff --name-only <last-tag>..main

A change under zebbern-kali/ does not justify a PyPI bump, and a PyPI release does not deliver it. This has been misread once already — a proposed release turned out to contain nothing but a comment.

The local backend image goes stale silently

ghcr.io/zebbern/zebbern-kali-mcp:latest moves on every docker-publish run, which triggers on any push to main touching Dockerfile, .dockerignore, docker/**, docker-compose*.yml, entrypoint.sh, requirements.txt or zebbern-kali/**. A local copy pulled earlier keeps serving, and the symptoms never look like staleness:

• container reports unhealthy (an old image predating the /live route)
• /health reports an old version
• tests pass against bits nobody ships

docker compose pull && docker compose up -d --force-recreate
docker buildx imagetools inspect ghcr.io/zebbern/zebbern-kali-mcp:latest   # remote
docker image inspect ghcr.io/zebbern/zebbern-kali-mcp:latest --format '{{index .RepoDigests 0}}'

Compare those two digests before trusting anything the backend says. This has happened three times.

Targeting the host from inside the container

Inside the container 127.0.0.1 is the container's own loopback. The host (and anything published on it, e.g. a crAPI lab on 8888) is reachable as host.docker.internal. Scanning 127.0.0.1 finds an empty container and looks exactly like a broken MCP server.

Services on another compose network that are not host-published (crAPI's crapi-identity:8080, crapi-community:6060) need the Kali container attached to that network.