xmind-mcp-smoke-test
Skill9 starsChanged 26 days agoMITView on GitHub
Release pre-validation smoke test that exercises the entire xmind-mcp MCP tool surface (all 27 tools plus error paths) against a throwaway scratch .xmind file, verifying every write by reading it back through the tools. Use when invoked via /xmind-mcp-smoke-test, before tagging a release, when validating an xmind-mcp build/deployment, or when the user says "smoke test xmind-mcp", "validate the MCP surface", or "run the release smoke test".
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/keep-docs-current.mdcCursor rule
- commit-messageSkill
- review-planSkill
- verify-changesSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 26
Optional read-only sanity pass: if the pointed-at file is a real .xmind, call xmind_open_map, xmind_list_sheets, and …
- Very specific: line 39
Keep a running scratch-pad of sheetMain, rootId, alphaId, etc.
- Distinctive: line 43
Run the phases in order; later phases depend on structure built earlier.
- Distinctive: line 121
After the run, remove the scratch and error-scenario files so the next run starts clean.
- Very specific: line 122
Delete both files only with a filesystem/shell tool that runs on the same machine as the xmind-mcp server.
- Distinctive: line 137
Every one of the 27 tools must appear.
- Distinctive: line 145
Do not mutate the file the instance was pointed at — always work on the self-created scratch file.
- Distinctive: line 146
Do not treat a successful write call as a pass on its own.
- Very specific: line 147
Do not skip tools to save time — release validation requires the full surface.
- Very specific: line 148
Do not report RELEASE OK with any NOT RUN, BLOCKED, or FAIL rows.
- Very specific: line 149
Do not invent tool arguments.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
xmind-mcp Smoke Test
This skill is run by a Claude instance that has xmind-mcp configured as an MCP server and is pointed at a writable location on disk. Its job is to confirm that every tool in the xmind-mcp surface works end to end before a release ships.
It is a smoke test, not a unit test: it drives the live MCP server exactly as a real client would, and verifies each mutation by reading it back through the tools (Claude cannot open .xmind files visually, so read-back is the source of truth).
Scope
- Exercise all 27 tools at least once — file/sheet management, find/search, topic mutation, and utilities.
- Verify every write with a read-back — after each mutating call, call the matching read tool (
xmind_get_subtree,xmind_get_topic_properties,xmind_list_relationships,xmind_list_sheets) and assert the change persisted. - Exercise error paths — deliberately trigger recoverable failures and confirm they come back as readable tool errors (
isError: truewith a usable message), not as protocol-level crashes. - Operate on a self-created scratch file — never mutate the file the instance was pointed at. All destructive work happens on a throwaway
.xmindcreated byxmind_create_map.
Preconditions
- Confirm the xmind-mcp tools are present (tool names prefixed
xmind_). If they are missing, stop and report that the MCP server is not connected — the smoke test cannot run. - Determine paths by string manipulation only (do not assume a filesystem tool is available):
- Scratch file (gets mutated): derive a sibling of the pointed-at path. Given
/dir/whatever.xmind, use/dir/xmind-smoke-scratch.xmind. Given only a directory, use<dir>/xmind-smoke-scratch.xmind. - Error-scenario file (separate, single-sheet):
/dir/xmind-smoke-errors.xmind. - Both must not already exist —
xmind_create_mapreturns a tool error if the file is present. A pre-existing scratch from a prior run is itself a finding: report it and pick a unique suffix.
- Scratch file (gets mutated): derive a sibling of the pointed-at path. Given
- Optional read-only sanity pass: if the pointed-at file is a real
.xmind, callxmind_open_map,xmind_list_sheets, andxmind_flatten_to_outlineon it first. These are non-mutating and prove the read tools work against real-world content. Do not write to it.
Capturing IDs
Several tools return IDs you must thread into later calls. Note where each comes from:
xmind_create_map/xmind_add_sheetreturn the sheet id in their text result ("...with sheet id <ID>","added sheet id <ID>"). Parse it out.- Root-topic IDs are not returned by
create_maporopen_map. Get them fromxmind_get_subtree(the root node'sid). xmind_add_topic,xmind_add_topics_bulk,xmind_duplicate_topic,xmind_move_topicreturn JSON with the new/affected IDs.xmind_import_from_outlineinto a new sheet (nosheet_id) returns the new sheet id in its text ("imported N topics into new sheet id <ID>"). Parse it out.xmind_add_summaryreturns the new summary topic's id in its text ("added summary topic id <ID>"). Parse it out.- Relationship IDs come from
xmind_list_relationships.
Keep a running scratch-pad of sheetMain, rootId, alphaId, etc. as you go.
Test plan
Run the phases in order; later phases depend on structure built earlier. For each numbered step: make the call, then make its assert read-back. Record PASS/FAIL with the observed result. A failed read-back is a FAIL even if the write call "succeeded".
Phase 1 — File & sheet management
xmind_create_map→ scratch path,root_title="Smoke Root",sheet_title="Main". CapturesheetMain. Assert: success text.xmind_open_map→ scratch. Assert: top-levelsheetCount=1, and insheets[0]: title"Main",rootTopicTitle="Smoke Root",topicCount=1(these are nested per-sheet, not top-level).xmind_list_sheets. Assert: one sheet, id =sheetMain.xmind_get_subtree→sheetMain. CapturerootId(root nodeid). Assert: title"Smoke Root", no children.xmind_add_sheet→title="Secondary",root_title="Secondary Root". CapturesheetSecondary.xmind_list_sheets. Assert: 2 sheets now.xmind_delete_sheet→sheetSecondary.xmind_list_sheets. Assert: back to 1 sheet;sheetSecondarygone.
Phase 2 — Topic creation & bulk add
xmind_add_topic→ parentrootId,title="Alpha". CapturealphaId. Assert:position=0.xmind_add_topic→ parentrootId,title="Beta". CapturebetaId.xmind_add_topic→ parentrootId,title="Gamma". CapturegammaId.xmind_get_subtree→sheetMain. Assert: root has children[Alpha, Beta, Gamma]in order.xmind_add_topics_bulk→ parentalphaId,topics=[{"title":"A1","children":[{"title":"A1a"}]},{"title":"A2"}]. CapturerootTopicIds. Assert:addedCount=3(counts the nestedA1a, not just top-level items) andlen(rootTopicIds)=2(top-level only — do not conflate the two).xmind_get_subtree→sheetMain,topic_id=alphaId. Assert: childrenA1(with childA1a) andA2.
Phase 3 — Topic properties (set / get / bulk / clear)
xmind_set_topic_properties→betaId,notes="Beta note",labels=["lbl1","lbl2"],markers=["priority-1","task-done"],link="https://example.com".xmind_get_topic_properties→betaId. Assert:notescontains "Beta note",labelsmatch,markersmatch,href="https://example.com".xmind_set_topic_properties_bulk→topic_ids=[alphaId, gammaId],labels=["bulk"].xmind_get_topic_properties→alphaIdandgammaId. Assert: both have label"bulk".xmind_set_topic_properties→betaId,markers=["priority-1","priority-2"],remove_markers=["priority-2"]. Assert viaxmind_get_topic_properties: markers =["priority-1"]only (remove applied after replace).- Clear semantics:
xmind_set_topic_properties→betaId,notes="",link="",labels=[],markers=[]. The""values are empty JSON strings ("notes": ""), not the two-character text""; passing the literal quotes stores them as note and link text. Assert viaxmind_get_topic_properties: notes, href, labels, markers all absent.
Phase 4 — Find & search
xmind_search_topics→ omitsheet_id,query="a"(all sheets). Assert:matchCount>0and matches carrysheetId/sheetTitle.xmind_search_topics→sheet_id=sheetMain,query="Beta". Assert: matches Beta; no sheet metadata on items (single-sheet scope).xmind_find_topic→sheetMain,title="Alpha". Assert:id=alphaId;childrenTitlesincludeA1,A2.xmind_find_topic→sheetMain,title="A1",parent_id=alphaId(scoped). Assert: found under the scope.
Phase 5 — Structure: rename, move, reorder, duplicate, floating, delete
xmind_rename_topic→gammaId,title="Gamma Renamed". Assert viaxmind_get_subtree: title updated.xmind_move_topic→gammaId,new_parent_id=betaId,position=0. Assert: resultparentId=betaId;xmind_get_subtree(betaId)shows Gamma as child. (Root children now[Alpha, Beta].)xmind_reorder_children→ parentrootId,ordered_ids=[betaId, alphaId](must list every attached child exactly once). Assert viaxmind_get_subtree: root children now[Beta, Alpha].xmind_duplicate_topic→topic_id=alphaId,target_parent_id=rootId. CapturenewRootId,copiedCount. Assert:newRootId != alphaId;xmind_get_subtreeshows a second Alpha subtree with fresh IDs.xmind_add_floating_topic→sheetMain,title="Floater". Assert viaxmind_get_topic_properties(rootId):childCounts.detached >= 1; viaxmind_get_subtree(sheetMain): "Floater" appears in the root's children withchildType: "detached", and the attached children have nochildType; and viaxmind_search_topics(sheetMain, query="Floater"): the match haschildType: "detached".xmind_add_relationship→from_id=newRootId,to_id=betaId. Thenxmind_delete_topic→newRootId(the duplicate). Assert: the delete result ends withremoved 1 relationship(s);xmind_list_relationships(sheetMain)shows count = 0 (deleting a topic removes the relationships connected to it); and viaxmind_get_subtree: the duplicated subtree is gone, originalAlpharemains.
Phase 6 — Relationships (sheet-level)
xmind_add_relationship→from_id=alphaId,to_id=betaId,label="rel".xmind_list_relationships→sheetMain. CapturerelId. Assert: count = 1;end1Id=alphaId,end2Id=betaId, title"rel".xmind_get_topic_properties→alphaId. Assert:relationshipsincludesrelId(confirms sheet-level storage is surfaced per-topic).xmind_delete_relationship→relId. Assert viaxmind_list_relationships: count = 0.
Phase 7 — Summaries & boundaries
xmind_add_summary→ parentalphaId,from_index=0,to_index=1,title="Sum"(spansA1,A2). CapturesumIdfrom the result text (E9 needs it). Assert viaxmind_get_topic_properties(alphaId):summaryCount >= 1andchildCounts.summary >= 1— this confirms the required double-write (range descriptor + summary topic). Also Assert viaxmind_get_subtree(alphaId): "Sum" appears in Alpha's children withchildType: "summary".xmind_add_boundary→ parentalphaId,title="Bound". Assert viaxmind_get_topic_properties(alphaId):boundaryCount >= 1, a boundary with title"Bound".
Phase 8 — Utilities: outline export/import, find & replace
xmind_flatten_to_outline→sheetMain,format="markdown",include_notes=true. Assert: Markdown text listing the topic titles.xmind_flatten_to_outline→topic_id=alphaId,format="text". Assert: indented plain-text outline of Alpha's subtree.xmind_import_from_outline→outline="# Imported\n- Child 1\n- Child 2", omitsheet_id(creates a new sheet). CapturesheetImportedfrom the result. Assert: result saysimported 3 topics;xmind_list_sheetsshows a new sheet titled"Imported"; andxmind_get_subtree(sheetImported)shows root"Imported"with children exactly[Child 1, Child 2](list items under a heading must not be dropped).xmind_import_from_outline→outline="- Solo A\n- Solo B", omitsheet_idandroot_title. Capture the new sheet id. Assert: result saysimported 3 topics(the synthesized root counts);xmind_get_subtreeon that sheet shows root"Imported Outline"with children exactly[Solo A, Solo B](several top-level items become siblings under a synthesized root).xmind_import_from_outline→ same outline,root_title="Solos", omitsheet_id. Capture the new sheet id. Assert: result saysimported 3 topics; the sheet and its root are both titled"Solos"; root children exactly[Solo A, Solo B].xmind_import_from_outline→outline="- Extra A\n- Extra B",sheet_id=sheetMain,parent_id=rootId. Assert viaxmind_get_subtree:Extra AandExtra Bnow under root. The result text carries no ids, so captureextraAIdandextraBIdfrom this read-back (E5 needs them).xmind_find_and_replace→sheet_id=sheetMain,find="Alpha",replace="Alfa". Assert: the result haschangedCount=1and onechangesentry withid=alphaId,oldTitle="Alpha",newTitle="Alfa"(only Alpha matches on this sheet; the duplicate was deleted in step 30). Assert viaxmind_search_topics:Alfapresent,Alphano longer matches.xmind_find_and_replace→ omitsheet_id(all sheets),find="Beta",replace="Beta!",exact_match=true. Assert: the result haschangedCount=1and onechangesentry withid=betaId,oldTitle="Beta",newTitle="Beta!",sheetId=sheetMain(entries carrysheetIdwhen more than one sheet is searched; the map has four sheets by now). Assert viaxmind_search_topics: exact-titledBetarenamed.
Phase 9 — Error paths (must return tool errors, not crashes)
For each, PASS = a recoverable tool error with a readable message; FAIL = protocol error/crash, a misleading message, or unexpected success.
E1. xmind_open_map → a path that does not exist. Expect: tool error (file not found).
E2. xmind_create_map → the existing scratch path. Expect: tool error ("file already exists").
E3. xmind_get_topic_properties → sheetMain, topic_id="does-not-exist". Expect: tool error ("topic not found").
E4. xmind_delete_topic → sheetMain, topic_id=rootId. Expect: tool error (cannot delete the sheet root).
E5. xmind_reorder_children → rootId with an ordered_ids list built from the root's current attached children, with one real id replaced by a fake id. Take the list from a fresh xmind_get_subtree(sheetMain): use the root's children that have no childType (skip "Floater", which is childType: "detached"). At this point that is [betaId, alphaId, extraAId, extraBId], so send e.g. ["fake-id", alphaId, extraAId, extraBId]. Expect: tool error ("ordered_ids contains unknown id"). Note: the handler checks list length first, so a list of the wrong length instead returns a length-mismatch error — also a valid tool error, but a different message.
E6. xmind_move_topic → move alphaId under one of its own descendants (e.g. A1). Expect: tool error (cannot move a topic into its own subtree).
E7. Create the error-scenario file with xmind_create_map (single sheet). Then xmind_delete_sheet on its only sheet. Expect: tool error ("cannot delete the last sheet").
E8. xmind_add_summary → sheetMain, parent alphaId, from_index=0.5, to_index=1. Expect: tool error ("invalid argument from_index: must be a whole number"). from_index is declared an integer, so a client that checks arguments against the schema may refuse to send the call. If it does, record PASS with the client's message and note that the server check was not reached.
E9. xmind_move_topic → sheetMain, topic_id=sumId, new_parent_id=rootId. Expect: tool error ("cannot move a summary topic").
E10. xmind_open_map → <scratch path>/child.xmind (the scratch path is a file, so this path goes through a file). Expect: tool error ("cannot access", or "file not found" on Windows), not a protocol error.
Cleanup
After the run, remove the scratch and error-scenario files so the next run starts clean. There is no MCP "delete map" tool, so:
- Delete both files only with a filesystem/shell tool that runs on the same machine as the xmind-mcp server. A shell in a cloud sandbox or a different container cannot see the server's files, so its
rmdeletes nothing even when it reports success. - Otherwise, report their full paths and ask the operator to delete them (a leftover file will make the next
xmind_create_mapfail).
Reporting
Produce a per-tool PASS/FAIL report suitable for release sign-off. Structure:
- Header: scratch path used, date, and the xmind-mcp version if exposed by the MCP server handshake (no tool returns a version —
xmind_open_mapreturns onlypath,sheetCount,sheets). Coverage table — one row per tool, with PASS/FAIL and a one-line observed result:
Tool Result Notes xmind_create_mapPASS created scratch, sheet id captured ... ... ... Every one of the 27 tools must appear. Mark any not reached as NOT RUN with the reason.
- Error-path table — E1–E10 with PASS/FAIL and the actual message returned.
- Final verdict:
RELEASE OKonly if every tool ran and every assertion + error path passed. OtherwiseRELEASE BLOCKEDwith the failing items listed first.
State failures plainly with the exact tool call and the observed vs. expected result. Do not soften or omit a failure. If a step could not run because an earlier step failed, mark it BLOCKED and say which step blocked it.
Anti-patterns
- Do not mutate the file the instance was pointed at — always work on the self-created scratch file.
- Do not treat a successful write call as a pass on its own; the read-back assertion is what counts.
- Do not skip tools to save time — release validation requires the full surface. A skipped tool is
NOT RUN, never an implied PASS. - Do not report
RELEASE OKwith anyNOT RUN,BLOCKED, orFAILrows. - Do not invent tool arguments; use only the documented parameters for each
xmind_*tool.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

