From 3671d0e30203fb1aa494fcecb1dbf707b2e43f2b Mon Sep 17 00:00:00 2001 From: settletop-niles Date: Tue, 11 Aug 2026 10:20:07 -0400 Subject: [PATCH] docs: full install + Claude Code usage (Docker/GHCR + uv) Adds a copy-pasteable install section: docker login to GHCR (private package), pull + run the image, register with Claude Code via `claude mcp add -- docker run --rm -i ... ` (and the local uv form), a config/env table, the real tool list, and a smoke check. Every command/env/tool/entrypoint verified against source; each documented docker-run MCP invocation was run live (handshake OK). Co-Authored-By: Claude Opus 4.8 --- README.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index babc668..c638242 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,63 @@ fields on top of that — a business-domain guess, a citation-backed second look a borderline case — and every one of those is labelled as LLM-derived. Bring your own model, or run with none at all. -## Quickstart +## Install & run + +### Run with Docker (GHCR) + +Prebuilt images are published to the GitHub Container Registry. The package is +**private**, so authenticate to GHCR once per machine before pulling — without +it `docker pull`/`docker run` returns `403`: + +```bash +# One-time: log in with a GitHub Personal Access Token (classic) that carries +# the read:packages scope, supplied as the password. +docker login ghcr.io -u +# (or: gh auth refresh -s read:packages && gh auth token | \ +# docker login ghcr.io -u --password-stdin) +``` + +Then pull and run the HTTP API — the mode the image runs by default +(`uvicorn` on port 8081): + +```bash +docker pull ghcr.io/settletop-inc/coderoot-repo-assessor:latest + +docker run --rm -p 8081:8081 \ + -e ASSESSOR_API_TOKEN=changeme \ + ghcr.io/settletop-inc/coderoot-repo-assessor:latest +``` + +Tags: `:latest` and `:sha-` track `main`; release builds are tagged +`:vX.Y.Z`. No `-v` mount is needed — acquisition clones the remote `repo_url` +you pass it, not a local working directory. To run this same image as a **stdio +MCP server** for Claude Code instead of the HTTP API, see +[Use with Claude Code](#use-with-claude-code) below — it overrides the default +command. + +The minimum you must set, and the optional knobs (full list under +[Configuration](#configuration)): + +| Variable | Required? | Meaning | +| --- | --- | --- | +| `ASSESSOR_API_TOKEN` | one of these two | Bearer token required on every authenticated HTTP route. Startup fails closed without it. | +| `ASSESSOR_ALLOW_ANONYMOUS` | one of these two | Set `true` to run with no token (deliberate opt-out). Startup fails closed unless this or `ASSESSOR_API_TOKEN` is set. | +| `GITHUB_TOKENS` | no | Comma-separated PATs. Raises the GitHub REST rate limit (60 → 5000/hr) for repo-object and commit-SHA lookups; acquisition still works without it, anonymously. | +| `LLM_PROVIDER` / `LLM_BASE_URL` / `LLM_MODEL` | no | Point at an OpenAI-compatible endpoint to enable advisory LLM-derived fields. Classification is fully deterministic with none set (`LLM_PROVIDER` defaults to `none`). | + +To add a model and raise the GitHub rate limit: + +```bash +docker run --rm -p 8081:8081 \ + -e ASSESSOR_API_TOKEN=changeme \ + -e GITHUB_TOKENS=ghp_xxx,ghp_yyy \ + -e LLM_PROVIDER=openai_compatible \ + -e LLM_BASE_URL=http://host.docker.internal:11434/v1 \ + -e LLM_MODEL=qwen2.5:7b \ + ghcr.io/settletop-inc/coderoot-repo-assessor:latest +``` + +### Build from source ```bash docker build -t coderoot-repo-assessor:dev . @@ -87,6 +143,54 @@ coderoot-repo-assessor-mcp Point any MCP client (Claude Desktop, an IDE plugin, etc.) at this command as a subprocess and it speaks MCP over that process's stdin/stdout. +### Use with Claude Code + +The MCP surface speaks over **stdio**, so Claude Code launches the server as a +subprocess. The default Docker command runs the *HTTP API*, so the registration +overrides it with the stdio entrypoint (`coderoot-repo-assessor-mcp`) as the +trailing argument. The `-i` (keep STDIN attached) is required for stdio MCP. + +**Docker (published image):** + +```bash +claude mcp add coderoot-repo-assessor -- \ + docker run --rm -i \ + -e ASSESSOR_ALLOW_ANONYMOUS=true \ + ghcr.io/settletop-inc/coderoot-repo-assessor:latest \ + coderoot-repo-assessor-mcp +``` + +`ASSESSOR_ALLOW_ANONYMOUS=true` is here because startup fails closed without a +token or this flag (see [config](#configuration)); over stdio there is no HTTP +endpoint and no bearer check, so anonymous is the honest choice for a locally +launched subprocess. Swap in `-e ASSESSOR_API_TOKEN=` if you prefer. +Add `-e GITHUB_TOKENS=ghp_xxx,ghp_yyy` to raise the GitHub rate limit, and the +`LLM_*` vars to enable advisory model fields. + +**Local, no Docker (uv):** + +```bash +claude mcp add coderoot-repo-assessor \ + -e ASSESSOR_ALLOW_ANONYMOUS=true \ + -- uv run --directory /path/to/CodeRoot-Repo-Assessor coderoot-repo-assessor-mcp +``` + +Once connected, these three tools appear in Claude Code: + +- `assess_repository(repo_url, subject_key="", subdir="")` +- `acquire_repository(repo_url)` +- `assessor_version()` + +**Confirm it's wired up** — the server should report `✓ Connected` and its +tools should list: + +```bash +claude mcp list +# coderoot-repo-assessor: docker run --rm -i ... - ✓ Connected +``` + +Removal, if you want to start over, is `claude mcp remove coderoot-repo-assessor`. + ## Configuration Every setting arrives as an environment variable (`.env.example` is the