Mellos Mapping

What mellos-mapping does

The mellos-mapping MCP server gives an AI coding session a structured map of a system under development. The map is organized into dependency layers, with primitive or foundational components below higher-level components. It can represent nodes, edges, layer bands, lanes, groups, and multiple pages.

Nodes can carry a status, evidence, detail, kind, group, lane, and optional submap reference. The intended workflow makes planned design visible before implementation, marks current work separately, and uses evidence when work is considered done. A later change can mark previously completed work as regressed. The map is a ledger of project state rather than an automatic workflow enforcer; structural problems such as invalid dependency direction are the main conditions the tools reject.

How it works

An agent first uses mmap_declare to create or extend a page. It can provide the title, diagram type, layers, lanes, groups, nodes, and edges in one all-or-nothing batch. Progress and structural revisions go through mmap_update, which can change node status, evidence, labels, placement, membership, kind, or submap, as well as rename and reorder layers, groups, and lanes.

mmap_read provides structured discovery, exact identifiers, filtering, pagination, context, and source-change information. mmap_view renders the current page as text at an optional zoom level and identifies all project pages in its output. mmap_batch combines creates, updates, and removals for one page while checking a revision. mmap_remove deletes selected map elements or, through its page options, entire pages and their files permanently after the call's other edits.

The pane is controlled separately through mmap_open. It can open the map or retarget an existing pane to a selected page, including a dedicated window option. It reports whether the pane actually checked in afterward and cannot close it. mmap_setup reads or changes the project's policy for when maps open.

Setup and configuration

Installation requires Node.js 18.17 or newer on the 18.x line, or Node.js 20.3 or newer, plus the relevant host CLI on the system path. Supported platforms are Windows 10 or newer, macOS 13 or newer, and Linux with glibc 2.28 or newer on x64 or arm64. The documented installer requires no build step and configures the selected host after checking release integrity and the MCP tools.

For Claude Code, installation can use the marketplace commands or a clone followed by the installer. The repository also documents installations for ChatGPT desktop Codex mode, Codex CLI, omp, and pi, with host-specific packaging. A new conversation or session is required after installation. The first session asks when mapping should be enabled and stores that policy for later sessions.

Tools and capabilities

The mellos-mapping MCP server exposes these tools:

• mmap_declare creates or expands map structure.
• mmap_update records progress and revises existing structure.
• mmap_remove removes elements or pages.
• mmap_view produces an inline text rendering.
• mmap_read discovers and reads structured map data.
• mmap_batch applies mixed edits with a revision check.
• mmap_setup manages the map-opening policy.
• mmap_open opens or retargets the terminal pane.

The repository also supplies an mmap terminal command for opening a page or toggling the pane, with platform-specific installation behavior documented for Windows and Unix-like systems.

Limitations and notes

The map does not silently enforce the project's development discipline. It is designed to expose violations and progress visually while refusing structural corruption. The terminal pane is an adjunct to the host session, and its availability depends on the installed host, supported platform, Node.js version, and successful pane reporting.

Removing pages or files is permanent. Batch declarations are all-or-nothing, and mixed page transactions require a matching revision. The README documents MIT licensing and does not describe environment variables required to run the server.