# jinzcdev/markmap-mcp-server architecture

> Architecture diagram of the GitHub repository jinzcdev/markmap-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jinzcdev/markmap-mcp-server
- Repository: https://github.com/jinzcdev/markmap-mcp-server

## Overview

##### Project type and purpose
- This is a small, standalone Node.js/TypeScript CLI “server” implementing the Model Context Protocol (MCP). Its sole responsibility is to convert Markdown input into interactive mind maps (via markmap) and return MCP-compatible responses (JSON over stdio). It can also write the output to disk and optionally launch a browser preview.

##### File structure
- Top level:
- .github / .husky / CI & git hooks
- Dockerfile, smithery.yaml (packaging/publishing)
- src/…: TypeScript source subdivided into:
– common/registry-base.ts: base classes for a tool registry
– mcp/tools/: MCP tool implementations & registry
– markmap/createMarkmap.ts: core conversion logic
– utils/logger.ts: logging utility
– index.ts: CLI entry point
- tests/: vitest unit tests for the markmap service
- Config files: package.json, tsconfig.json, eslint.config.js, prettier.config.js, vitest.config.ts.

##### README for additional insights
- The README confirms it implements MCP over stdio, registers a tool named `markdown-to-mindmap`, reads Markdown, calls markmap under the hood, writes files to an output directory (`--output` or `MARKMAP_DIR`), then returns JSON with a link to the generated file, and can open the map in the browser.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actors
    MCPClient["MCP Client"]:::external
    Browser["Browser (system)"]:::external
    FS["File System"]:::external

    %% CLI Process Subgraph
    subgraph "CLI Process"
        CLIEntry["CLI Entry Point"]:::core
        ArgLoader["Argument & Env Loader"]:::util
        ProtocolAdapter["MCP Protocol Adapter"]:::core
        RegistryBase["Tool Registry Base Classes"]:::core
        ToolRegistry["Tool Registry & Dispatcher"]:::core
        MarkdownTool["Markdown-to-Mindmap Tool"]:::core
        MarkmapCore["Markmap Core Conversion Logic"]:::core
        Logger["Logger Utility"]:::util
    end

    %% Development & CI Subgraph
    subgraph "Development & CI"
        Tests["Unit Tests (Vitest)"]:::config
        TSConfig["TypeScript Config"]:::config
        Vitest["Vitest Config"]:::config
        PackagingWorkflows["Packaging & Release Workflows"]:::config
        DockerfileNode["Dockerfile"]:::config
        Smithery["smithery.yaml"]:::config
        CodeQuality["Code Quality Hooks & Configs"]:::config
    end

    %% Data Flow
    MCPClient -->|"stdin"| ProtocolAdapter
    CLIEntry -->|"invokes"| ArgLoader
    CLIEntry -->|"invokes"| ProtocolAdapter
    ProtocolAdapter -->|"parse args/env"| ArgLoader
    ProtocolAdapter -->|"dispatch"| ToolRegistry
    ToolRegistry -->|"extends"| RegistryBase
    ToolRegistry -->|"invoke tool"| MarkdownTool
    MarkdownTool -->|"calls"| MarkmapCore
    MarkmapCore -->|"generate SVG/JSON"| FS
    FS -->|"filepath"| ProtocolAdapter
    ProtocolAdapter -->|"stdout JSON"| MCPClient
    MarkdownTool -->|"spawn browser"| Browser
    %% Logging
    CLIEntry --> Logger
    ArgLoader --> Logger
    ProtocolAdapter --> Logger
    ToolRegistry --> Logger
    MarkdownTool --> Logger
    MarkmapCore --> Logger

    %% Click Events
    click CLIEntry "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/index.ts"
    click ArgLoader "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/mcp/tools/context.ts"
    click ProtocolAdapter "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/mcp/tools/tool-registry.ts"
    click RegistryBase "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/common/registry-base.ts"
    click MarkdownTool "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/mcp/tools/markmap-tools.ts"
    click MarkmapCore "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/markmap/createMarkmap.ts"
    click Logger "https://github.com/jinzcdev/markmap-mcp-server/blob/main/src/utils/logger.ts"
    click Tests "https://github.com/jinzcdev/markmap-mcp-server/blob/main/tests/services/markmap.test.ts"
    click TSConfig "https://github.com/jinzcdev/markmap-mcp-server/blob/main/tsconfig.json"
    click Vitest "https://github.com/jinzcdev/markmap-mcp-server/blob/main/vitest.config.ts"
    click PackagingWorkflows "https://github.com/jinzcdev/markmap-mcp-server/tree/main/.github/workflows"
    click DockerfileNode "https://github.com/jinzcdev/markmap-mcp-server/tree/main/Dockerfile"
    click Smithery "https://github.com/jinzcdev/markmap-mcp-server/blob/main/smithery.yaml"
    click CodeQuality "https://github.com/jinzcdev/markmap-mcp-server/tree/main/.husky/pre-commit"
    click CodeQuality "https://github.com/jinzcdev/markmap-mcp-server/blob/main/eslint.config.js"
    click CodeQuality "https://github.com/jinzcdev/markmap-mcp-server/blob/main/prettier.config.js"

    %% Styles
    classDef external fill:#BBE1FA,stroke:#333,stroke-width:1px;
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:1px;
    classDef util fill:#FFF9C4,stroke:#333,stroke-width:1px;
    classDef config fill:#E1BEE7,stroke:#333,stroke-width:1px;
```
