# graphicle.dev

> A hosted code-knowledge server for coding agents: read-only, indexed copies of 20 open-source repositories (code graph, symbols and sources, with file-and-line citations), served over MCP. Access needs a token (`gd_…`).

## Connect

- MCP endpoint: https://graphicle.dev/mcp (streamable HTTP; POST JSON-RPC; no SSE stream)
- Authentication: `Authorization: Bearer gd_…` on every request
- One server covers every repository listed below
- Full client setup (roc, opencode, Claude Code, Codex, any MCP client): https://graphicle.dev/SETUP.md

## Get a token

- A pass costs 0.99 RLUSD and lasts 3 hours from its first request. It can be used any time within 30 days of purchase.
- Passes are on sale: 50 of 50 available right now. No account or email; an agent can buy one, but paying needs an XRPL wallet holding RLUSD: if you can't sign a payment yourself, give your user the instructions from step 1.

### Buying a pass

1. `curl -s -X POST https://graphicle.dev/api/passes` returns `id`, `claim` (keep it secret: it's the only way to collect the token) and `pay`: `address`, `destination_tag`, `amount` (currency RLUSD, hex `524C555344000000000000000000000000000000`, its `issuer`, `value`), `pay_before`, and a ready `transaction` to sign.
2. Send one Payment of **exactly** `amount.value` RLUSD from that issuer to `address` **with** `destination_tag`, before `pay_before`. Don't set the partial-payment flag. A wrong amount, tag, issuer or a late payment issues no pass, and there are no refunds for human error.
3. Poll `curl -s https://graphicle.dev/api/passes/<id> -H "Authorization: Bearer <claim>"` every few seconds. `status` goes from `pending` to `paid`; the response then has `token` (`gd_…`). A payment that didn't count is listed under `rejected_payments` with the reason.
4. Use the token as below. Its 3 hours start with your first MCP request.

- `GET https://graphicle.dev/api/passes` shows the price and how many passes are available. `503` from `POST` means the club is full, or too many purchases are waiting; retry after `Retry-After`.

## Using the tools well

1. Call `list_projects` once: it gives every repository's project id.
2. Name the repository (`repo`) in `recall_project`, `query_graph`, `get_node`, `get_neighbors` and `read_project_source`. Without one, a search covers only the first 8 projects.
3. Use `query_graph` / `get_node` / `get_neighbors` for structure (who calls what, where a type is defined), `recall_project` for questions in words, and `read_project_source` for the exact lines.
4. Cite what you use: repository, file and lines.
5. `workspace_map` shows how the repositories import one another.

## Limits and errors

- 5 requests are served at a time across all members; others wait in order.
- One request per token runs at a time, with one more waiting.
- `429` + `Retry-After`: busy; wait that many seconds and retry.
- `503` + `Retry-After`: nightly maintenance (03:00 America/New_York) while new repositories are added; retry after it.
- `401`: no token, unknown, expired or revoked. `403`: the token doesn't include that part of the shelf.
- A pass's expiry is in the `X-Graphicle-Expires` response header.

## Licenses

Each repository's license is listed below. Keep license notices with any code you reuse. Copyleft repositories (AGPL, GPL, LGPL, MPL) may only be reused under their own terms: don't copy their code into projects under other licenses.

## Repositories

- go/bump: Apache-2.0, 13 MB, indexed 2026-11-01
- go/checkfs: Apache-2.0, 64 KB, indexed 2026-11-01
- go/concert: Apache-2.0, 4 MB, indexed 2026-11-01
- go/configure-ebs: Apache-2.0, 22 KB, indexed 2026-11-01
- go/disk-speed: MIT, 5 KB, indexed 2026-11-01
- go/figtree: MIT, 1 MB, indexed 2026-11-01
- go/gematria: Apache-2.0, 41 KB, indexed 2026-11-01
- go/go-animate-coin: MIT, 696 KB, indexed 2026-11-01
- go/goenv: Apache-2.0, 100 KB, indexed 2026-11-01
- go/goini: Apache-2.0, 41 KB, indexed 2026-11-01
- go/igo: MIT, 16 MB, indexed 2026-11-01
- go/lemmings: Apache-2.0, 1 MB, indexed 2026-11-01
- go/room: Apache-2.0, 594 KB, indexed 2026-11-01
- go/sema: Apache-2.0, 162 KB, indexed 2026-11-01
- go/summarize: MIT, 1 MB, indexed 2026-11-01
- go/textee: Apache-2.0, 26 KB, indexed 2026-11-01
- go/verbose: Apache-2.0, 2 MB, indexed 2026-11-01
- rust/graphicle: Apache-2.0, 152 MB, indexed 2026-11-01
- rust/roc: Apache-2.0, 610 KB, indexed 2026-11-01
- rust/toktail: Apache-2.0, 11 MB, indexed 2026-11-01

## Optional

- [repos.json](https://graphicle.dev/repos.json): the same list as JSON
- [status.json](https://graphicle.dev/status.json): queue and maintenance state