From a54e921d39b76e5d6033a202dd2fc6674f5c34f3 Mon Sep 17 00:00:00 2001 From: Matvey-Kuk Date: Wed, 20 Aug 2025 09:12:30 +0100 Subject: [PATCH] Add MCP Catalog Trust Score badge --- .gitignore 2 | 36 +++++ LICENSE 2 | 21 +++ README 2.md | 343 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + pyproject 2.toml | 37 +++++ 5 files changed, 438 insertions(+) create mode 100644 .gitignore 2 create mode 100644 LICENSE 2 create mode 100644 README 2.md create mode 100644 pyproject 2.toml diff --git a/.gitignore 2 b/.gitignore 2 new file mode 100644 index 0000000..14bac72 --- /dev/null +++ b/.gitignore 2 @@ -0,0 +1,36 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# Distribution / packaging +dist/ +build/ +*.egg-info/ + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ + +# Virtual environments +venv/ +env/ +ENV/ + +# IDE files +.idea/ +.vscode/ +*.swp +*.swo + +# OS specific files +.DS_Store +Thumbs.db diff --git a/LICENSE 2 b/LICENSE 2 new file mode 100644 index 0000000..990061c --- /dev/null +++ b/LICENSE 2 @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 YuChenSSR + +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. diff --git a/README 2.md b/README 2.md new file mode 100644 index 0000000..08bf34f --- /dev/null +++ b/README 2.md @@ -0,0 +1,343 @@ +# Mindmap MCP Server + +[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/YuChenSSR/mindmap-mcp-server)](https://archestra.ai/mcp-catalog/yuchenssr__mindmap-mcp-server) +

+ mindmap_mcp +

+ +A Model Context Protocol (MCP) server for converting Markdown content to interactive mindmaps. + + + +## Installation + +```bash +pip install mindmap-mcp-server +``` + +Or using `uvx`: + +```bash +uvx mindmap-mcp-server +``` +Or using `docker` safer and easier. + +## Attention + +Three installation methods have been successfully tested on macOS and Linux. + +For Windows users experiencing issues with `npx` for this MCP, consider using the Docker method. Alternatively, if you use Visual Studio Code, the ["Markmap"](https://marketplace.visualstudio.com/items?itemName=gera2ld.markmap-vscode) extension offers a potentially simpler solution than navigating command-line tools. + +--- + +If you're experiencing unresolved issues, you can use my recent system prompt as a Mindmap Assistant instead of using this MCP server. + +
+Using my system prompt instead of using this MCP server + +``` +You are a specialized assistant that generates HTML code for interactive markdown-based mind maps (markmaps). When a user sends you content, respond with a complete HTML document that displays their content as a markmap visualization. +If artifact tool is turned on, you can use the artifact. + +Follow these requirements: +1. Use the markmap-autoloader library (version 0.18 or latest stable version) +2. Format the HTML exactly according to the template below +3. Replace the demo content in the template with the user's content, preserving their hierarchical structure +4. Maintain the markmap configuration options (maxWidth: 300, colorFreezeLevel: 2) +5. If the user doesn't provide markdown formatting (# for headings), format their content appropriately with main topics using # and subtopics using ## + +Template to follow: + + + + + + + + Markmap + + + + +
+ +
+ + +``` + +*Visualization options:* (If formulas or symbols don’t display correctly, download the HTML file and open it in a browser.) +1. View the mindmap in artifacts (if available): +![system_prompt_artifact](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-05-20/1i9LIfoVRdCV97HM.png) + +2. Render the HTML file as a mindmap: +![system_prompt_render](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-05-20/qv4ActvFaphc64oA.png) + +
+ +--- + +## Prerequisites + +This package requires Node.js to be installed when using command `python` or `uvx` to run the server. + + + +## Usage + +### With Claude Desktop or other MCP clients + +Add this server to your `claude_desktop_config.json`: + +
+ + using `uvx`: + +```json +{ + "mcpServers": { + "mindmap": { + "command": "uvx", + "args": ["mindmap-mcp-server", "--return-type", "html"] + } + } +} +``` + +or + +recommended: + +```json +{ + "mcpServers": { + "mindmap": { + "command": "uvx", + "args": ["mindmap-mcp-server", "--return-type", "filePath"] + } + } +} +``` + +we use `--return-type` to specify the return type of the mindmap content, you can choose `html` or `filePath` according to your needs. +`html` will return the entire HTML content of the mindmap, which you can preview in your AI client's artifact; + +![return_html_content](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-20/qAEimhwZJDQ3NBLs.png) + +![html_preview](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-21/SujqY2L5lhWSHWvi.png) + + +`filePath` will save the mindmap to a file and return the file path,which you can open in your browser. It can **save your tokens** ! + +![generate_file](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-20/WDqlWhsoiAYpLmBF.png) + +![file_to_open](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-20/jfRIDc5mfvNtKykC.png) + +
+ +
+using `python`: + +Using [a specific Python file](https://github.com/YuChenSSR/mindmap-mcp-server/blob/main/mindmap_mcp_server/server.py) in this repository: + + +```json +{ + "mcpServers": { + "mindmap": { + "command": "python", + "args": ["/path/to/your/mindmap_mcp_server/server.py", "--return-type", "html"] + } + } +} +``` + +or + +```json +{ + "mcpServers": { + "mindmap": { + "command": "python", + "args": ["/path/to/your/mindmap_mcp_server/server.py", "--return-type", "filePath"] + } + } +} +``` +we use `--return-type` to specify the return type of the mindmap content, you can choose `html` or `filePath` according to your needs. see using \`uvx\` for more details. + +
+ +
+ +using `docker`: + +First, you pull the image: + +```bash +docker pull ychen94/mindmap-converter-mcp +``` + +Second, set the server: + +```json +{ + "mcpServers": { + "mindmap-converter": { + "command": "docker", + "args": ["run", "--rm", "-i", "-v", "/path/to/output/folder:/output", "ychen94/mindmap-converter-mcp:latest"] + } + } +} +``` +⚠️ Replace `/path/to/output/folder` with an actual path on your system where you want to save mind maps, such as `/Users/username/Downloads` on macOS or `C:\\Users\\username\\Downloads` on Windows. + +**Tools Provided in the docker container** +The server provides the following MCP tools: +1. **markdown-to-mindmap-content** +Converts Markdown to an HTML mind map and returns the entire HTML content. +You don't use the args: `-v` and `/path/to/output/folder:/output` in the command `docker`. +**Parameters**: + • markdown (string, required): The Markdown content to convert + • toolbar (boolean, optional): Whether to show the toolbar (default: true) +**Best for**: Simple mind maps where the HTML content size isn't a concern. And you can use **artifact** in your AI client to preview the mindmap. +2. **markdown-to-mindmap-file** +Converts Markdown to an HTML mind map and saves it to a file in the mounted directory. +**Parameters**: + • markdown (string, required): The Markdown content to convert + • filename (string, optional): Custom filename (default: auto-generated timestamp name) + • toolbar (boolean, optional): Whether to show the toolbar (default: true) +**Best for**: Complex mind maps or when you want to **save the tokens** for later use. +you can open the html file in your browser to view the mindmap. Also you can use the [iterm-mcp-server](https://github.com/ferrislucas/iterm-mcp) or other terminals' mcp servers to open the file in your browser without interrupting your workflow. + +
+ +### Troubleshooting + +**File Not Found** +If your mind map file isn't accessible: + 1 Check that you've correctly mounted a volume to the Docker container + 2 Ensure the path format is correct for your operating system + 3 Make sure Docker has permission to access the directory + +**Docker Command Not Found** + 1 Verify Docker is installed and in your PATH + 2 Try using the absolute path to Docker + +**Server Not Appearing in Claude** + 1 Restart Claude for Desktop after configuration changes + 2 Check Claude logs for connection errors + 3 Verify Docker is running + +**Advanced Usage +Using with Other MCP Clients** +This server works with any MCP-compatible client, not just Claude for Desktop. The server implements the Model Context Protocol (MCP) version 1.0 specification. + + + + +## Features + +This server provides a tool for converting Markdown content to mindmaps using the `markmap-cli` library: + +- Convert Markdown to interactive mindmap HTML +- Option to create offline-capable mindmaps +- Option to hide the toolbar +- Return either HTML content or file path + +## Example + +In Claude, you can ask: + +1. +"**give a mindmap for the following markdown code, using a mindmap tool:** +``` +# Project Planning +## Research +### Market Analysis +### Competitor Review +## Design +### Wireframes +### Mockups +## Development +### Frontend +### Backend +## Testing +### Unit Tests +### User Testing +``` +" + + +if you want to save the mindmap to a file, and then open it in your browser using the iTerm MCP server: + +2. +"**give a mindmap for the following markdown input_code using a mindmap tool, +after that,use iterm to open the generated html file. +input_code:** +``` +markdown content +``` +" + + +3. +"**Think about the process of putting an elephant into a refrigerator, and provide a mind map. Open it with a terminal.**" + +
+ +see the result + +![aiworkflow](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-22/QUjGnpmUcPfd3lBI.png) + +![mindmapinbrowser](https://raw.githubusercontent.com/YuChenSSR/pics/master/imgs/2025-03-22/w7DZ4shFhLoQZruq.png) + +
+ + +**and more** + + +## License + +This project is licensed under the MIT License. +For more details, please see the LICENSE file in [this project repository](https://github.com/YuChenSSR/mindmap-mcp-server) + +--- + +If this project is helpful to you, please consider giving it a Star ⭐️ + +The advancement of technology ought to benefit all individuals rather than exploit the general populace. diff --git a/README.md b/README.md index 7f7773b..08bf34f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # Mindmap MCP Server +[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/YuChenSSR/mindmap-mcp-server)](https://archestra.ai/mcp-catalog/yuchenssr__mindmap-mcp-server)

mindmap_mcp

diff --git a/pyproject 2.toml b/pyproject 2.toml new file mode 100644 index 0000000..7145266 --- /dev/null +++ b/pyproject 2.toml @@ -0,0 +1,37 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "mindmap-mcp-server" +version = "0.1.1" +description = "MCP server for converting Markdown to mindmaps" +readme = "README.md" +requires-python = ">=3.10" +license = {file = "LICENSE"} +authors = [ + {name = "YuChenSSR"} +] +keywords = ["mcp", "mindmap", "markdown", "claude", "ai"] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Topic :: Software Development :: Libraries", +] +dependencies = [ + "mcp>=1.2.0", +] + +[project.urls] +"Homepage" = "https://github.com/YuChenSSR/mindmap-mcp-server" +"Bug Tracker" = "https://github.com/YuChenSSR/mindmap-mcp-server/issues" + +[project.scripts] +mindmap-mcp-server = "mindmap_mcp_server.server:main" + +[tool.hatch.build.targets.wheel] +packages = ["mindmap_mcp_server"]