@zengjing/xmind-mcp 1.0.0

package/dist/tools/search-tool.js

@@ -0,0 +1,179 @@
+/**
+ * MCP Tool: search_xmind_nodes
+ * Search XMind nodes by keyword, label, or status marker.
+ */
+import { parseXMindFile } from '../core/parser.js';
+import { resolveFilePath } from '../utils/file-utils.js';
+import { isXMindError } from '../utils/errors.js';
+import { info, warn, error as logError } from '../utils/logger.js';
+/**
+ * MCP Tool definition for search_xmind_nodes.
+ * Enables keyword/label/marker filtering with breadcrumb path resolution.
+ */
+export const SEARCH_XMIND_TOOL = {
+    name: 'search_xmind_nodes',
+    description: 'Search for nodes in an XMind file by keyword (title/notes) or label. ' +
+        'Returns matching nodes with breadcrumb paths. ' +
+        'Useful for large mind maps to find specific topics without loading entire document.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Absolute file path to the .xmind file. Supports ~ for home directory expansion.',
+            },
+            query: {
+                type: 'string',
+                description: 'Search keyword or phrase to match in node titles, notes, or labels',
+            },
+            searchIn: {
+                type: 'array',
+                items: { type: 'string', enum: ['title', 'note', 'label'] },
+                default: ['title', 'note', 'label'],
+                description: 'Which fields to search in (default: all)',
+            },
+            caseSensitive: {
+                type: 'boolean',
+                default: false,
+                description: 'Enable case-sensitive matching',
+            },
+        },
+        required: ['path', 'query'],
+    },
+};
+/**
+ * Recursively search nodes and collect results with breadcrumb paths.
+ * Traverses the entire tree, building path from root to matching nodes.
+ *
+ * @param node - Current node being examined
+ * @param query - Search query string
+ * @param searchIn - Fields to search in (title, note, label)
+ * @param caseSensitive - Whether to use case-sensitive matching
+ * @param pathToRoot - Accumulated path from root (node IDs in reverse order)
+ * @returns Array of matching SearchResult objects with breadcrumb paths
+ */
+function searchNode(node, query, searchIn = ['title', 'note', 'label'], caseSensitive = false, pathToRoot = []) {
+    const results = [];
+    // Normalize query based on case sensitivity setting
+    const normalizeQuery = caseSensitive ? (s) => s : (s) => s.toLowerCase();
+    const normalizedQuery = normalizeQuery(query);
+    // Check title field
+    if (searchIn.includes('title')) {
+        const normalizedTitle = normalizeQuery(node.title);
+        if (normalizedTitle.includes(normalizedQuery)) {
+            results.push({
+                node,
+                matchType: 'title',
+                matchText: node.title,
+                pathToRoot: [node.id, ...pathToRoot],
+            });
+        }
+    }
+    // Check note field
+    if (searchIn.includes('note') && node.note) {
+        const normalizedNote = normalizeQuery(node.note);
+        if (normalizedNote.includes(normalizedQuery)) {
+            // Truncate matched text to 100 chars for readability
+            const matchText = node.note.substring(0, 100) + (node.note.length > 100 ? '...' : '');
+            results.push({
+                node,
+                matchType: 'note',
+                matchText,
+                pathToRoot: [node.id, ...pathToRoot],
+            });
+        }
+    }
+    // Check labels field
+    if (searchIn.includes('label') && node.labels) {
+        for (const label of node.labels) {
+            const normalizedLabel = normalizeQuery(label);
+            if (normalizedLabel.includes(normalizedQuery)) {
+                results.push({
+                    node,
+                    matchType: 'label',
+                    matchText: label,
+                    pathToRoot: [node.id, ...pathToRoot],
+                });
+            }
+        }
+    }
+    // Recursively search children, building path as we go down the tree
+    for (const child of node.children) {
+        results.push(...searchNode(child, query, searchIn, caseSensitive, [node.id, ...pathToRoot]));
+    }
+    return results;
+}
+/**
+ * Format search results as readable text output.
+ * Includes match count, breadcrumb paths, match types, and preview of matched text.
+ *
+ * @param results - Array of SearchResult objects to format
+ * @returns Formatted string suitable for LLM consumption
+ */
+function formatResults(results) {
+    if (results.length === 0) {
+        return 'No matches found.';
+    }
+    let output = `Found ${results.length} match${results.length !== 1 ? 'es' : ''}:\n\n`;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        // Reverse path to show root → ... → node order
+        const breadcrumb = result.pathToRoot.reverse().join(' > ');
+        output += `**${i + 1}. ${result.node.title}**\n`;
+        output += `   Path: ${breadcrumb}\n`;
+        output += `   Match: ${result.matchType} — "${result.matchText}"\n`;
+        // Include node note preview if available
+        if (result.node.note) {
+            const notePreview = result.node.note.substring(0, 80);
+            const noteSuffix = result.node.note.length > 80 ? '...' : '';
+            output += `   Note: ${notePreview}${noteSuffix}\n`;
+        }
+        output += '\n';
+    }
+    return output;
+}
+/**
+ * Executes the search_xmind_nodes tool.
+ * Parses the file, searches all sheets, and returns formatted results with breadcrumb paths.
+ *
+ * @param input - Tool input containing path, query, and optional search parameters
+ * @returns Formatted search results or error message
+ * @throws Does not throw; returns user-friendly error messages
+ */
+export async function executeSearchTool(input) {
+    try {
+        // Step 1: Validate and resolve file path
+        info('search_xmind_nodes tool invoked', { path: input.path, query: input.query });
+        const resolvedPath = resolveFilePath(input.path);
+        // Step 2: Parse the XMind file
+        const parsed = await parseXMindFile(resolvedPath);
+        info('File parsed successfully for search', { sheetCount: parsed.sheets.length });
+        // Step 3: Check if file has content
+        if (parsed.sheets.length === 0) {
+            return 'No sheets found in the XMind file.';
+        }
+        // Step 4: Search across all sheets
+        const allResults = [];
+        for (const sheet of parsed.sheets) {
+            allResults.push(...searchNode(sheet.rootTopic, input.query, input.searchIn, input.caseSensitive));
+        }
+        // Step 5: Format and return results
+        const formatted = formatResults(allResults);
+        info('Search completed', { resultCount: allResults.length, query: input.query });
+        return formatted;
+    }
+    catch (err) {
+        // Step 6: Error handling with user-friendly messages
+        if (isXMindError(err)) {
+            warn('XMind error during search', { code: err.code, message: err.message });
+            return `Error: ${err.message}`;
+        }
+        if (err instanceof Error) {
+            logError('Unexpected error in search_xmind_nodes', err);
+            return `Error: ${err.message}`;
+        }
+        logError('Unknown error in search_xmind_nodes', err);
+        return 'Error: An unknown error occurred while searching the file.';
+    }
+}
+//# sourceMappingURL=search-tool.js.map

package/dist/tools/search-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tool.js","sourceRoot":"","sources":["../../src/tools/search-tool.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Custom error classes for XMind parsing and MCP operations.
+ * All errors include actionable messages to guide LLM recovery.
+ */
+export declare class XMindError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export declare class FileNotFoundError extends XMindError {
+    constructor(filePath: string);
+}
+export declare class InvalidFormatError extends XMindError {
+    constructor(reason: string);
+}
+export declare class ParseError extends XMindError {
+    readonly details?: string | undefined;
+    constructor(message: string, details?: string | undefined);
+}
+export declare class SearchError extends XMindError {
+    constructor(message: string);
+}
+export declare class BranchExtractionError extends XMindError {
+    constructor(message: string);
+}
+export declare function isXMindError(error: unknown): error is XMindError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,UAAW,SAAQ,KAAK;aACU,IAAI,EAAE,MAAM;gBAA7C,OAAO,EAAE,MAAM,EAAkB,IAAI,GAAE,MAAsB;CAI1E;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,QAAQ,EAAE,MAAM;CAM7B;AAED,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,MAAM,EAAE,MAAM;CAM3B;AAED,qBAAa,UAAW,SAAQ,UAAU;aACK,OAAO,CAAC,EAAE,MAAM;gBAAjD,OAAO,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,MAAM,YAAA;CAM9D;AAED,qBAAa,WAAY,SAAQ,UAAU;gBAC7B,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,qBAAsB,SAAQ,UAAU;gBACvC,OAAO,EAAE,MAAM;CAG5B;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

package/dist/utils/errors.js

@@ -0,0 +1,41 @@
+/**
+ * Custom error classes for XMind parsing and MCP operations.
+ * All errors include actionable messages to guide LLM recovery.
+ */
+export class XMindError extends Error {
+    constructor(message, code = 'XMIND_ERROR') {
+        super(message);
+        this.code = code;
+        this.name = 'XMindError';
+    }
+}
+export class FileNotFoundError extends XMindError {
+    constructor(filePath) {
+        super(`File not found: ${filePath}. Please provide an absolute path to an existing .xmind file.`, 'FILE_NOT_FOUND');
+    }
+}
+export class InvalidFormatError extends XMindError {
+    constructor(reason) {
+        super(`Invalid .xmind format: ${reason}. The file may be corrupted or created with an unsupported XMind version. Try re-saving in XMind 2020+ (Zen format) or XMind 8.`, 'INVALID_FORMAT');
+    }
+}
+export class ParseError extends XMindError {
+    constructor(message, details) {
+        super(`Failed to parse .xmind: ${message}${details ? ` (${details})` : ''}. Check file integrity or try with a simpler mind map.`, 'PARSE_ERROR');
+        this.details = details;
+    }
+}
+export class SearchError extends XMindError {
+    constructor(message) {
+        super(`Search failed: ${message}`, 'SEARCH_ERROR');
+    }
+}
+export class BranchExtractionError extends XMindError {
+    constructor(message) {
+        super(`Failed to extract branch: ${message}`, 'BRANCH_EXTRACTION_ERROR');
+    }
+}
+export function isXMindError(error) {
+    return error instanceof XMindError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe,EAAkB,OAAe,aAAa;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,SAAI,GAAJ,IAAI,CAAwB;QAEvE,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,QAAgB;QAC1B,KAAK,CACH,mBAAmB,QAAQ,+DAA+D,EAC1F,gBAAgB,CACjB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAChD,YAAY,MAAc;QACxB,KAAK,CACH,0BAA0B,MAAM,iIAAiI,EACjK,gBAAgB,CACjB,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,UAAW,SAAQ,UAAU;IACxC,YAAY,OAAe,EAAkB,OAAgB;QAC3D,KAAK,CACH,2BAA2B,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,wDAAwD,EAC3H,aAAa,CACd,CAAC;QAJyC,YAAO,GAAP,OAAO,CAAS;IAK7D,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,UAAU;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,kBAAkB,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;IACrD,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,UAAU;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,6BAA6B,OAAO,EAAE,EAAE,yBAAyB,CAAC,CAAC;IAC3E,CAAC;CACF;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,UAAU,CAAC;AACrC,CAAC"}

package/dist/utils/file-utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * File system helpers for .xmind file handling.
+ */
+/**
+ * Validate that a file path points to an existing, readable .xmind file.
+ */
+export declare function validateXMindPath(filePath: string): Promise<void>;
+/**
+ * Read entire file into Buffer (suitable for ZIP extraction).
+ */
+export declare function readFileBuffer(filePath: string): Promise<Buffer>;
+/**
+ * Extract absolute path (resolve ~ and relative paths).
+ */
+export declare function resolveFilePath(filePath: string): string;
+/**
+ * Estimate token count for markdown output (rough heuristic: 1 token ≈ 4 chars).
+ * Helps LLMs decide whether to use search or branch extraction tools.
+ */
+export declare function estimateTokenCount(text: string): number;
+/**
+ * Check if a string looks like a valid UUID/node ID.
+ */
+export declare function isValidNodeId(id: string): boolean;
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/utils/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBvE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGtE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/utils/file-utils.js

@@ -0,0 +1,58 @@
+/**
+ * File system helpers for .xmind file handling.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { FileNotFoundError, InvalidFormatError } from './errors.js';
+/**
+ * Validate that a file path points to an existing, readable .xmind file.
+ */
+export async function validateXMindPath(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        if (!stat.isFile()) {
+            throw new InvalidFormatError(`${filePath} is not a file`);
+        }
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new FileNotFoundError(filePath);
+        }
+        if (err instanceof InvalidFormatError)
+            throw err;
+        throw new InvalidFormatError(`Cannot access file: ${err.message}`);
+    }
+    if (!filePath.endsWith('.xmind')) {
+        throw new InvalidFormatError('File must have .xmind extension');
+    }
+}
+/**
+ * Read entire file into Buffer (suitable for ZIP extraction).
+ */
+export async function readFileBuffer(filePath) {
+    await validateXMindPath(filePath);
+    return fs.readFile(filePath);
+}
+/**
+ * Extract absolute path (resolve ~ and relative paths).
+ */
+export function resolveFilePath(filePath) {
+    if (filePath.startsWith('~')) {
+        return path.join(process.env.HOME || '/root', filePath.slice(1));
+    }
+    return path.resolve(filePath);
+}
+/**
+ * Estimate token count for markdown output (rough heuristic: 1 token ≈ 4 chars).
+ * Helps LLMs decide whether to use search or branch extraction tools.
+ */
+export function estimateTokenCount(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Check if a string looks like a valid UUID/node ID.
+ */
+export function isValidNodeId(id) {
+    return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+//# sourceMappingURL=file-utils.js.map

package/dist/utils/file-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.js","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;YACnB,MAAM,IAAI,kBAAkB,CAAC,GAAG,QAAQ,gBAAgB,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,GAAG,YAAY,kBAAkB;YAAE,MAAM,GAAG,CAAC;QACjD,MAAM,IAAI,kBAAkB,CAAC,uBAAuB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,kBAAkB,CAAC,iCAAiC,CAAC,CAAC;IAClE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB;IACnD,MAAM,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Simple debug logger (optional, can be disabled in production).
+ */
+export declare function debug(message: string, data?: unknown): void;
+export declare function info(message: string, data?: unknown): void;
+export declare function warn(message: string, data?: unknown): void;
+export declare function error(message: string, err?: unknown): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAI3D;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAG1D;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAG1D;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAG1D"}

package/dist/utils/logger.js

@@ -0,0 +1,23 @@
+/**
+ * Simple debug logger (optional, can be disabled in production).
+ */
+const DEBUG = process.env.DEBUG === '1' || process.env.DEBUG === 'true';
+export function debug(message, data) {
+    if (!DEBUG)
+        return;
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] DEBUG:`, message, data ? JSON.stringify(data) : '');
+}
+export function info(message, data) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] INFO:`, message, data ? JSON.stringify(data) : '');
+}
+export function warn(message, data) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] WARN:`, message, data ? JSON.stringify(data) : '');
+}
+export function error(message, err) {
+    const timestamp = new Date().toISOString();
+    console.error(`[${timestamp}] ERROR:`, message, err);
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC;AAExE,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,IAAc;IACnD,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,IAAc;IAClD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,OAAe,EAAE,IAAc;IAClD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,GAAa;IAClD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,OAAO,CAAC,KAAK,CAAC,IAAI,SAAS,UAAU,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@zengjing/xmind-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for parsing and searching XMind mind maps (.xmind files). Enables Claude and other LLM applications to extract, search, and analyze mind map data.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "xmind-mcp": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "tsc --noEmit",
+    "parse": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "xmind",
+    "mindmap",
+    "mind-map",
+    "parser",
+    "search",
+    "model-context-protocol",
+    "claude",
+    "ai"
+  ],
+  "author": "zengjing <hhtczengjing@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hhtczengjing/xmind-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hhtczengjing/xmind-mcp/issues"
+  },
+  "homepage": "https://github.com/hhtczengjing/xmind-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "jszip": "^3.10.1",
+    "fast-xml-parser": "^4.3.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.2.0",
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "tsx": "^3.14.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "ts-jest": "^29.1.0"
+  }
+}