Provides tools for reading, creating, and editing mind maps stored in a GitHub repository (mindspark-maps), using GitHub's Contents API for storage and synchronization.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mindspark-mcp list my mind maps"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for MindSpark. Lets Claude or ChatGPT read, create, and edit your mind maps directly — either the same mindspark-maps GitHub repo the web app itself reads and writes, or, if you self-host MindSpark, that server's own database directly, with no GitHub account involved at all.
Two ways to run it: as a local process (Claude Desktop, Claude Code, any stdio-based MCP client), or over HTTP (ChatGPT, or any client that needs a network-reachable server). Same tools either way — just a different transport, and a choice of where the data actually lives (see below).
|
| |
Data lives in | your | your self-hosted MindSpark server's own SQLite database |
Setup | a GitHub personal access token (below) | a URL — no account or token needed |
Works with | MindSpark cloud mode (static/GitHub-backed) or self-hosted | MindSpark self-hosted mode ( |
They're mutually exclusive — set one or the other. If you're self-hosting MindSpark (node server.js), you almost certainly want MINDSPARK_SELF_HOSTED_URL: it points this server at the same REST API (/api/maps) your self-hosted MindSpark already exposes, so a map created here shows up in the app immediately, with nothing synced through GitHub. See Option C below. The rest of this README (steps 1–2, Options A/B) covers the original GitHub-backed mode.
Related MCP server: GitHub MCP Server
list_maps — list your maps (title, id, last updated)
get_map — read a map as an indented outline
render_map — show a map as an actual visual diagram, inline in the conversation (see below) — ask to "see" or "visualize" a map rather than just read it
create_map — create a new map from a Markdown outline. This is the main way to use it: just write an outline the way you normally would (headings and/or nested bullets, bold, italic, code), and it becomes a fully structured mind map. No need to describe nodes one at a time.
add_node / update_node — add or edit nodes, including MindSpark's bulleted/numbered list style (listType: 'ul'|'ol') and task checkboxes (task: 'todo'|'doing'|'done'), and pick from MindSpark's own light node-color palette (peach, cream, mint, teal, lavender, pink, beige) or any custom hex color
delete_node — delete a node and its subtree
delete_map — delete a map entirely
Every write goes through the same GitHub Contents API calls, the same _index.json / _deleted.json bookkeeping, and the same optimistic-concurrency (sha-based) handling as the web app's own storage layer — a map created here opens normally in MindSpark, and edits made in the app while this server is also active can't be clobbered by it (writes merge rather than overwrite).
A map created via create_map also sets a one-shot _import flag matching what MindSpark's own import flow sets — this is a real bug fix, not a nicety: a freshly created map has no x/y on its nodes, and app.js's loadMap() only runs autoLayout() (computing real, non-overlapping positions) automatically when this flag is present. Without it, opening a freshly created map in the app would show every node stacked on top of each other. Confirmed by reading app.js's actual load path, not assumed.
render_map)render_map returns an actual rendered diagram — matching MindSpark's own look, not a generic tree: root centered with branches balanced left and right (the same radial layout app.js's own balanceRootSides() produces for a fresh view, including the exact same contiguous-half-split rule), the same default color palette and root-accent-color behavior, the same rule that custom node colors always pair with dark text, the same curved connector shape, the root's distinct bolder serif styling versus regular nodes' sans-serif, and the same 18px circular +/− fold toggle on any node with children, styled to match app.js's .h-collapse exactly. Confirmed working live in ChatGPT (both browser and mobile), after two rounds of fixes based on that live testing.
Word wrap, bullets, and task checkboxes all match the app's own conventions, checked directly against app.js/styles.css rather than approximated: long node text wraps across multiple lines (the node grows taller to fit, and the layout re-flows so nothing overlaps) instead of just truncating with an ellipsis; listType: 'ul'/'ol' nodes show a bulleted or numbered line per item, matching app.js's renderNodeText(); task nodes show the same three-state checkbox app.js uses (todo empty, doing amber half-circle, done green checkmark with the node text struck through and faded), matching .task-check and .task-done .node-text exactly. No real font metrics are available outside a browser, so wrapping uses an approximate character count per line rather than a measured pixel width — close, not pixel-perfect.
Large maps default to showing just the center node and its immediate children, with everything deeper collapsed until you click to expand a branch — so opening a big map doesn't dump an overwhelming wall of nodes on you. This is additive with the map's own saved fold state (anything the real app already has collapsed stays collapsed), not a replacement for it.
Fold/unfold, not editing. Clicking a node's toggle expands or collapses that branch — collapsing genuinely removes its descendants from the layout (not just visually hiding them), matching how collapsing works in the app itself. This state is local to the widget session and never written back to GitHub; the widget opens matching whatever fold state the real map currently has (respecting each node's own collapsed flag) plus the depth default above, and diverges from there as you click around, but MindSpark's own copy is never touched. This is deliberately a read-only view — for edits, use add_node/update_node/delete_node, or the link below to open the real app.
"Open in MindSpark" appears at the bottom of every rendered map, linking to that map in your actual MindSpark app when MINDSPARK_APP_URL is configured (see the environment variable table above) — the natural handoff point from "look at this" to "now edit it directly." This is a universally-viewable read-only link (the same #view= encoding MindSpark's own "Copy share link" feature uses — the whole map travels in the URL itself, nothing server-side to look up), not a link that only resolves for whoever's GitHub account the map happens to live in — so it works for anyone it gets shared with, not just its owner. Opening it shows MindSpark's own read-only shared view, with a "Make an editable copy" button already built into the app for saving it into their account if they want to.
Worth knowing: the layout and rendering logic (turning a node tree into SVG, word-wrap, the fold/collapse math, escaping text safely, matching MindSpark's exact styling) is thoroughly tested — test/widget-layout.mjs, test/widget-text-layout.mjs, test/widget-render.mjs, test/widget-interactivity.mjs (real simulated clicks against a real DOM, not just structural checks) — including strict XML well-formedness validation, which has caught several real bugs (an unescaped attribute quote, two separate instances of a duplicate class attribute, and a missing module in the widget's own build step) that more lenient HTML-style parsing missed entirely. The host-facing bridge (the handshake that gets map data into the iframe) is the one part that's only verifiable by actually using it in ChatGPT or Claude Desktop, which is exactly what surfaced and fixed the two earlier issues.
If the widget doesn't render, it shows its own diagnostics directly in the chat as an ongoing "still waiting" status rather than sitting silently forever: after about 5 seconds with nothing received, it displays what it actually tried (whether window.openai was present, how many messages arrived from the host, whether the handshake timed out). A screenshot of that panel is far more useful for tracking down a new issue than "it's not rendering."
A note on the "Widget CSP / domain not set" warning ChatGPT's connector screen shows in Developer Mode: this widget makes zero external network calls (everything — layout, rendering, styling — is inlined in one self-contained HTML resource) other than optionally allowing navigation to your own configured MINDSPARK_APP_URL for the "Open in MindSpark" link, so its CSP is otherwise the most restrictive one possible. That's set directly on the widget resource. This warning specifically gates public app submission, not Developer Mode testing — you can use the widget as-is; it only becomes relevant if you ever submit this for listing in ChatGPT's app directory.
Node.js 18 or later
Self-hosted mode (MINDSPARK_SELF_HOSTED_URL): just a running self-hosted MindSpark server — skip straight to Option C.
GitHub mode (MINDSPARK_GH_TOKEN, steps 1–2 below): a GitHub account with (or willing to have) a mindspark-maps repo — the same one the MindSpark web app uses when you sign in with GitHub. If you've never signed into MindSpark's cloud mode, the server creates this repo (private) on first use.
(Skip this and step 2 if you're using self-hosted mode — go straight to Option C.)
First, check whether you already have a mindspark-maps repository under your GitHub account (you would if you've ever signed into MindSpark's cloud mode). This determines which setup is simpler.
mindspark-maps already existsCreate a fine-grained personal access token:
GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
Repository access: "Only select repositories" → mindspark-maps
Permissions → Repository permissions → Contents: Read and write
Generate, copy the token (starts with github_pat_)
That's it — no other permissions needed.
The simplest and most secure option is to create the repository yourself first, then scope a token to just that one repo:
Go to github.com/new, create a repository named exactly mindspark-maps — private, otherwise empty (don't add a README)
Follow the steps above ("if it already exists") now that it does
This is where it's easy to get a confusing permissions error, so it's worth calling out specifically: creating a new repository requires a separate permission from the one that reads and writes files inside it. "Contents: Read and write" is not enough on its own.
Fine-grained tokens → Generate new token
Repository access: "All repositories" (a repo that doesn't exist yet can't be individually selected)
Permissions → Repository permissions → Contents: Read and write and Administration: Read and write (this second one is specifically "repository creation, deletion, settings, teams, and collaborators" — easy to miss, since nothing about creating a repo obviously sounds like "administration")
Generate, copy the token
Once the repo exists, you can generate a narrower, single-repo token to replace this one if you'd rather not keep a broadly-scoped token around.
A classic token with the repo scope also works for either case, if you prefer — it doesn't have this Contents/Administration split, at the cost of being broader (access to every repo you can access, not just this one).
cd mcp-server
npm installAdd to your MCP config (claude_desktop_config.json, or via claude mcp add for Claude Code):
{
"mcpServers": {
"mindspark": {
"command": "node",
"args": ["/absolute/path/to/mindspark/mcp-server/src/server.js"],
"env": {
"MINDSPARK_GH_TOKEN": "github_pat_..."
}
}
}
}Restart Claude Desktop (or reload MCP servers in Claude Code) after saving.
This runs the same server over HTTP instead of as a local subprocess, since ChatGPT can't spawn a process on your machine — it needs a URL it can reach.
This is a single-user setup: the token still comes from one environment variable, same as Option A. Anyone who has the tunnel URL while it's running can call every tool as you. Fine for trying it out yourself; don't share the URL, and stop the tunnel when you're done.
Start the server:
MINDSPARK_GH_TOKEN=github_pat_... npm run start:httpBy default it listens on http://localhost:3300/mcp (override with PORT).
Expose it publicly with a tunnel, e.g. ngrok:
ngrok http 3300Note the https://....ngrok.app URL it gives you.
In ChatGPT: Settings → Apps → Advanced Settings → turn on Developer mode (requires Plus, Pro, Business, Enterprise, or Edu). Then Settings → Apps → Create, and point it at https://<your-ngrok-url>/mcp.
Start a new chat, add the connector from the + menu, and try:
Create a MindSpark map planning a birthday party, with sections for guest list, food, and decorations.
Every tool call re-authenticates against GitHub with the same token as the local version — nothing about the data path changes, only how ChatGPT reaches the server. Each client connection gets its own session (a fresh handshake creates a new one); idle sessions are cleaned up automatically after 30 minutes.
If you're running MindSpark yourself (node server.js — see the main MindSpark README), point this server at it directly instead of using a GitHub token:
{
"mcpServers": {
"mindspark": {
"command": "node",
"args": ["/absolute/path/to/mindspark-mcp/src/server.js"],
"env": {
"MINDSPARK_SELF_HOSTED_URL": "http://localhost:3000"
}
}
}
}Or over HTTP, the same way as Option B:
MINDSPARK_SELF_HOSTED_URL=http://localhost:3000 npm run start:httpNo GitHub account, repo, or token involved — reads and writes go straight to your MindSpark server's /api/maps REST API, so a map created here appears in the app immediately (and vice versa). This is the natural pairing for a self-hosted MindSpark instance that isn't on localhost (e.g. reachable over a private network/VPN): set MINDSPARK_SELF_HOSTED_URL to wherever it's actually reachable from, and see MINDSPARK_MCP_TOKEN below if you're running the HTTP transport somewhere more than just your own machine can reach.
Variable | Required | Default | Purpose |
| One of this or | — | GitHub token, see step 1. Mutually exclusive with |
| No |
| Repo name, if you use something other than the default. Only used with |
| One of this or | — | Base URL of a self-hosted MindSpark server (e.g. |
| No | — | The URL where your MindSpark app is hosted (e.g. |
| No | — (unset = open) | HTTP transport only. When set, every request to |
| No (HTTP only) |
| Port for the HTTP server |
Once connected, in Claude:
Create a MindSpark map planning a birthday party, with sections for guest list, food, and decorations.
Claude writes the outline and calls create_map — the map appears in your MindSpark sidebar the next time you open the app (or refresh "Your maps" if it's already open).
npm install # if you haven't already
npm test # runs everything below in sequenceOr individually:
node test/widget-layout.mjs # tree layout algorithm: sibling spacing, deep chains, wide fan-outs,
# malformed input (dangling/cyclic references), variable per-node
# heights (word-wrapped content) with no overlap
node test/widget-text-layout.mjs # word-wrap, bullet/numbered list formatting, truncation with ellipsis,
# HTML/<br> normalization — all as pure, isolated functions
node test/widget-render.mjs # SVG generation: well-formed output (strict XML validation, not just
# lenient HTML-style parsing), text escaping (including hostile input),
# MindSpark's exact coloring/font/border/task-checkbox conventions
node test/widget-assembly.mjs # the tested layout/render/text-layout code actually ends up in the
# shipped widget HTML, unmodified and functional
node test/widget-interactivity.mjs # real simulated clicks against a real DOM: fold/unfold toggles,
# default collapse-beyond-depth-1 view, initial state seeded from the
# map's own collapsed flags, the "open in MindSpark" footer link
node test/share-link.test.mjs # the "#view=" share-link encoding shared with mcp-server/no-login/ —
# cross-validated against Node's independent zlib implementation, not
# just round-tripped through its own decoder, to confirm the output is
# genuinely standard gzip a real browser would decode correctly
node test/widget-integration.mjs # full round trip through the real MCP protocol: create a map, confirm
# the _import flag is set (fixes a real overlap-on-open bug), add
# listType/task nodes and confirm they survive the round trip, and
# confirm render_map's "Open in MindSpark" link is a universally-
# viewable share link (checked against app.js's own detection regex)
# rather than a login-gated deep link
node test/e2e.mjs # full protocol test (stdio-style, in-memory transport) against a mocked GitHub API
node test/edge-cases.mjs # sha-conflict retry, first-run repo creation, concurrent-write safety
node test/http-e2e.mjs # same protocol + widget tests but over real HTTP — starts the actual
# server process, connects with a real HTTP client
node test/multi-session.mjs # confirms multiple independent client sessions can each connect and
# operate without interfering with each other
node test/self-hosted-store.test.mjs # SelfHostedStore against a mocked self-hosted REST API: constructor
# validation, list/get/save/delete, save always issues a PUT (the
# self-hosted server's upsert() handles create-or-update either way)
node test/self-hosted-e2e.mjs # same full-protocol coverage as test/e2e.mjs, but backed by
# SelfHostedStore instead of GitHubStore — proves the self-hosted
# mode works through the real tool surface, not just in isolation
node test/http-auth.test.mjs # MINDSPARK_MCP_TOKEN: unauthenticated/wrong-token requests to /mcp
# are rejected (401), the correct token works, and the health check
# stays reachable either way; also confirms default (unset) behavior
# is unchanged from before this option existedAll of these run entirely offline — no real GitHub account, token, or MCP client (ChatGPT/Claude) needed. What they can't cover is noted in "The visual widget" section above — that part needs a live check.
Your token (GitHub mode) is read from an environment variable, never logged, never sent anywhere except api.github.com. Self-hosted mode has no token at all — access is whatever can reach MINDSPARK_SELF_HOSTED_URL.
Use a fine-grained token scoped to just the mindspark-maps repo where possible, not a broad classic token (GitHub mode only).
This server can create, edit, and delete maps and nodes on your behalf whenever an MCP client decides to call it — the same trust model as giving any MCP server file access. Only run it with clients and configurations you trust.
HTTP mode specifically: by default, whoever can reach the port can call every tool — there's no built-in identity check. For a tunnel (Option B) this is inherent to the tunnel-URL-as-secret model: don't post it publicly, and stop ngrok/kill the server when you're done testing. For anything longer-lived or reachable by more than just you (e.g. a self-hosted deployment on a private network), set MINDSPARK_MCP_TOKEN so every request needs Authorization: Bearer <token> — this doesn't add per-user identity (still single-shared-secret, not OAuth), just a gate against anything that merely happens to be able to route to the port. This mode overall is meant for one person/one deployment, not multi-tenant sharing — see the earlier note about what a real multi-user deployment would need instead (per-user OAuth, hosted rather than tunneled).
Add a single new node under an existing node in a map. Use get_map first to find the parent node's id.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Show a task checkbox on the node. "done" also renders the text struck through. | |
| text | Yes | Node text. Supports basic HTML tags: <b>, <i>, <u>, <s>. For multi-line content (used with listType), separate lines with <br> or \n. | |
| color | No | Optional hex color for the node. For a look that matches MindSpark's own palette, use one of its built-in light node colors: #ffe2d6 (peach), #ffedc2 (cream), #dcefce (mint), #cfe9e6 (teal), #d8e0fb (lavender), #efd9f2 (pink), #e9e2d6 (beige) — or any other hex value for a custom color. | |
| mapId | Yes | ||
| listType | No | Render the node's text as a bulleted (ul) or numbered (ol) list — each line becomes one list item. | |
| parentId | Yes | id of the node this new node should nest under |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the mutation nature is communicated. The description does not add extra behavioral details (e.g., side effects, return behavior), but that is acceptable given the annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, directly stating the action and a key prerequisite. No redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description covers the essential context: what it does and how to prepare (calling get_map first). It does not need to describe return values. Minor omission: no mention of how errors are handled, but that is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 83% of parameters with descriptions. The description adds value by explaining the color palette and listType rendering, but mapId has no description in the schema or tool description. Since coverage is high, the baseline is 3; the small extra explanation does not push it higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a single new node') and the target ('under an existing node in a map'). It distinguishes this tool from siblings like update_node and delete_node by specifying the addition operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a concrete usage tip: 'Use get_map first to find the parent node's id.' This guides the agent on a prerequisite step. It does not explicitly mention when not to use it, but the hint is sufficient for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new mind map from a Markdown outline (headings and/or nested bullets). This is the preferred way to build a map from scratch — write normal Markdown (the way you already would) rather than constructing nodes one at a time. The first line becomes the map's central topic. Supports bold, italic, and code.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Override the map title (defaults to the outline's first line) | |
| outline | Yes | Markdown outline: headings (#, ##, ###) and/or nested bullets (-, *), indented 2 spaces per level |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructive=false, so the creation behavior is expected. The description adds valuable detail that the first line becomes the central topic, which is not implicit in the annotations. It does not describe return values or side effects, but given the non-destructive nature and simple creation action, the added context is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant information. It front-loads the core action and then provides key differentiators and format details. Every sentence contributes to clarity, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the absence of an output schema, and existing annotations covering safety, the description is largely complete. It explains the purpose, input format, and central topic behavior. It does not explicitly state what the tool returns (e.g., map ID), but this is not critical for a creation tool and the context of sibling tools (like get_map) implies typical behavior. Overall, it provides enough context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptive text (outline format and title override). The description further clarifies that the outline's first line becomes the central topic and mentions Markdown formatting (bold, italic, code), which goes beyond the schema's basic syntax. This additional context enhances understanding of how to use the 'outline' parameter effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Create' as the action and 'mind map' as the resource. It clearly distinguishes itself from sibling tools like add_node and update_node by calling itself the 'preferred way' to build from scratch, avoiding the need for node-by-node construction. The mention of 'central topic' further clarifies its specific role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends this tool as the preferred method for building a map from scratch, providing clear usage direction. It contrasts with the alternative (constructing nodes one at a time) and gives format hints (Markdown, bold/italic/code), making the use case unmistakable. The lack of a direct 'when not to use' is compensated by the explicit preference statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Permanently delete an entire map. This cannot be undone through this tool (the file history remains in git, recoverable manually).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide destructiveHint, but the description adds that it cannot be undone through this tool and that file history remains in git, giving extra context about reversibility and recovery.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with the primary action front-loaded and a relevant caution following. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the key aspects: what is deleted, irreversibility, and manual recovery. No output schema, so return info is not needed. Sibling list provides additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the 'id' parameter at all. Schema coverage is 0%, and the description must compensate but fails to provide any parameter meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (delete) and the resource (map). Distinguishes from sibling tools like delete_node and create_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Warns about permanence and possible recovery, but does not explicitly mention alternatives or when to use this tool versus others. The action is obvious from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a node and its entire subtree. Cannot delete the root node — delete the whole map instead.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | ||
| nodeId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds critical behavioral details: the operation removes the entire subtree and is forbidden on the root node. This meaningfully expands on the raw annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and scope, then adds a necessary constraint and alternative. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior, the key exception, and the fallback tool, which is sufficient for a simple delete operation. It does not elaborate on parameter meanings, but the names are reasonably self-explanatory in the MindSpark context, and no output schema is expected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only names and types for mapId and nodeId, with no descriptions or titles. The description does not explain these parameters, leaving their exact meaning and format implicit. Since schema coverage is low and the description fails to compensate, parameter semantics are under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete) and the object (a node and its entire subtree), immediately distinguishing this tool from sibling tools like delete_map. The explicit note about the root node restriction further clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit when-not-to-use condition ('Cannot delete the root node') and directs the user to the alternative ('delete the whole map instead'). This gives clear guidance on when to choose this tool over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a mind map by id and render it as an indented outline, so its structure and content are readable at a glance.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The map id, from list_maps |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the behavioral detail that the output is an indented outline, going beyond the readOnlyHint annotation. It does not describe potential errors or limitations, but for a read-only fetch-and-render operation the disclosed behavior is largely sufficient and consistent with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys the action, the target resource, and the output format without any redundant or vague wording. It is well-structured and immediately comprehensible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only operation, no output schema), the description is complete. It specifies what the tool does, what it returns (an indented outline), and where the input comes from, covering all necessary context for an agent to use it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'id', has a description that clearly explains its meaning and provides a source ('from list_maps'). This fully documents the parameter within the schema itself, leaving no ambiguity about how to obtain or use the value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: fetching a mind map and rendering it as an indented outline for readability. It distinguishes the tool from list_maps (which lists maps) and implicitly from render_map by specifying the output format, making the action and result unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives such as render_map or list_maps. It lacks explicit conditions, exclusions, or contextual triggers that would help an agent choose this tool appropriately, leaving the selection largely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all of the user's mind maps, with id, title, and last-updated time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
ReadOnlyHint and openWorldHint annotations already cover safety. The description adds behavioral context by stating it returns 'all' maps, implying a complete listing, and specifies the fields returned. This goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly conveys the purpose and output without any redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what is returned and the scope (user's maps). It does not mention pagination or error cases, but for a simple list operation with no parameters, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so there is no ambiguity. The description does not contradict the schema and requires no additional explanation for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'list' and the resource 'mind maps', with explicit output fields (id, title, last-updated time). It is immediately distinct from get_map (retrieves one) and other mutating tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining all maps in the user's collection, contrasting with get_map for a single map. Explicit alternatives are not named, but the context is clear enough for an agent to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a mind map as an interactive visual diagram inline in the conversation, instead of plain text. Use this when the user asks to see, view, or visualize a map — get_map is better when you just need to read or reason about its contents.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The map id, from list_maps |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, covering safety. The description adds context about the inline visual output but does not elaborate on side effects, return format, or other behavioral aspects. Since annotations cover the safety profile, the modest additional context warrants a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that are direct and purposeful. The first sentence states the action and output, the second provides usage guidance. No superfluous words or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, read-only operation, no output schema), the description provides all necessary context: what it does, when to use it, and how it differs from a sibling tool. No missing information for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully covers the single parameter 'id' with the description 'The map id, from list_maps'. The tool description does not add any extra meaning beyond that, so the baseline of 3 applies due to 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool renders a mind map as an interactive visual diagram inline, contrasting with plain text. It also distinguishes it from get_map, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides selection criteria: 'Use this when the user asks to see, view, or visualize a map — get_map is better when you just need to read or reason about its contents.' This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change the text, color, list style, or task status of an existing node.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Show a task checkbox on the node. "done" also renders the text struck through. Pass "none" to remove the checkbox. | |
| text | No | New node text. For multi-line content (used with listType), separate lines with <br> or \n. | |
| color | No | Hex color for the node. For a look that matches MindSpark's own palette, use one of its built-in light node colors: #ffe2d6 (peach), #ffedc2 (cream), #dcefce (mint), #cfe9e6 (teal), #d8e0fb (lavender), #efd9f2 (pink), #e9e2d6 (beige) — or any other hex value for a custom color. Pass "#ffffff" to clear back to the default. | |
| mapId | Yes | ||
| nodeId | Yes | ||
| listType | No | Render the node's text as a bulleted (ul) or numbered (ol) list — each line becomes one item. Pass "none" to remove list formatting. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only (readOnlyHint: false) and not destructive (destructiveHint: false). The description confirms a mutation but adds no extra details about side effects, idempotency, or failure behavior, which the annotations don't already cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and enumerates the affected properties. It avoids redundancy and perfectly accompanies the schema without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers the core functionality for a typical update operation, and the schema provides required parameter details. It does not explain return values or error cases, but the absence of an output schema and the straightforward nature of the tool make this acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 4 of 6 parameters (text, color, listType, task) with clear meanings, leaving mapId and nodeId unexplained. The description itself does not add further semantic value beyond what the schema provides, but it does align with the listed mutable fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (change) and the resource (an existing node), explicitly listing the four modifiable attributes (text, color, list style, task status). It distinguishes this tool from siblings like add_node and delete_node by focusing on updating an existing node.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating existing nodes but does not explicitly state when to prefer this over add_node or delete_node. It lacks direct guidance on selection criteria, though the operation type is evident from the verb 'change'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0add_nodecreate_mapdelete_mapdelete_nodeget_maplist_mapsrender_mapupdate_nodeScored across 8 tools
Each tool targets a distinct resource/action pair: maps vs nodes, listing vs rendering vs creating vs deleting. get_map and render_map could overlap, but the descriptions explicitly separate outline reading from visual rendering.
All tool names follow a consistent verb_noun pattern: list_maps, get_map, render_map, create_map, add_node, update_node, delete_node, delete_map. The verbs are clear and the object is always the affected resource.
Eight tools is well-scoped for a mind map management server. Each tool covers a necessary core operation without redundancy or bloat.
The surface covers the main lifecycle: list, read, render, create, update nodes, add nodes, delete nodes, and delete maps. Minor gaps exist around reorganizing nodes (move/reorder) and updating map-level metadata, but agents can accomplish core workflows.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
Turn outlines and hierarchical notes into interactive mind maps through a hosted remote MCP server.
A MCP server built for developers enabling Git based project management with project and personal…
