docs: add Solana onboarding runbooks for the MCP - #197
Merged
Conversation
Jared-dz
self-requested a review
August 12, 2026 11:59
karl-dz
pushed a commit
to malbeclabs/lake
that referenced
this pull request
Aug 12, 2026
## Summary - Extends the DoubleZero MCP with guided onboarding: `get_onboarding_runbook` loads walkthroughs from public docs (catalog from GitHub raw `docs/runbooks.md`). - Replaces the mock edge-access check with a real `check_edge_access` that execs `doublezero access-pass get --user-payer <pubkey> --client-ip <ip> --json` on the API host, so onchain state is the source of truth. Only a `connected` pass reports `active`; `requested`/`disconnected`/`expired` report `pending` with per-status guidance. - Moves docs fetching into `utils/pkg/docsfetch` (shared by `read_docs` and the runbook loader), bounded at 10k per page. - Removes the embedded runbook fallback (`api/handlers/runbooks/`). Catalog and bodies come only from docs — no in-repo mockups. - Based on [@armcconnell](https://github.com/armcconnell)'s MCP onboarding mockup work (`lake-private` / `mcp-onboarding`). ## Docs dependency (cross-repo — cannot merge here) The runbook index (`docs/runbooks.md`) and the runbook pages land via **[malbeclabs/docs#197](malbeclabs/docs#197 in a separate repo. There is **no embed fallback**: until that PR merges, `get_onboarding_runbook` cannot list or load runbooks. **Merge docs#197 first (or together), then this.** ## Deployment note `check_edge_access` requires the `doublezero` CLI on the API host. Hosts without it get a clear tool error ("access pass lookup failed"); no other tool is affected. ## Testing Verification - Verified the docs#197 `runbooks.md` index format parses with the catalog parser (fenced example block is stripped; all three runbook entries parse). - Verified `doublezero access-pass get` behavior against a live testnet host: connected pass with `0.0.0.0` wildcard resolves for an arbitrary receiving IP, lowercase `status` in JSON, exit 1 + `Error: Access Pass not found` on a miss. - Red-checked the status gating tests: against the previous code a `requested` pass reported `active`; the new tests fail on that code and pass on the fix. - `get_onboarding_runbook` exercised with local docs fixtures; missing index / missing page return clear errors (no embed path). --------- Co-authored-by: Jared-dz <jared@doublezero.us>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/runbooks.mdindex so the DoubleZero MCP can discover onboarding walkthroughs from GitHub raw.exclude_docs) so they are not on the docs site nav.