# mellos-mapping [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/GuangminJu/mellos-mapping  
**GitHub Stars:** 98  
**npm Downloads (last month):** 1831  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mellos-mapping

## Description
Live layered dependency map for bottom-up development, drawn by the agent in a terminal pane.

## Tools
Capabilities this server exposes over MCP:

- **mmap_declare** — Grow the map: title (`null` removes it), diagram kind, layer bands, lanes, groups (subsystems), nodes — with `status`, `evidence`, `detail`, `kind`, `group`, `lane`, `submap` — and edges, optionally labeled (all-or-nothing batch)
- **mmap_update** — Record progress **and revise**: status (`planned → in-progress → done` +evidence, `regressed`), relabel a node, move it to another band (`layer`), join/leave a group or lane, set a node kind or a `submap`; rename and re-rank bands (`layers`), relabel groups (`groups`) and lanes (`lanes`); `null` cl…
- **mmap_remove** — Revise: drop edges, nodes, groups, lanes, empty bands — and, with `pages`, whole pages, file and all (permanent; applied after this call's map edits)
- **mmap_view** — Render the current map as text inline (optional `zoom`, `-4`…`2`), ending with a `pages:` line naming every page the project has and which one you are looking at
- **mmap_read** — Structured page discovery, precise IDs, filtered/paginated reads, context and source changes
- **mmap_batch** — One-page mixed create/update/remove transaction with a revision check
- **mmap_setup** — Get/set the project's mapping policy — when maps open
- **mmap_open** — Put the map on your screen: open the pane, or retarget an open one to a `page` (`window: true` for the dedicated window). It answers with whether a pane actually reported in afterwards, not merely that a command ran — and it can never close one

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mellos-mapping": {
    "command": "npx",
    "args": ["-y","mellos-mapping"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/mellos-mapping/readme_