Mellos Mapping MCP
An MCP server and terminal pane that draw a layered dependency map: a ghost design, the current step and verified nodes.
- 116 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- Writes map files into the project folder, and on Windows the hook adds the `mmap` command to the user PATH.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mellos-mappingDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- Writes map files into the project folder, and on Windows the hook adds the `mmap` command to the user PATH.
This is third-party code. Review the repository files before installing.
What it does
Mellos Mapping shows a live map of the system beside the chat that the agent builds bottom-up. Primitive layers sit at the bottom and dependency edges point only downward. Dashed ghost nodes mark what is designed, a spinner shows what is being built now, and solid green marks what is built and verified. Eight `mmap_*` tools, including `mmap_declare`, `mmap_read`, `mmap_open` and `mmap_remove`, write the map to the project's `.mellos/map.json`. A node turns green only with evidence such as a passing test, and a cracked foundation turns red. The server rejects only structural corruption: an upward edge or a duplicate rank.
Who it is for. Developers who have Claude Code or Codex build a system layer by layer and want to see what each node stands on and what is verified.
Good fit when
- An agent designs an architecture and the ghost diagram appears before the first line of code.
- You want to see what the agent is working on now and on which layers.
- After edits you check whether a foundation cracked: the node turns red.
- Work resumes in a new conversation through `mmap_read`.
Not a fit when
- You need a top-down task list: the map grows bottom-up and shows dependencies, not a schedule.
- The client lacks MCP support: without it there are no `mmap_*` tools.
- You need the workflow discipline in Cursor or Windsurf: the skill layer targets Claude Code and Codex.
Example request
Declare a ghost map of the game engine layers up front, open the pane and light up nodes as tests pass.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
MELLOS_MAPPING_CWD- Project folder for the map when the client starts the server elsewhere
MELLOS_MAPPING_NO_STAR- Value 1 turns off the one-time GitHub star reminder
MELLOS_MAPPING_TMUX_TARGET- tmux session or pane to open the map in, for example work:2.1
Limitations
Node.js 18.17 or newer on the 18.x line, or 20.3 and up, is required. The skill with the workflow discipline works only in Claude Code and Codex; other clients get the eight tools and the pane. On Linux and macOS the pane opens through tmux. If a client starts the server outside the project folder, set `MELLOS_MAPPING_CWD`. In the npm edition the pane shows a one-time reminder to star the repository on GitHub; turn it off with `MELLOS_MAPPING_NO_STAR=1`.
How to disable. Remove the plugin through the `/plugin` manager or delete the MCP entry from the client config. Clean the `.mellos/` folder in the project by hand.
FAQ
How do I install it in Claude Code?
Run `/plugin marketplace add GuangminJu/mellos-mapping`, then `/plugin install mellos-mapping@mellos-mapping`. Start a new conversation after installing.
How do I connect it in Cursor or Windsurf?
Add a stdio server with the command `npx -y mellos-mapping`. Open the pane with `npx -y -p mellos-mapping mellos-mapping-watch` from the project folder.
When does a node turn green?
Only with verification evidence such as a passing test. If later work cracks a foundation, the node turns red.
Where is the map stored?
In `.mellos/map.json` of the session working folder. Another folder is set with `MELLOS_MAPPING_CWD`.
Which platforms are supported?
Windows 10 and newer, macOS 13 and newer, Linux with glibc 2.28 or newer, on x64 or arm64. Native bindings ship with the release, so no compilation is needed.
Discussion
No questions or reviews yet.
Related
MCP serversA skill that maps a repository into meaningful blocks, walks through the code on that map step by step and highlights broken spots
DevLens analyzes a repo once and serves agents ranked files, call flow and change impact over MCP, no file-by-file reading
A local MCP server with call graphs and symbol search: the agent sees code structure and what an edit affects in advance.
Resolves which files import each other and what an edit will touch, and serves it to agents through hooks, MCP and a CLI
A plan-then-build pipeline for Claude Code and Codex: spec, small contracts, stage checks, review and lessons learned
codesight maps a project in one run: routes, DB models, dependencies, env vars. It gives the map to an agent as files or through an MCP server
README in short
Installation depends on the client: a plugin for Claude Code and omp, an installer for Codex, an extension for pi and stdio for the rest.