agentleFS
mab-gomab-go/xmind-mcp/.agents/skills/xmind-mcp-smoke-test/SKILL.md

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".

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
  1. Very specific:

    Optional read-only sanity pass: if the pointed-at file is a real .xmind, call xmind_open_map, xmind_list_sheets, and …

    line 26
  2. Very specific:

    Keep a running scratch-pad of sheetMain, rootId, alphaId, etc.

    line 39
  3. Distinctive:

    Run the phases in order; later phases depend on structure built earlier.

    line 43
  4. Distinctive:

    After the run, remove the scratch and error-scenario files so the next run starts clean.

    line 121
  5. Very specific:

    Delete both files only with a filesystem/shell tool that runs on the same machine as the xmind-mcp server.

    line 122
  6. Distinctive:

    Every one of the 27 tools must appear.

    line 137
  7. Distinctive:

    Do not mutate the file the instance was pointed at — always work on the self-created scratch file.

    line 145
  8. Distinctive:

    Do not treat a successful write call as a pass on its own.

    line 146
  9. Very specific:

    Do not skip tools to save time — release validation requires the full surface.

    line 147
  10. Very specific:

    Do not report RELEASE OK with any NOT RUN, BLOCKED, or FAIL rows.

    line 148
  11. Very specific:

    Do not invent tool arguments.

    line 149

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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: true with 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 .xmind created by xmind_create_map.

Preconditions

  1. 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.
  2. 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_map returns 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.
  3. Optional read-only sanity pass: if the pointed-at file is a real .xmind, call xmind_open_map, xmind_list_sheets, and xmind_flatten_to_outline on 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_sheet return 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_map or open_map. Get them from xmind_get_subtree (the root node's id).
  • xmind_add_topic, xmind_add_topics_bulk, xmind_duplicate_topic, xmind_move_topic return JSON with the new/affected IDs.
  • xmind_import_from_outline into a new sheet (no sheet_id) returns the new sheet id in its text ("imported N topics into new sheet id <ID>"). Parse it out.
  • xmind_add_summary returns 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

  1. xmind_create_map → scratch path, root_title="Smoke Root", sheet_title="Main". Capture sheetMain. Assert: success text.
  2. xmind_open_map → scratch. Assert: top-level sheetCount=1, and in sheets[0]: title "Main", rootTopicTitle="Smoke Root", topicCount=1 (these are nested per-sheet, not top-level).
  3. xmind_list_sheets. Assert: one sheet, id = sheetMain.
  4. xmind_get_subtree → sheetMain. Capture rootId (root node id). Assert: title "Smoke Root", no children.
  5. xmind_add_sheet → title="Secondary", root_title="Secondary Root". Capture sheetSecondary.
  6. xmind_list_sheets. Assert: 2 sheets now.
  7. xmind_delete_sheet → sheetSecondary.
  8. xmind_list_sheets. Assert: back to 1 sheet; sheetSecondary gone.

Phase 2 — Topic creation & bulk add

  1. xmind_add_topic → parent rootId, title="Alpha". Capture alphaId. Assert: position=0.
  2. xmind_add_topic → parent rootId, title="Beta". Capture betaId.
  3. xmind_add_topic → parent rootId, title="Gamma". Capture gammaId.
  4. xmind_get_subtree → sheetMain. Assert: root has children [Alpha, Beta, Gamma] in order.
  5. xmind_add_topics_bulk → parent alphaId, topics=[{"title":"A1","children":[{"title":"A1a"}]},{"title":"A2"}]. Capture rootTopicIds. Assert: addedCount=3 (counts the nested A1a, not just top-level items) and len(rootTopicIds)=2 (top-level only — do not conflate the two).
  6. xmind_get_subtree → sheetMain, topic_id=alphaId. Assert: children A1 (with child A1a) and A2.

Phase 3 — Topic properties (set / get / bulk / clear)

  1. xmind_set_topic_properties → betaId, notes="Beta note", labels=["lbl1","lbl2"], markers=["priority-1","task-done"], link="https://example.com".
  2. xmind_get_topic_properties → betaId. Assert: notes contains "Beta note", labels match, markers match, href="https://example.com".
  3. xmind_set_topic_properties_bulk → topic_ids=[alphaId, gammaId], labels=["bulk"].
  4. xmind_get_topic_properties → alphaId and gammaId. Assert: both have label "bulk".
  5. xmind_set_topic_properties → betaId, markers=["priority-1","priority-2"], remove_markers=["priority-2"]. Assert via xmind_get_topic_properties: markers = ["priority-1"] only (remove applied after replace).
  6. 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 via xmind_get_topic_properties: notes, href, labels, markers all absent.

Phase 4 — Find & search

  1. xmind_search_topics → omit sheet_id, query="a" (all sheets). Assert: matchCount>0 and matches carry sheetId/sheetTitle.
  2. xmind_search_topics → sheet_id=sheetMain, query="Beta". Assert: matches Beta; no sheet metadata on items (single-sheet scope).
  3. xmind_find_topic → sheetMain, title="Alpha". Assert: id=alphaId; childrenTitles include A1, A2.
  4. xmind_find_topic → sheetMain, title="A1", parent_id=alphaId (scoped). Assert: found under the scope.

Phase 5 — Structure: rename, move, reorder, duplicate, floating, delete

  1. xmind_rename_topic → gammaId, title="Gamma Renamed". Assert via xmind_get_subtree: title updated.
  2. xmind_move_topic → gammaId, new_parent_id=betaId, position=0. Assert: result parentId=betaId; xmind_get_subtree(betaId) shows Gamma as child. (Root children now [Alpha, Beta].)
  3. xmind_reorder_children → parent rootId, ordered_ids=[betaId, alphaId] (must list every attached child exactly once). Assert via xmind_get_subtree: root children now [Beta, Alpha].
  4. xmind_duplicate_topic → topic_id=alphaId, target_parent_id=rootId. Capture newRootId, copiedCount. Assert: newRootId != alphaId; xmind_get_subtree shows a second Alpha subtree with fresh IDs.
  5. xmind_add_floating_topic → sheetMain, title="Floater". Assert via xmind_get_topic_properties(rootId): childCounts.detached >= 1; via xmind_get_subtree(sheetMain): "Floater" appears in the root's children with childType: "detached", and the attached children have no childType; and via xmind_search_topics(sheetMain, query="Floater"): the match has childType: "detached".
  6. xmind_add_relationship → from_id=newRootId, to_id=betaId. Then xmind_delete_topic → newRootId (the duplicate). Assert: the delete result ends with removed 1 relationship(s); xmind_list_relationships(sheetMain) shows count = 0 (deleting a topic removes the relationships connected to it); and via xmind_get_subtree: the duplicated subtree is gone, original Alpha remains.

Phase 6 — Relationships (sheet-level)

  1. xmind_add_relationship → from_id=alphaId, to_id=betaId, label="rel".
  2. xmind_list_relationships → sheetMain. Capture relId. Assert: count = 1; end1Id=alphaId, end2Id=betaId, title "rel".
  3. xmind_get_topic_properties → alphaId. Assert: relationships includes relId (confirms sheet-level storage is surfaced per-topic).
  4. xmind_delete_relationship → relId. Assert via xmind_list_relationships: count = 0.

Phase 7 — Summaries & boundaries

  1. xmind_add_summary → parent alphaId, from_index=0, to_index=1, title="Sum" (spans A1,A2). Capture sumId from the result text (E9 needs it). Assert via xmind_get_topic_properties(alphaId): summaryCount >= 1 and childCounts.summary >= 1 — this confirms the required double-write (range descriptor + summary topic). Also Assert via xmind_get_subtree(alphaId): "Sum" appears in Alpha's children with childType: "summary".
  2. xmind_add_boundary → parent alphaId, title="Bound". Assert via xmind_get_topic_properties(alphaId): boundaryCount >= 1, a boundary with title "Bound".

Phase 8 — Utilities: outline export/import, find & replace

  1. xmind_flatten_to_outline → sheetMain, format="markdown", include_notes=true. Assert: Markdown text listing the topic titles.
  2. xmind_flatten_to_outline → topic_id=alphaId, format="text". Assert: indented plain-text outline of Alpha's subtree.
  3. xmind_import_from_outline → outline="# Imported\n- Child 1\n- Child 2", omit sheet_id (creates a new sheet). Capture sheetImported from the result. Assert: result says imported 3 topics; xmind_list_sheets shows a new sheet titled "Imported"; and xmind_get_subtree(sheetImported) shows root "Imported" with children exactly [Child 1, Child 2] (list items under a heading must not be dropped).
  4. xmind_import_from_outline → outline="- Solo A\n- Solo B", omit sheet_id and root_title. Capture the new sheet id. Assert: result says imported 3 topics (the synthesized root counts); xmind_get_subtree on that sheet shows root "Imported Outline" with children exactly [Solo A, Solo B] (several top-level items become siblings under a synthesized root).
  5. xmind_import_from_outline → same outline, root_title="Solos", omit sheet_id. Capture the new sheet id. Assert: result says imported 3 topics; the sheet and its root are both titled "Solos"; root children exactly [Solo A, Solo B].
  6. xmind_import_from_outline → outline="- Extra A\n- Extra B", sheet_id=sheetMain, parent_id=rootId. Assert via xmind_get_subtree: Extra A and Extra B now under root. The result text carries no ids, so capture extraAId and extraBId from this read-back (E5 needs them).
  7. xmind_find_and_replace → sheet_id=sheetMain, find="Alpha", replace="Alfa". Assert: the result has changedCount=1 and one changes entry with id=alphaId, oldTitle="Alpha", newTitle="Alfa" (only Alpha matches on this sheet; the duplicate was deleted in step 30). Assert via xmind_search_topics: Alfa present, Alpha no longer matches.
  8. xmind_find_and_replace → omit sheet_id (all sheets), find="Beta", replace="Beta!", exact_match=true. Assert: the result has changedCount=1 and one changes entry with id=betaId, oldTitle="Beta", newTitle="Beta!", sheetId=sheetMain (entries carry sheetId when more than one sheet is searched; the map has four sheets by now). Assert via xmind_search_topics: exact-titled Beta renamed.

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 rm deletes 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_map fail).

Reporting

Produce a per-tool PASS/FAIL report suitable for release sign-off. Structure:

  1. Header: scratch path used, date, and the xmind-mcp version if exposed by the MCP server handshake (no tool returns a version — xmind_open_map returns only path, sheetCount, sheets).
  2. Coverage table — one row per tool, with PASS/FAIL and a one-line observed result:

    ToolResultNotes
    xmind_create_mapPASScreated scratch, sheet id captured
    .........

    Every one of the 27 tools must appear. Mark any not reached as NOT RUN with the reason.

  3. Error-path table — E1–E10 with PASS/FAIL and the actual message returned.
  4. Final verdict: RELEASE OK only if every tool ran and every assertion + error path passed. Otherwise RELEASE BLOCKED with 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 OK with any NOT RUN, BLOCKED, or FAIL rows.
  • Do not invent tool arguments; use only the documented parameters for each xmind_* tool.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.