@zengjing/xmind-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zengjing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,574 @@
+# XMind MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@zengjing%2Fxmind-mcp.svg)](https://www.npmjs.com/package/@zengjing/xmind-mcp)
+[![license](https://img.shields.io/npm/l/@zengjing%2Fxmind-mcp.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/@zengjing%2Fxmind-mcp.svg)](https://www.npmjs.com/package/@zengjing/xmind-mcp)
+[![MCP](https://img.shields.io/badge/MCP-1.0-blueviolet.svg)](https://modelcontextprotocol.io)
+
+A Model Context Protocol (MCP) server for parsing and searching XMind mind map files (.xmind). Enables Claude and other AI applications to efficiently extract, search, and manipulate mind map data with token-aware formatting and intelligent error handling.
+
+## Features
+
+- **Full Document Parsing**: Convert entire XMind documents to structured Markdown or JSON format
+- **Efficient Search**: Search nodes by keyword, label, or status marker with breadcrumb path resolution
+- **Branch Extraction**: Extract specific subtrees with optional depth limiting for token optimization
+- **Multi-Format Support**: Handles both Zen (modern JSON-based) and Legacy (XML-based) XMind formats
+- **Token-Aware Output**: Estimates token consumption and provides optimization suggestions
+- **Error Guidance**: Helpful error messages with actionable recovery steps
+- **Claude Desktop Integration**: Ready to use as a Claude Desktop tool
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+  - [Global Install (Recommended)](#global-install-recommended)
+  - [From Source](#from-source)
+- [Usage](#usage)
+  - [Running the MCP Server](#running-the-mcp-server)
+  - [Claude Desktop Configuration](#claude-desktop-configuration)
+  - [Command-Line (CLI) Usage](#command-line-cli-usage)
+- [Tools Documentation](#tools-documentation)
+  - [parse_xmind](#1-parse_xmind)
+  - [search_xmind_nodes](#2-search_xmind_nodes)
+  - [get_xmind_node_branch](#3-get_xmind_node_branch)
+- [Debugging with MCP Inspector](#debugging-with-mcp-inspector)
+- [Development](#development)
+- [Limitations and Known Issues](#limitations-and-known-issues)
+- [Troubleshooting](#troubleshooting)
+- [Support](#support)
+- [License](#license)
+- [Changelog](#changelog)
+
+## Quick Start
+
+> Get from zero to a working result in under a minute.
+
+**Option A — Global install (fastest)**
+
+```bash
+npm install -g @zengjing/xmind-mcp
+xmind-mcp --help                                 # verify install
+xmind-mcp ~/Documents/my-mindmap.xmind          # try CLI on a file
+```
+
+**Option B — Local dev install**
+
+```bash
+git clone https://github.com/hhtczengjing/xmind-mcp.git
+cd xmind-mcp
+npm install
+npm run build
+npm start                                        # launches MCP server on stdio
+```
+
+Then point Claude Desktop at the built `dist/index.js` (see [Claude Desktop Configuration](#claude-desktop-configuration)).
+
+## Installation
+
+### Requirements
+
+- Node.js 18.0 or higher (matches `engines.node` in `package.json`)
+- npm or yarn package manager
+
+### Global Install (Recommended)
+
+The `bin` field in `package.json` exposes the `xmind-mcp` command globally, so most users can skip building from source:
+
+```bash
+npm install -g @zengjing/xmind-mcp
+xmind-mcp --help
+```
+
+This gives you both:
+- the `xmind-mcp` CLI (see [Command-Line Usage](#command-line-cli-usage))
+- a runnable MCP server entry point at `<npm-prefix>/lib/node_modules/@zengjing/xmind-mcp/dist/index.js`
+
+> 📌 Use `npm root -g` (macOS/Linux) or `%APPDATA%\npm` (Windows) to locate `dist/index.js` for your Claude Desktop config.
+
+### From Source
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/hhtczengjing/xmind-mcp.git
+   cd xmind-mcp
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Build the project**
+   ```bash
+   npm run build
+   ```
+
+4. **Verify installation**
+   ```bash
+   npm run lint
+   ```
+
+## Usage
+
+### Running the Server
+
+Start the MCP server via stdio transport:
+
+```bash
+npm start
+```
+
+The server will start and listen for MCP protocol requests on stdin/stdout.
+
+For development with hot reload:
+
+```bash
+npm run dev
+```
+
+### Claude Desktop Configuration
+
+To use with Claude Desktop, add the server to your `claude_desktop_config.json`:
+
+**Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+
+**Configuration**:
+```json
+{
+  "mcpServers": {
+    "xmind-mcp": {
+      "command": "node",
+      "args": ["/path/to/xmind-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Replace `/path/to/xmind-mcp` with the absolute path to your xmind-mcp directory.
+
+After adding the configuration, restart Claude Desktop. The three tools will be available to Claude.
+
+### Command-Line (CLI) Usage
+
+The project ships a standalone CLI built on the same parser/formatters that power the MCP tools. It's useful for quick inspection, scripting, and CI pipelines.
+
+**Script alias** (from source): `npm run parse -- <file> [options]`
+**Global command** (after `npm install -g`): `xmind-mcp <file> [options]`
+**Direct binary**: `node dist/cli.js <file> [options]`
+
+**Usage**
+
+```
+xmind-mcp <file-path> [options]
+
+Arguments:
+  <file-path>     Path to the .xmind file (supports ~ for home directory)
+
+Options:
+  -f, --format    Output format: 'markdown' (default) or 'json'
+  -o, --output    Save output to file
+  -s, --search    Filter results by keyword (case-insensitive)
+  -v, --verbose   Show sheet titles and parsing details
+  -h, --help      Show this help message
+```
+
+**Examples**
+
+```bash
+# Print a Markdown outline to stdout
+xmind-mcp ~/Documents/project-plan.xmind
+
+# JSON output, saved to a file
+xmind-mcp ~/Documents/strategy.xmind --format json -o strategy.json
+
+# Filter content by a keyword
+xmind-mcp ~/Documents/notes.xmind --search "deadline"
+
+# Verbose mode (shows file metadata + per-sheet titles)
+xmind-mcp ~/Documents/notes.xmind -v
+```
+
+The CLI prints a header block with file metadata (format version, sheet count, total topics, parse timestamp) followed by the formatted content, and exits with status code `0` on success or `1` on error.
+
+## Tools Documentation
+
+### 1. parse_xmind
+
+**Description**: Parse an entire XMind document and return formatted output (Markdown or JSON).
+
+**When to use**:
+- Analyzing complete mind map structures
+- Creating summaries or reports from mind maps
+- Understanding full document architecture
+
+**Parameters**:
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | Yes | - | Absolute file path to the .xmind file. Supports `~` for home directory expansion. |
+| `format` | string | No | `markdown` | Output format: `markdown` (token-efficient, recommended) or `json` (structured). |
+
+**Examples**:
+
+```
+Tool Call:
+  parse_xmind
+  path: "~/Documents/project-plan.xmind"
+  format: "markdown"
+
+Response:
+  Complete mind map structure in Markdown format with token estimate.
+  Includes recommendations for large documents (>20K tokens).
+```
+
+```
+Tool Call:
+  parse_xmind
+  path: "/Users/alice/xmind/strategy.xmind"
+  format: "json"
+
+Response:
+  Structure summary + full JSON representation with metadata.
+```
+
+**Output**:
+- Formatted content (Markdown or JSON)
+- Metadata: file path, XMind format (Zen/Legacy), sheet count, topic count
+- Token estimation and optimization suggestions for large documents
+- Character count and recommendations for context efficiency
+
+**Token Efficiency**:
+- Markdown format: ~1 token per 4 characters (most efficient)
+- JSON format: ~1 token per 3 characters (more detailed metadata)
+- Large documents (>20K tokens): Consider using search or branch extraction
+
+### 2. search_xmind_nodes
+
+**Description**: Search for nodes in an XMind file by keyword, label, or status marker with breadcrumb path resolution.
+
+**When to use**:
+- Finding specific topics in large mind maps without loading entire document
+- Locating nodes by keyword, label, or marker type
+- Narrowing context for focused analysis
+
+**Parameters**:
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | Yes | - | Absolute file path to the .xmind file. Supports `~` for home directory. |
+| `query` | string | Yes | - | Search keyword or phrase to match in node titles, notes, or labels. |
+| `searchIn` | array | No | `['title', 'note', 'label']` | Fields to search in: `title`, `note`, `label`. Specify subset to optimize. |
+| `caseSensitive` | boolean | No | `false` | Enable case-sensitive matching (default: case-insensitive). |
+
+**Examples**:
+
+```
+Tool Call:
+  search_xmind_nodes
+  path: "~/Documents/project-plan.xmind"
+  query: "deadline"
+  searchIn: ["title", "note"]
+
+Response:
+  Found 3 matches:
+  1. Project Deadline
+     Path: Project Plan > Timeline > Project Deadline
+     Match: title — "deadline"
+     Note: Must complete by end of Q3...
+  
+  2. Milestone Due Date
+     Path: Project Plan > Phases > Phase 2 > Milestone Due Date
+     Match: note — "Deadline is Sept 30th"
+  ...
+```
+
+```
+Tool Call:
+  search_xmind_nodes
+  path: "/Users/alice/xmind/architecture.xmind"
+  query: "API"
+  caseSensitive: true
+  searchIn: ["title"]
+
+Response:
+  Found 2 matches:
+  1. REST API Design
+     Path: Architecture > Backend > REST API Design
+     Match: title — "REST API Design"
+  ...
+```
+
+**Output**:
+- Match count and result details
+- Breadcrumb paths (root → ... → node) for context
+- Match type and matched text excerpt
+- Node notes preview (first 80 characters) if available
+- Matched nodes have IDs that can be used with `get_xmind_node_branch`
+
+### 3. get_xmind_node_branch
+
+**Description**: Extract a specific node and its subtree (up to specified depth) from an XMind file.
+
+**When to use**:
+- Focusing on specific branches to avoid token overload
+- Extracting relevant subtrees for detailed analysis
+- Limiting recursion depth for performance
+- Narrowing context after search results
+
+**Parameters**:
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `path` | string | Yes | - | Absolute file path to the .xmind file. |
+| `nodeId` | string | Yes | - | Target node ID to extract. Get IDs via `search_xmind_nodes` or `parse_xmind` output. |
+| `depth` | number | No | unlimited | Maximum recursion depth for children (0 = node only, 1 = children, 2+ = deeper). |
+
+**Examples**:
+
+```
+Tool Call:
+  get_xmind_node_branch
+  path: "~/Documents/project-plan.xmind"
+  nodeId: "topic-42a"
+  depth: 2
+
+Response:
+  Extracted 8 nodes (depth: 2/2)
+  
+  - Target Topic
+    - Child 1
+      - Grandchild 1
+      - Grandchild 2
+    - Child 2
+    > Supporting notes if available...
+```
+
+```
+Tool Call:
+  get_xmind_node_branch
+  path: "/Users/alice/xmind/strategy.xmind"
+  nodeId: "analysis-backend"
+
+Response:
+  Extracted 24 nodes (depth: 4/∞)
+  
+  - Backend Architecture
+    - API Layer
+      - REST Endpoints
+      - GraphQL
+    - Database
+      - Schema Design
+      - Performance Tuning
+    ...
+```
+
+**Output**:
+- Node count and depth information
+- Extracted subtree in Markdown outline format
+- Metadata: actual depth reached vs requested depth
+- Suitable for direct analysis or further processing
+
+## Debugging with MCP Inspector
+
+The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official debugger for MCP servers. It streams `ListTools` / `CallTool` traffic so you can verify your install and inspect each request/response without going through Claude Desktop.
+
+```bash
+# From the project root, with deps installed
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+In the Inspector UI:
+1. Confirm the three tools (`parse_xmind`, `search_xmind_nodes`, `get_xmind_node_branch`) appear under **Tools**.
+2. Pick a tool, fill in `path` to a real `.xmind` file, and hit **Run**.
+3. Use the **Notifications** / **Logs** pane to see structured log output (the server uses the `utils/logger.ts` module with `info` / `warn` / `error` levels).
+
+Enable verbose logging in any environment by setting `DEBUG=xmind-mcp`.
+
+## Development
+
+### Project Structure
+
+```
+xmind-mcp/
+├── src/
+│   ├── index.ts                    # MCP server entry point (stdio transport)
+│   ├── cli.ts                      # Standalone CLI for local/scripted use
+│   ├── core/
+│   │   ├── parser.ts              # Unified parser interface
+│   │   ├── zen-parser.ts          # Zen (JSON) format handler
+│   │   └── legacy-parser.ts       # Legacy (XML) format handler
+│   ├── tools/
+│   │   ├── parse-tool.ts          # parse_xmind implementation
+│   │   ├── search-tool.ts         # search_xmind_nodes implementation
+│   │   └── branch-tool.ts         # get_xmind_node_branch implementation
+│   ├── formatters/
+│   │   ├── markdown-formatter.ts  # Markdown output formatting
+│   │   └── json-formatter.ts      # JSON output formatting
+│   ├── model/
+│   │   ├── types.ts               # Core TypeScript types (XMindNode, XMindSheet, etc.)
+│   │   └── schemas.ts             # Zod schemas for input validation
+│   └── utils/
+│       ├── errors.ts              # Error types and handling
+│       ├── file-utils.ts          # File path resolution and validation
+│       └── logger.ts              # Structured logging utilities
+├── tests/                          # Jest test suite
+├── dist/                           # Compiled JavaScript (generated)
+├── package.json
+├── tsconfig.json
+└── jest.config.js
+```
+
+### File Descriptions
+
+#### Core Modules
+
+- **parser.ts**: Unified interface for parsing both Zen and Legacy formats. Auto-detects format and delegates to appropriate parser.
+- **zen-parser.ts**: Handles modern XMind Zen format (JSON-based). Extracts content.xml from .zip archive.
+- **legacy-parser.ts**: Handles legacy XMind 8 format (XML-based). Parses workbook.xml structure.
+
+#### Entry Points
+
+- **index.ts**: MCP server. Listens on stdio and routes `parse_xmind` / `search_xmind_nodes` / `get_xmind_node_branch` calls.
+- **cli.ts**: Standalone CLI (see [Command-Line Usage](#command-line-cli-usage)). Built into `dist/cli.js` and exposed as the `xmind-mcp` global command.
+
+#### Tool Implementations
+
+- **parse-tool.ts**: Full document parsing with format selection. Includes token estimation and optimization suggestions.
+- **search-tool.ts**: Breadth-first search across all sheets with path tracking. Supports field filtering and case sensitivity.
+- **branch-tool.ts**: Tree extraction with depth limiting. Useful for large documents.
+
+#### Formatters
+
+- **markdown-formatter.ts**: Converts AST to token-efficient Markdown outline. Escapes special characters and includes metadata.
+- **json-formatter.ts**: Full-featured JSON output with structure summary. Useful for programmatic processing.
+
+#### Model & Utilities
+
+- **types.ts**: Core types: XMindNode, XMindSheet, XMindParsedResult, SearchResult, etc.
+- **schemas.ts**: Zod validation schemas for all tool inputs.
+- **errors.ts**: Custom error classes with error codes for specific failure modes.
+- **file-utils.ts**: Path resolution, validation, and node ID verification.
+- **logger.ts**: Structured logging with levels (debug, info, warn, error).
+
+### Testing
+
+Run the full test suite:
+
+```bash
+npm test
+```
+
+Run tests in watch mode:
+
+```bash
+npm run test:watch
+```
+
+Tests are organized by layer under `tests/`:
+
+```
+tests/
+├── core/                         # Unit tests for individual parsers
+│   ├── legacy-parser.test.ts     # XMind 8 (XML) format
+│   └── zen-parser.test.ts        # XMind Zen (JSON) format
+└── e2e/
+    └── mcp-integration.test.ts   # End-to-end MCP protocol flow
+```
+
+The framework is Jest with `ts-jest` (TypeScript out of the box). All tests run from a clean repo without any external network access — `.xmind` fixtures are generated or committed locally.
+
+### Building
+
+Compile TypeScript to JavaScript:
+
+```bash
+npm run build
+```
+
+Type check without building:
+
+```bash
+npm run lint
+```
+
+### Architecture Overview
+
+**Unified AST Model**: Both Zen and Legacy formats are normalized to a single tree structure (XMindNode), simplifying downstream processing.
+
+**Stateless Design**: All functions are pure and immutable. No server-side state is maintained between requests.
+
+**Token-Aware Output**: Tools estimate token consumption and suggest optimizations (search/branch extraction for large documents).
+
+**Error Guidance**: All errors include actionable messages helping users recover (invalid paths, missing nodes, etc.).
+
+**Performance**: Lazy evaluation where possible, depth limiting in branch extraction, incremental search results.
+
+## Limitations and Known Issues
+
+### Current Limitations
+
+1. **Hyperlinks**: Internal node references (href) are preserved but not resolved to actual node content
+2. **Relationships/Connectors**: Cross-node relationships are parsed but not included in Markdown output (available in JSON format)
+3. **Rich Text**: Multi-formatted text within notes is flattened to plain text
+4. **Images & Media**: Embedded images and media are not extracted or referenced
+5. **Styling**: Font colors, sizes, and other visual formatting are not preserved
+6. **Comments**: XMind 2024 comment annotations are not extracted
+
+### Token Limitations
+
+- Large mind maps (>50K nodes) may exceed Claude's context window even with branch extraction
+- Recommend using search to narrow scope for very large documents
+- JSON format uses more tokens than Markdown format (use Markdown when possible)
+
+### File Format Support
+
+- **Supported**: XMind 2023 (Zen format), XMind 8 (Legacy format)
+- **Experimental**: Earlier XMind versions may work but are untested
+
+### Error Recovery
+
+- Invalid file paths: Validates before parsing; suggests checking file permissions
+- Corrupted archives: Returns detailed error if .zip is invalid
+- Missing nodes: Returns friendly error suggesting search_xmind_nodes for available IDs
+- Large files: Suggests using search or branch extraction for better performance
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Error: Cannot find module '@modelcontextprotocol/sdk'` | You ran `node dist/index.js` before building | Run `npm install && npm run build` |
+| Claude Desktop doesn't list the three tools | Config path is wrong or `node` isn't on PATH | Re-check `claude_desktop_config.json`; the server only registers after a successful `connect()` on stdio |
+| `File not found: …` from the CLI | `~` not expanded on Windows shells | Pass an absolute path or use `path.resolve` upstream |
+| `nodeId` returns "Node not found" | The id was from a different file or session | Re-run `search_xmind_nodes` against the same file — ids are file-scoped |
+| Output blows past context window | Whole-document parse on a very large map | Use `search_xmind_nodes` first, then `get_xmind_node_branch` with a small `depth` |
+| `Failed to start MCP server` on launch | Another process already bound the stdio | Close any duplicate launches; MCP over stdio is single-consumer |
+| Corrupt archive errors | File isn't a real `.xmind` (renamed `.zip`, partial download) | Re-export from XMind; confirm `unzip -l file.xmind` lists `content.xml` or `manifest.json` |
+
+For anything not covered above, please open an issue (next section).
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues, feature requests, or questions:
+1. Check existing issues at <https://github.com/hhtczengjing/xmind-mcp/issues>
+2. Enable debug logging by setting `DEBUG=xmind-mcp` environment variable
+3. Run the test suite to verify your install: `npm test`
+4. When filing a new issue, include:
+   - Output of `node --version` and `npm --version`
+   - Exact command / tool call that failed and the full error text
+   - A minimal `.xmind` sample (anonymized if it contains sensitive content)
+
+## Changelog
+
+### Version 1.0.0 (Initial Release)
+
+- Full document parsing (Markdown and JSON formats)
+- Node search with breadcrumb paths
+- Branch extraction with depth limiting
+- Support for Zen and Legacy XMind formats
+- Token estimation and optimization suggestions
+- Comprehensive error handling and logging
+- MCP server integration for Claude and other clients

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * CLI tool for extracting and analyzing XMind files.
+ * Usage: node dist/cli.js <file-path> [options]
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}