Skip to main content
Glama
qingchejun

mindlm-mcp

by qingchejun
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mindlm-mcp

Turn text, web pages and PDFs into interactive mind maps — an MCP server and a command-line tool, with no API key required.

npx -y mindlm-mcp demo

That renders a built-in example and opens it. One HTML file, no build step, no account, no key.

  • Three inputs. Plain text or Markdown, an http(s) page, or a local PDF.

  • Two outputs. A Markdown outline you can edit, and a standalone HTML mind map (markmap) that works offline — every script is inlined.

  • Zero keys. Over MCP the server hands your own model a draft plus the cleaned source text and lets it write the final outline. Set your own API key only if you want the server to call a model itself. See How the outline gets written.

Docs and a live demo: https://qingchejun.github.io/mindlm-io/ · Source: https://github.com/qingchejun/mindlm-io

Quick start

Every client runs the same command — npx -y mindlm-mcp serve — and needs no environment variables. MINDMAP_OUTPUT_DIR below is optional; it just decides where exported files land.

Claude Code

claude mcp add mindlm -- npx -y mindlm-mcp serve

Scope it to one project with --scope project, and pass environment variables with -e:

claude mcp add mindlm -e MINDMAP_OUTPUT_DIR=~/Documents/mindmaps -- npx -y mindlm-mcp serve

Check it with claude mcp list, or /mcp inside a session.

Claude Desktop

Add this to claude_desktop_config.json, then restart the app:

{
  "mcpServers": {
    "mindlm": {
      "command": "npx",
      "args": ["-y", "mindlm-mcp", "serve"],
      "env": {
        "MINDMAP_OUTPUT_DIR": "~/Documents/mindmaps"
      }
    }
  }
}

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

The same block goes in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "mindlm": {
      "command": "npx",
      "args": ["-y", "mindlm-mcp", "serve"]
    }
  }
}

Ready-to-copy versions of all three live in examples/configs/.

Then ask for a mind map in plain language — "make a mind map of this PDF", "map out https://example.com/article" — and the client picks the right tool.

Related MCP server: gobbler-mcp

Tools

Four tools, always advertised in this order. The three *_to_mindmap tools return a Markdown outline; export_mindmap turns an outline into an HTML file. Every result carries both a readable text block and structuredContent.

text_to_mindmap

Outline text or Markdown you already have — a draft, notes, a transcript, a pasted chapter.

Field

Type

Notes

text

string, required

The content to map. Capped by MINDMAP_MAX_INPUT_CHARS.

mode

auto | client | llm | heuristic

Default auto.

title

string

Root node title. Derived from the source if omitted.

maxDepth

int 2–6

Levels including the root. Default 4.

maxChildren

int 3–15

Children kept per node. Default 8.

language

string

e.g. "English", "中文". Defaults to the source language.

export

boolean

Also render an HTML file and return its path.

outputPath

string

Where that file goes.

Input:

{
  "text": "# Tides\n\nSpring tides are the largest of the month.\n\n## Neap\n\nNeap tides are the smallest.\n"
}

structuredContent (default auto mode with no API key, i.e. client mode):

{
  "title": "Tides",
  "markdown": "# Tides\n\n## Spring tides are the largest of the month.\n\n### Neap\n- Neap tides are the smallest.\n",
  "mode": "client",
  "stats": { "inputChars": 79, "nodes": 4, "depth": 4, "truncated": false },
  "sourceText": "# Tides\n\nSpring tides are the largest of the month.\n\n## Neap\n\nNeap tides are the smallest.",
  "instructions": "This is a DRAFT outline produced by a rule-based algorithm. …"
}

With "mode": "heuristic" (or when an API key makes it "llm") the result is the same minus sourceText and instructions — the outline is final and ready to export.

url_to_mindmap

Fetch a page and outline its main content. Article text is extracted with Readability; navigation, footers and boilerplate are dropped. Page furniture goes too: reference markers ([1]), "[edit]" links, notes above the article, image captions, navigation boxes, and the trailing See also / References / Notes / Further reading / External links / Bibliography sections, which are link lists rather than content. A URL that serves a PDF is handed to the PDF pipeline automatically.

Field

Type

Notes

url

string, required

http(s) only. Private and loopback addresses are refused.

…

plus every option from text_to_mindmap

Input:

{ "url": "https://example.com/tide-tables", "mode": "heuristic" }

structuredContent adds a source block describing where the text came from:

{
  "title": "Tide tables",
  "markdown": "# Tide tables\n\n## Spring tides …\n\n## Neap tides …\n",
  "mode": "heuristic",
  "stats": { "inputChars": 1042, "nodes": 9, "depth": 3, "truncated": false },
  "source": {
    "url": "https://example.com/tide-tables",
    "finalUrl": "https://example.com/tide-tables",
    "title": "Tide tables",
    "siteName": "Example",
    "fetchedAt": "2026-09-27T10:21:04.512Z",
    "contentType": "text/html"
  }
}

pdf_to_mindmap

Read a local PDF, using its bookmarks as the skeleton when it has them. A PDF stores positioned lines rather than paragraphs, so the soft-wrapped lines of one paragraph are rejoined before sentences are split — otherwise a browser's "print to PDF" would yield nodes like "releases oxygen." instead of whole sentences.

Field

Type

Notes

path

string, required

Path to a local PDF. ~ is expanded.

pages

string

1-based selection: "1-20", "3", "1-5,9". All pages by default.

…

plus every option from text_to_mindmap

Input:

{ "path": "~/papers/attention.pdf", "pages": "1-12", "mode": "heuristic" }

structuredContent:

{
  "title": "mindlm-mcp PDF fixture",
  "markdown": "# mindlm-mcp PDF fixture\n\n## 1. Introduction\n\n### Mind maps turn a wall of prose into something you can scan…\n",
  "mode": "heuristic",
  "stats": { "inputChars": 769, "nodes": 12, "depth": 4, "truncated": false },
  "source": { "path": "/home/you/papers/attention.pdf", "totalPages": 3, "hasOutline": true }
}

export_mindmap

Render a Markdown outline into a standalone HTML mind map. Call this after you (or your model) have written the outline. It will not overwrite an existing file unless you ask.

Field

Type

Notes

markdown

string, required

One # root, then ##/### and - bullets.

title

string

Page title. Defaults to the outline root.

outputPath

string

File, or a directory to generate a name in.

offline

boolean

Inline every script. Default true.

toolbar

boolean

Zoom / fit / expand toolbar. Default true.

initialExpandLevel

int −1–6

Levels expanded on open; -1 expands everything.

colorFreezeLevel

int 0–6

Stop changing branch colour below this level.

maxWidth

int 0–2000

Maximum node width in pixels; 0 is unlimited.

overwrite

boolean

Replace the file if it exists. Default false.

returnHtml

boolean

Include the whole document in the result. Default false.

branding

boolean

Add a small "Made with mindlm-mcp" footer link. Default false.

Input:

{
  "markdown": "# Tides\n\n## Spring\n\n- Sun and moon in line\n\n## Neap\n\n- At right angles\n"
}

structuredContent:

{
  "path": "/home/you/mindmaps/tides-20260927-183322.html",
  "fileUrl": "file:///home/you/mindmaps/tides-20260927-183322.html",
  "bytes": 344349,
  "nodes": 5,
  "offline": true
}

Prompt

The server also exposes one prompt, mindmap_outline, which returns the outline rules (optionally in a given language) followed by an instruction to call export_mindmap.

Command line

The same pipeline without a client. With no arguments and no terminal attached, mindlm-mcp starts the MCP server — which is what an MCP client wants.

mindlm-mcp demo                                   # render a built-in example and open it
mindlm-mcp text notes.md -o notes.html            # a file, or "-" to read stdin
mindlm-mcp url https://example.com/article --open
mindlm-mcp pdf paper.pdf --pages 1-20
mindlm-mcp export outline.md -o map.html          # an outline you wrote yourself
mindlm-mcp serve                                  # MCP server on stdio
mindlm-mcp doctor                                 # runtime, LLM config, output directory

Command

What it does

serve

Start the MCP server on stdio.

demo

Render the built-in example (--no-open to skip the browser).

text <file>

Outline a .txt/.md file, or - for stdin.

url <url>

Fetch a page and outline its main content.

pdf <file>

Outline a local PDF.

export <outline>

Render an existing Markdown outline.

doctor

Report what is configured and where files will be written.

Options on the conversion commands:

Option

Meaning

-o, --output <path>

Write here. A .md path writes the outline, .html the mind map.

--title <title>

Root node title and page title.

--md

Print the Markdown outline to stdout.

--mode <auto|llm|heuristic>

How the outline is written.

--depth <n> / --max-children <n>

Shape of the tree.

--lang <language>

Language for the node labels.

--provider <anthropic|openai> / --model <name>

Override the LLM configuration.

--no-offline

Link CDN assets instead of inlining them.

--no-toolbar

Hide the mind map toolbar.

--open

Open the result in a browser.

--overwrite

Replace the output file if it exists.

--branding

Add the "Made with mindlm-mcp" footer link.

-q, --quiet

Only print results, no progress.

--env-file <path>

Load environment variables from a file first.

Results a script might consume (a file path, an outline) go to stdout; progress and diagnostics go to stderr. Exit codes: 0 ok, 1 usage error, 2 input error, 3 LLM error.

There is also a small programmatic API — textToOutline, urlToOutline, pdfToOutline, renderMindmapHtml, exportMindmap — exported from the package root.

How the outline gets written

Deciding what belongs in the tree is the hard part, and there are three ways to do it. You never have to supply a key for any of this to work.

Mode

When it is used

What happens

client

MCP default with no key

The server returns a rule-based draft, the cleaned source text and instructions. Your client's model — the one you are already talking to — rewrites the outline and calls export_mindmap. Nothing leaves your machine except what the client already sees.

heuristic

CLI default with no key

Rules only, no network: headings become branches, ranked sentences become leaves. Fast, deterministic, offline.

llm

Whenever ANTHROPIC_API_KEY or OPENAI_API_KEY is set

The server calls that model itself, over plain fetch, using your key and your endpoint. Falls back to the heuristic draft if the call fails.

mode: "auto" (the default everywhere) picks the row that applies. You can always force one with mode over MCP or --mode on the CLI. Run mindlm-mcp doctor to see which one auto resolves to right now.

There is no hosted service behind any of this: no telemetry, no update check, no call home.

Configuration

Every variable is optional. Copy .env.example to .env and pass it explicitly with --env-file .env — nothing is loaded automatically — or set the variables in your MCP client's env block.

Variable

Default

Meaning

MINDMAP_OUTPUT_DIR

./mindmaps

Where exported HTML files go. ~ is expanded.

MINDMAP_LLM_PROVIDER

auto-detected

anthropic or openai. Inferred from whichever key is set.

ANTHROPIC_API_KEY

—

Switches auto to llm mode.

OPENAI_API_KEY

—

Same, for any OpenAI-compatible endpoint.

OPENAI_BASE_URL

https://api.openai.com/v1

The endpoint used with OPENAI_API_KEY.

MINDMAP_LLM_MODEL

claude-sonnet-5 for Anthropic

Model name. Required for OpenAI-compatible endpoints, where no name is portable.

MINDMAP_ALLOW_PRIVATE_HOSTS

false

Let url_to_mindmap reach localhost and private networks.

MINDMAP_MAX_INPUT_CHARS

200000

Hard cap on characters read from any one input.

MINDMAP_CLIENT_MAX_CHARS

60000

Cap on the source text returned in client mode.

The exported HTML

One file, openable with a double click. By default every script and stylesheet — d3, markmap-view, the toolbar — is inlined, so the map keeps working with no network, on a locked-down machine, or five years from now when a CDN has moved on. That costs about 340 KB per file; pass offline: false (--no-offline) if you would rather link the CDN copies.

The KaTeX and highlight.js markmap plugins are deliberately disabled: both pull stylesheets from a CDN, which would quietly break an "offline" export. Raw HTML in the outline is not rendered (markdown-it runs with html: false), so text extracted from a hostile page cannot inject script into the file you open.

Exports carry no attribution by default. --branding / branding: true adds one small footer line if you want it.

Limitations

  • JavaScript-only pages. url_to_mindmap reads the HTML the server sends. A single-page app that renders its content client-side will come back empty or nearly so — copy the text and use text_to_mindmap instead. There is no headless browser.

  • Scanned PDFs. A PDF needs a real text layer. Scans and image-only exports are rejected with a clear error; there is no OCR.

  • Long documents are truncated, not chunked, at MINDMAP_MAX_INPUT_CHARS. Use pages on a long PDF, or map it a section at a time.

  • The heuristic is a draft. It ranks sentences by position and term frequency. It is stable and fast, and it will sometimes pick the wrong sentence. That is exactly why client mode exists.

  • Paywalls, logins and robots. The fetcher sends no cookies and does not log in.

Security

  • SSRF guard. url_to_mindmap resolves the host first and refuses loopback, private, link-local (including the 169.254.169.254 cloud metadata address), CGNAT and multicast ranges unless you set MINDMAP_ALLOW_PRIVATE_HOSTS=true. Only http: and https: are accepted.

  • Limits. 5 MB per fetched response, a 15 s timeout, at most 5 redirects, 50 MB / 300 pages per PDF, and a character cap on every input.

  • No telemetry, no update check, no hosted backend. The only network calls are the URL you ask for and — if you configured a key — your own LLM endpoint.

  • No raw HTML in exports, and inlined JSON has </script> escaped.

  • Reporting a vulnerability, and the known DNS-rebinding caveat: SECURITY.md.

Launch materials and directory listings

This section is a placeholder owned by the outreach lead. Announcement copy, awesome-list entries and MCP directory submissions (mcp.so, Glama, Smithery, PulseMCP, the official MCP Registry) are tracked in docs/launch.md and are intentionally empty here.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md. Requires Node ≥ 22.12.

npm ci && npm run lint && npm run typecheck && npm test && npm run build

Want a full editor?

mindlm-mcp is deliberately small: outline in, one HTML file out. If you want to keep editing the map afterwards — drag nodes around, restyle branches, collaborate, keep a library of maps — that is what mindlm.io is for. This package works completely on its own and never talks to it.

License

MIT © 2026 青澈君

Available Tools

4 tools
export_mindmapExport a mind mapA

Render a Markdown outline into a standalone HTML mind map — interactive, single file, no network needed. Call this after you have written or refined an outline. Returns the file path; it does not overwrite an existing file unless you ask it to.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleNoPage title. Defaults to the outline root.
offlineNoInline every script so the file works with no network (default true).
toolbarNoShow the zoom / fit / expand toolbar (default true).
brandingNoAdd a small "Made with mindlm-mcp" footer link (default false).
markdownYesThe Markdown outline to render: one "# " root, "##"/"###", then "-" bullets.
maxWidthNoMaximum node width in pixels; 0 means unlimited.
overwriteNoReplace the file if it already exists (default false).
outputPathNoOutput file or directory. Defaults to $MINDMAP_OUTPUT_DIR or ./mindmaps/.
returnHtmlNoInclude the full HTML in the result. Only useful for small maps (default false).
colorFreezeLevelNoStop changing branch colour below this level.
initialExpandLevelNoLevels expanded on open; -1 expands everything.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=false, destructiveHint=false and openWorldHint=false; the description corroborates this by stating it writes a file, returns the path, does not overwrite by default, and needs no network. That overwrite-safety and offline detail is genuine added context beyond the annotations, though permissions and error behavior are unmentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero padding: capability, output form, then invocation timing and the overwrite caveat. The most important constraint (no accidental overwrite) is placed where it is read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter writer with no output schema, the description covers the return value ('Returns the file path'), the non-destructive default, and the offline guarantee, so an agent can call it safely. Missing only the default output location, which the outputPath schema already supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 11 parameters are already documented, and the description adds no per-parameter detail. It does reinforce the overwrite default in prose, which slightly clarifies the most consequential flag, but otherwise the schema does the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Render a Markdown outline into a standalone HTML mind map') plus the output characteristics (interactive, single file, no network). It implies the distinction from the url/pdf/text_to_mindmap siblings by framing itself as the step after an outline already exists, but never names or contrasts them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Call this after you have written or refined an outline' gives a clear triggering condition for the tool, which is the key decision point given the conversion-oriented siblings. It stops short of naming an alternative or stating when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

pdf_to_mindmapPDF to mind mapA
Read-only

Read a local PDF and turn it into a mind-map outline, using its bookmarks as the skeleton when it has them. Scanned PDFs with no text layer are rejected — there is no OCR. Use pages to limit long documents.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoauto (default): use a configured API key if there is one, otherwise "client". client: get a draft plus the source text back and write the outline yourself. llm: the server calls the model configured by ANTHROPIC_API_KEY / OPENAI_API_KEY. heuristic: rule-based only, no model.
pathYesPath to a local PDF file. "~" is expanded.
pagesNoPage selection, 1-based, e.g. "1-20", "3" or "1-5,9". All pages by default.
titleNoRoot node title. Derived from the source if omitted.
exportNoAlso render the outline to a standalone HTML file and return its path.
languageNoLanguage for the node labels, e.g. "English" or "中文". Defaults to the source language.
maxDepthNoLevels including the root (default 4).
outputPathNoWhere to write the HTML when export is true. A directory gets a generated file name. Defaults to $MINDMAP_OUTPUT_DIR or ./mindmaps/.
maxChildrenNoChildren kept per node before the rest collapse into "…(+N)" (default 8).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: the no-OCR limitation and the bookmark-skeleton heuristic are things an agent cannot infer from the schema. It stays quiet on cost/latency of the LLM modes and on failure modes for malformed PDFs, so not quite a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, zero filler, with the core transform stated first and constraints (bookmarks, no OCR, pages) following. Nothing to cut.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter read tool with no output schema, the description covers purpose, source limitations, and scoping. It never hints at the shape of the produced outline (especially the draft-plus-source-text behavior in client mode), but that gap is largely filled by the mode parameter's own schema text.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains mode, pages, export, title and the rest. The description only echoes the 'pages' parameter with the long-document hint, adding little beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('Read a local PDF and turn it into a mind-map outline') plus the exact resource and behavior. It is instantly distinguishable from the siblings url_to_mindmap and text_to_mindmap, which take a different input source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete conditions: bookmarks are used as the skeleton when present, scanned PDFs without a text layer are rejected, and 'pages' should be used for long documents. It lacks an explicit 'use this instead of url_to_mindmap when...' routing sentence, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

text_to_mindmapText to mind mapA
Read-only

Turn text or Markdown into a mind-map outline. Use this for content you already have — a draft, notes, a transcript, a chunk of a document. Returns a Markdown outline; pass export: true, or call export_mindmap afterwards, to get an HTML file.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoauto (default): use a configured API key if there is one, otherwise "client". client: get a draft plus the source text back and write the outline yourself. llm: the server calls the model configured by ANTHROPIC_API_KEY / OPENAI_API_KEY. heuristic: rule-based only, no model.
textYesThe text or Markdown to map. Capped by MINDMAP_MAX_INPUT_CHARS (200k by default).
titleNoRoot node title. Derived from the source if omitted.
exportNoAlso render the outline to a standalone HTML file and return its path.
languageNoLanguage for the node labels, e.g. "English" or "中文". Defaults to the source language.
maxDepthNoLevels including the root (default 4).
outputPathNoWhere to write the HTML when export is true. A directory gets a generated file name. Defaults to $MINDMAP_OUTPUT_DIR or ./mindmaps/.
maxChildrenNoChildren kept per node before the rest collapse into "…(+N)" (default 8).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered; the description adds the return type ('Markdown outline') and the export side-effect path, which is the key behavioral fact. One minor tension: export writes an HTML file to disk while readOnlyHint=true, but that is a local artifact rather than remote state mutation, so it is not a real contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero filler, with the operation stated first and the export/escalation path last. Every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description correctly fills that gap by naming the return format and the HTML alternative. Combined with a fully documented 8-parameter schema, an agent has enough to call it, though the internal shape of the outline is left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents mode, text, title, export, language, maxDepth, outputPath and maxChildren in detail. The description only restates the export flag and never adds syntax or defaults beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Turn text or Markdown into a mind-map outline') and immediately scopes the input type ('content you already have') which implicitly separates it from url_to_mindmap and pdf_to_mindmap. An agent can pick this tool without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete input examples (draft, notes, transcript, document chunk) and explicitly routes the export case to the sibling ('pass export: true, or call export_mindmap afterwards'). It lacks an explicit when-not statement, but the 'content you already have' framing covers that implicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

url_to_mindmapURL to mind mapA
Read-only

Fetch an http(s) page (or a PDF served over http) and turn its main content into a mind-map outline. Article text is extracted with Readability; navigation and boilerplate are dropped. Pages that render entirely in JavaScript will come back empty — paste the text into text_to_mindmap instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesAn http(s) page or PDF. Server-rendered pages only — a JS-only SPA will come back empty.
modeNoauto (default): use a configured API key if there is one, otherwise "client". client: get a draft plus the source text back and write the outline yourself. llm: the server calls the model configured by ANTHROPIC_API_KEY / OPENAI_API_KEY. heuristic: rule-based only, no model.
titleNoRoot node title. Derived from the source if omitted.
exportNoAlso render the outline to a standalone HTML file and return its path.
languageNoLanguage for the node labels, e.g. "English" or "中文". Defaults to the source language.
maxDepthNoLevels including the root (default 4).
outputPathNoWhere to write the HTML when export is true. A directory gets a generated file name. Defaults to $MINDMAP_OUTPUT_DIR or ./mindmaps/.
maxChildrenNoChildren kept per node before the rest collapse into "…(+N)" (default 8).

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint, but the description adds real behavioral context the annotations cannot: Readability extraction, dropping of navigation/boilerplate, and the hard failure mode of empty results on JS-rendered pages. It does not note network/auth constraints for fetching, but the failure-mode disclosure is the valuable part.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action, then extraction detail, then the failure mode and fallback. No filler; each sentence carries a distinct fact.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does tell the agent what comes back (a mind-map outline, plus source text in client mode). Given eight parameters fully documented in the schema and annotations covering the safety profile, this is nearly complete; only the PDF-vs-pdf_to_mindmap overlap is left ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and each parameter already carries its own enum explanation, default, and range. The description adds nothing parameter-specific beyond what the schema states. Baseline 3 is appropriate when the schema does all the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: fetch an http(s) page/PDF and convert its main content into a mind-map outline. It names Readability as the extraction mechanism, which tells the agent exactly what content is used. It does not, however, clarify its boundary against the pdf_to_mindmap sibling, despite explicitly advertising PDF support.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit exclusion and a named alternative: JS-only pages will come back empty, so use text_to_mindmap instead. That is exactly the kind of routing guidance an agent needs. It does not mention when to prefer pdf_to_mindmap or export_mindmap, so the routing is partial rather than complete.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedexport_mindmap
    • First observedpdf_to_mindmap
    • First observedtext_to_mindmap
    • First observedurl_to_mindmap
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool maps to a clearly distinct input source (raw text, URL, local PDF) plus one distinct output operation (HTML export). The only mild overlap is url_to_mindmap also accepting remotely-served PDFs, but the descriptions explicitly differentiate remote vs. local handling.

Naming Consistency4/5

Three tools share a clean {source}_to_mindmap pattern (text/url/pdf), and all four share the 'mindmap' suffix, making the set cohesive. export_mindmap deviates by using a verb_noun form rather than the source_to pattern, a minor inconsistency.

Tool Count4/5

Four tools is compact and each earns its place: three input adapters and one exporter form a coherent pipeline. It leans slightly thin—no redundancy, but little room for edge operations—so not quite ideal.

Completeness4/5

The surface covers the core lifecycle: acquire content from text/URL/PDF, produce an outline, and render standalone HTML. Gaps are minor—no import of an existing outline file and no alternative export formats (PNG/SVG/OPML)—but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers