0.1.0npm · @shlokkhemani/rabbithole · current release
Observed 2026-08-23T16:10:00.782Z using mcpSecurity-inventory. Status: succeeded. Negotiated protocol: 2025-06-18.
{
"tools": {
"listChanged": true
}
}| Tool | Category | Annotations | Risk |
|---|---|---|---|
answer_branchAnswer one pending branch_request or convert_request from an open Rabbithole. For convert_request, read every pages[].image_path in order, follow rules exactly, stream transcription chunks, and emit figure: refs rather than cropping. For branch_request, write a focused answer using the supplied selection context; when region.image_path is present, it may be the new selection clip or the immediate parent's clip, so read it and trust it over extracted text.
Authoring vocabulary:
- Base notation: GFM markdown, $...$/$$...$$ and \(...\)/\[...\] math, and highlighted language-tagged code fences.
- If the answer is content fetched from a URL or repo, pass its document URL as base_url so relative images and links resolve.
- If the answer uses a local image, pass assets: [{ name, file_path }] and reference it as ; use this for screenshots, generated diagrams, and other non-web images.
- Use standard ```mermaid fences for flowcharts, sequence, class, state, and entity-relationship diagrams.
- Use ```show for bespoke spatial explanations that Mermaid cannot express well: architecture layouts, memory diagrams, comparisons, and custom relationships.
- show dialect: HTML/CSS/inline-SVG only; no scripts. Scripts and unsafe attributes are stripped.
- show craft: prefer HTML/CSS layout with flexbox/grid over absolute SVG coordinates.
- Design visuals for about 380px card width; make them fluid and keep labels short.
- Use theme tokens, never hardcoded colors, so visuals match light and dark themes:
--fg, --fg-bold, --fg-dim, --fg-faint, --node-bg, --bar-bg, --border, --border-focus, --accent, --accent-contrast, --code-bg, --hl, --hl-strong, --warn, --font-ui, --font-doc, --font-mono.
- Example show:
```show
<style>.flow{display:grid;gap:8px}.box{border:1px solid var(--border);padding:8px;border-radius:6px}</style>
<div class='flow'><div class='box'>Parse</div><div class='box' style='background:var(--hl)'>Render</div></div>
```
- Example Mermaid:
```mermaid
flowchart LR
Question --> Explore --> Understand
```
- Mermaid mindmap, architecture, and Mermaid-side KaTeX syntax are not supported; use ```show or ordinary math around the diagram instead.
- Streaming choreography: send prose in 1-3 sentence chunks as usual.
- Emit each visual fence contiguously, ideally in one chunk; readers see a placeholder until the fence closes.
- Interleave prose -> visual -> prose when useful. Use a visual only when it genuinely carries the explanation.
Finish streaming by sending the remaining final chunk in a normal call with a short 'title'. Partial chunks concatenate verbatim: include your own spacing/newlines and never repeat text already sent. The final call blocks and returns the next event. If it returns status='keep_listening', immediately call open_rabbithole { hole_id }; if the host reports a tool timeout (e.g. timed out awaiting tools/call), do the same. Do not re-send content; asks are saved.Input schema{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"maxLength": 200,
"description": "Active session ID from open_rabbithole"
},
"request_id": {
"type": "string",
"maxLength": 200,
"description": "The request_id of the branch_request being answered"
},
"title": {
"type": "string",
"maxLength": 2000,
"description": "Short label for the new node (a few words; required on the final call)"
},
"content": {
"type": "string",
"maxLength": 10485760,
"description": "Markdown chunk (partial) or the remaining markdown (final call)"
},
"base_url": {
"type": "string",
"maxLength": 2000,
"description": "Document URL used to resolve relative markdown links/images; absolute http(s) only"
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 300,
"description": "Filename to use in markdown asset: references, e.g. diagram-1.png"
},
"file_path": {
"type": "string",
"maxLength": 4096,
"description": "Local path to the image file to copy into this Rabbithole"
}
},
"required": [
"name",
"file_path"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Local image files to attach to this hole; reference them in markdown as asset:name.png images"
},
"partial": {
"type": "boolean",
"description": "true = stream this chunk into the pending answer and return immediately; omit/false = finish the answer and block for the next event"
}
},
"required": [
"session_id",
"request_id",
"content"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
} | — | — · — | — |
list_rabbitholesList saved Rabbitholes (most recently updated first) so you can resume one by hole_id via open_rabbithole. Returns id, title, last-updated time, and node count for each.Input schema{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {}
} | — | — · — | — |
open_rabbitholeOpen a document on an infinite canvas so the human can read it and dive down rabbit holes. Start a NEW hole with { title, content } (or { title, file_path }), or RESUME a saved one with { hole_id } (use list_rabbitholes to find it). When opening content fetched from a URL or repo, pass the document's own URL as base_url so relative images and links resolve. For local images that are not on the web, pass assets and reference them as . For a local PDF, pass its path directly as file_path; Rabbithole extracts text and opens native JPEG pages automatically. For arXiv, prefer the HTML version with base_url when available. The canvas opens in the browser and this call BLOCKS until the human acts. It returns status='branch_request' when the human selects text and asks a question — answer it with answer_branch. A branch_request with EMPTY selected_text is a follow-up question about the parent document as a whole (a chat reply beneath it) — answer conversationally in that document's context. A branch_request may carry a 'lens' (explain | eli5 | example | deeper) — the question text spells out the style the human tapped; honor it. One marked saved=true was asked while no agent was listening — answer it like any other. When region.image_path is present, it is either this selection's clip or the immediate parent's clip; read that image before answering and trust it over extracted text for math, tables, and figures. A convert_request asks you to transcribe the listed page image_path files under its inline rules; stream the document through answer_branch with that request_id. On a resumed hole the first branch_request carries a 'rehydration' field with the whole tree (and any saved_asks); read it to reload your context. Long waits periodically return status='keep_listening' with hole_id; immediately call open_rabbithole { hole_id } to keep listening, and do not re-send content. If the host reports a tool timeout (e.g. timed out awaiting tools/call), also re-call open_rabbithole { hole_id }; nothing is lost and asks are saved. It returns status='session_closed' when the human clicks Done or closes the tab.Input schema{
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 2000,
"description": "Document title (required for a new hole)"
},
"content": {
"type": "string",
"maxLength": 10485760,
"description": "Raw markdown for the starting document"
},
"file_path": {
"type": "string",
"maxLength": 4096,
"description": "Path to a markdown or PDF file (PDF title is optional)"
},
"base_url": {
"type": "string",
"maxLength": 2000,
"description": "Document URL used to resolve relative markdown links/images; absolute http(s) only"
},
"assets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 300,
"description": "Filename to use in markdown asset: references, e.g. diagram-1.png"
},
"file_path": {
"type": "string",
"maxLength": 4096,
"description": "Local path to the image file to copy into this Rabbithole"
}
},
"required": [
"name",
"file_path"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Local image files to attach to this hole; reference them in markdown as asset:name.png images"
},
"hole_id": {
"type": "string",
"maxLength": 200,
"description": "Resume a saved hole instead of starting a new one"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
} | — | — · — | — |