atlas-tracker（阿特拉斯追踪器）

Atlas Tracker Skill

Atlas Tracker (app.redforester.com) is a graph-based knowledge system combining mindmaps, Kanban, and structured properties. This skill covers working with it via the OpenClaw AT plugin tools.

Setup

This skill requires two components to be installed and running:

1. AT MCP Server

A local Node.js server that proxies requests to the Atlas Tracker REST API.

The AT MCP server is maintained by the Atlas Tracker / RedForester team. Contact @gmdidro (Telegram) or visit app.redforester.com to request access.

Once you have the server files:

cd at-mcp/
yarn install
yarn build

# Run directly
node build/index.js

# Or run as a systemd user service (recommended)
cp at-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now at-mcp

The server listens on http://localhost:3222 by default.

Required environment variables (set in the service file or .env):

AT_BASE_URL=https://app.redforester.com/api
AUTH_HEADER=Basic <base64(username:md5(password))>
API_KEY=<your-local-api-key>
PORT=3222

2. OpenClaw Plugin

Copy the plugin file to your OpenClaw extensions directory:

mkdir -p ~/.openclaw/extensions/atlas-tracker/
cp index.ts ~/.openclaw/extensions/atlas-tracker/
cp openclaw.plugin.json ~/.openclaw/extensions/atlas-tracker/

Then configure the plugin in your openclaw.json:

{
  "plugins": {
    "atlas-tracker": {
      "serverUrl": "http://localhost:3222",
      "apiKey": "<your-local-api-key>"
    }
  }
}

OpenClaw will hot-reload the plugin automatically. Verify with:

openclaw status

You should see at_read_branch, at_create_branch, at_update_branch, at_get_node_types, at_read_attachments listed as available tools.

Core Concepts

• Map — a mindmap, identified by mapId (full UUID)
• Node — a single item in the map; has id, title (HTML), optional typeId, typeProperties, children[]
• Branch — a node + all its descendants
• Node type — a schema defining available properties (enum, text, htmltext, file, user, date, etc.)
• Title format — always HTML: <p>My title</p>, never plain text

Tool URLs

All tools take a nodeUrl in format:

https://app.redforester.com/mindmap?mapid=<UUID>&nodeid=<UUID>

Both mapid and nodeid must be full UUIDs (e.g. 3d7340e8-c763-4c9e-b049-4e900b7cf565), never partial.

Workflow

Reading a branch

Always read before modifying — never assume structure:

at_read_branch(nodeUrl) → returns node tree with children, types, properties

Finding the right node

If you don't know a nodeId, search via AT REST API:

POST /api/search  body: {"query": "...", "map_ids": ["<mapId>"]}
# Returns hits[].id — then at_read_branch each candidate to verify title

Creating branches

at_create_branch(parentNodeUrl, data)

data must include children: [] even for leaf nodes — required field.

Updating branches

at_update_branch(nodeUrl, delete[], update[], create[])

• create items: {parentNodeId, data: {title, typeId?, typeProperties?, children: []}}
• update items: {id, title?, typeProperties?, customProperties?}
• All three arrays required (pass [] if unused)

Node Types

Call at_get_node_types(nodeUrl) once per map session — types vary per map. Common types: Идея, Задача, Заметка, Категория, Проект, Этап, Заявка, Лид.

For typed nodes, typeProperties keys must exactly match the property names from at_get_node_types.

Critical Rules

1. Full UUIDs only — partial IDs (e.g. b319f356) will return 404
2. children: [] required — omitting it causes validation error on create
3. HTML titles — wrap in <p>...</p>; use <ul><li>...</li></ul> for lists
4. Read before write — always at_read_branch first to get current state and node IDs
5. 403 = permission denied — you can only write nodes owned by your AT account; read access may be broader
6. Large maps are slow — avoid full subtree reads on large maps; use search + targeted node reads instead

Common Patterns

Add children to existing node

1. at_read_branch to get parent nodeId and confirm it exists
2. at_update_branch with create: [{parentNodeId: "<id>", data: {..., children: []}}]

Batch create a solution tree

Use at_create_branch with nested children[] to create the full tree in one call.

Update node content

1. at_read_branch to get current node id and properties
2. at_update_branch with update: [{id, typeProperties: {key: "<html_value>"}}]

Create a link node (shortcut/reference)

A link node is a reference to an existing node — it appears in the map as a shortcut to the original. Useful for showing the same node in multiple places without duplicating it.

at_create_link_node(nodeUrl, originalNodeId)

• nodeUrl — URL of the parent where the link node should appear
• originalNodeId — UUID of the existing node to reference

Example: place a reference to node abc-123 under parent node def-456:

at_create_link_node(
  "https://app.redforester.com/mindmap?mapid=<mapId>&nodeid=def-456",
  "abc-123"
)

Upload a file to a node

Attach any file (PDF, Excel, Word, image) to an AT node:

at_upload_file(nodeUrl, filePath)

• filePath — absolute local path to the file
• Uploads via PUT /api/files, then attaches as a type_id=10 property
• Adds to existing files — does not overwrite

Work with comments

at_get_comments(nodeUrl)           → list all comments (with thread structure)
at_add_comment(nodeUrl, text, replyToCommentId?)  → add comment or reply to thread
at_update_comment(nodeUrl, commentId, text)       → edit comment text
at_delete_comment(nodeUrl, commentId)             → delete comment

Reference Files

• api-patterns.md — REST API search, auth, node fetch patterns (read when you need to search nodes or call AT API directly)
• node-types-guide.md — property type reference (htmltext, enum, file, user, date, etc.) and how to set them (read when creating/updating typed nodes)