Blame · Line-by-line history

`CLAUDE_SETUP.md`

Each line is annotated with the commit that last touched it. Click any SHA to jump to that commit and see the surrounding change.

CLAUDE_SETUP.mdBlame99 lines · 1 contributor

Normal view Raw

3b99c5fTest User	1	# Claude Setup for Gluecron
	2
	3	This doc covers how to wire Claude (Desktop or Code) to Gluecron's native
	4	MCP server so it drives this repo through Gluecron's tools — not GitHub's.
	5
	6	## Why we use Gluecron MCP instead of GitHub MCP
	7
	8	Gluecron self-hosts. The canonical remote for every Gluecron repo is
	9	`https://gluecron.com/<owner>/<repo>.git`; GitHub is a 7-day fallback
	10	mirror only. Every PR, issue, comment, merge, and review must land on
	11	Gluecron first or it doesn't exist as far as the platform is concerned.
	12
	13	The Gluecron MCP server (`POST /mcp`, see `src/lib/mcp-tools.ts`) exposes
	14	15 tools — 5 read, 10 write — covering the full lifecycle:
	15
	16	- `gluecron_repo_search`, `gluecron_repo_read_file`,
	17	`gluecron_repo_list_issues`, `gluecron_repo_explain_codebase`,
	18	`gluecron_repo_health` (read).
	19	- `gluecron_create_issue`, `gluecron_comment_issue`,
	20	`gluecron_close_issue`, `gluecron_reopen_issue` (issues).
	21	- `gluecron_create_pr`, `gluecron_get_pr`, `gluecron_list_prs`,
	22	`gluecron_comment_pr`, `gluecron_merge_pr`, `gluecron_close_pr` (PRs).
	23
	24	If Claude falls back to a `mcp__github__*` write tool, the change lands on
	25	the wrong source of truth and the deploy pipeline (`scripts/self-deploy.sh`)
	26	never fires. That's why `.claude/settings.json` denies the GitHub write
	27	tools at the harness layer.
	28
	29	## Set up Claude Desktop (30 seconds)
	30
	31	Two equally valid paths:
	32
	33	### Option A — drag the `.dxt` extension
	34
	35	1. Open <https://gluecron.com/> and download `public/gluecron.dxt`.
	36	2. Drag it onto the Claude Desktop window. Claude prompts for two values:
	37	- `gluecron_host` — leave as `https://gluecron.com` unless you run a
	38	private instance.
	39	- `gluecron_pat` — paste a token from `/settings/tokens` (admin
	40	scope; the merge tool needs it).
	41	3. Done. Restart Claude Desktop. Ask "list my open Gluecron repos" — it
	42	should call `gluecron_repo_search` immediately.
	43
	44	### Option B — one-line installer
	45
	46	```bash
	47	curl -sSL https://gluecron.com/install \| bash
	48	```
	49
	50	The script signs you in, mints a PAT, and merges a `gluecron` entry into
	51	`~/Library/Application Support/Claude/claude_desktop_config.json`
	52	(macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux / WSL).
	53	Idempotent — safe to re-run.
	54
	55	## Set up Claude Code
	56
	57	No setup. The repo ships `.claude/settings.json`. Claude Code reads
	58	it automatically every session opened inside this checkout.
	59
	60	The only thing you provide is a `GLUECRON_PAT` env var in your shell:
	61
	62	```bash
	63	export GLUECRON_PAT="glc_..." # from https://gluecron.com/settings/tokens
	64	```
	65
	66	The settings file uses `${env:GLUECRON_PAT}` as the bearer token, so the
	67	PAT never lands in any file under version control.
	68
	69	## Verify it's working
	70
	71	Open Claude inside this repo and ask:
	72
	73	> list my open PRs
	74
	75	A correctly-wired Claude will call `gluecron_list_prs` (you'll see it in
	76	the tool-call trace). It must NOT call anything starting with
	77	`mcp__github__`. If it does, the settings file's deny list will surface
	78	a `permission denied` error — switch to the `gluecron_*` equivalent.
	79
	80	Other smoke prompts:
	81
	82	\| Prompt \| Expected MCP tool \|
	83	\| --- \| --- \|
	84	\| "Show me issue 17" \| `gluecron_repo_list_issues` (then narrow) \|
	85	\| "Comment 'thanks' on PR 42" \| `gluecron_comment_pr` \|
	86	\| "What's the health score of ccantynz/Gluecron.com?" \| `gluecron_repo_health` \|
	87	\| "Search repos for 'rate limiter'" \| `gluecron_repo_search` \|
	88
	89	## Troubleshooting
	90
	91	- "authentication required for gluecron_..." — the MCP server got the
	92	request but the PAT didn't authenticate. Re-mint at `/settings/tokens`
	93	and update `GLUECRON_PAT`.
	94	- "permission denied: mcp__github__create_pull_request" — Claude
	95	tried to fall back to GitHub. The deny list caught it. Re-prompt
	96	with "use Gluecron, not GitHub".
	97	- Skill not auto-invoking — make sure the active git remote contains
	98	`gluecron.com` (`git remote -v`), or export `GLUECRON_HOST` to override
	99	the detection.