The Stages API provides read-only access to project stages and their tasks. Use it to list stages in a project or get a specific stage with its full task tree.

Capability required: stages:read

Frontend (iframe)

import { createResourceClient } from "@rightplace/sdk";

const rp = createResourceClient();
await rp.ready();

// List stages in a project
const stages = await rp.stages.list("project-id-123");
// -> [{ id: "abc", title: "Sprint 1", slug: "sprint-1", totalTasks: 12, doneTasks: 5, ... }]

// Get a specific stage with tasks
const stage = await rp.stages.get("project-id-123", "stage-id-abc");
// -> { id: "abc", title: "Sprint 1", tasks: [{ id: "t1", title: "Fix bug", status: "done", ... }] }

Backend (Node.js)

import { createResourceServer } from "@rightplace/sdk/server";

const server = createResourceServer({
  methods: {
    getProjectProgress: async (_params, { rp }) => {
      const stages = await rp.stages.list("project-id");
      return stages.map(s => ({
        title: s.title,
        progress: s.totalTasks > 0 ? s.doneTasks / s.totalTasks : 0,
      }));
    },
  },
});

server.start();

MCP

Full read + write over kanban-style stages and tasks:

Tool	Purpose	Permission
rightplace_list_stages	All stages in a project	stages:read
rightplace_get_stage	One stage with its full task tree	stages:read
rightplace_create_stage	New stage	stages:write
rightplace_add_stage_task	Append a task to a stage	stages:write
rightplace_update_stage_task	Update title / content / status / labels	stages:write
rightplace_stage_move_task	Re-order / re-parent a task	stages:write
rightplace_delete_stage_task	Remove a task	stages:write

RobinPath Bridge

# Read a stage's tasks
rightplace.list_stages {projectId: "proj_abc"} into $stages
rightplace.get_stage {projectId: "proj_abc", stageId: $stages[0].id} into $stage
for $t in $stage.tasks
  log $t.status $t.title
endfor

# Add + update a task
rightplace.add_stage_task {
  projectId: "proj_abc",
  stageId: $stages[0].id,
  title: "Ship v1.3",
  content: "Includes SRP + vault"
} into $task
rightplace.update_stage_task {
  projectId: "proj_abc",
  stageId: $stages[0].id,
  taskId: $task.id,
  status: "doing"
}

# Re-order
rightplace.stage_move_task {
  projectId: "proj_abc",
  stageId: $stages[0].id,
  taskId: $task.id,
  beforeTaskId: null
}

API Reference

rp.stages.list(projectId)

Returns all stages in a project.

Parameter	Type	Description
projectId	string	The project ID
Returns	Promise<StageSummary[]>	List of stage summaries

rp.stages.get(projectId, stageId)

Returns a specific stage with its full task tree.

Parameter	Type	Description
projectId	string	The project ID
stageId	string	The stage ID
Returns	Promise<StageDetail | null>	The stage with tasks, or null

StageSummary

Field	Type	Description
id	string	Stage ID
title	string	Stage title
slug	string	URL-safe slug
projectId	string	Owning project ID
totalTasks	number	Total task count
doneTasks	number	Completed task count
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)

StageDetail

Field	Type	Description
id	string	Stage ID
title	string	Stage title
description	string | null	Optional description
slug	string	URL-safe slug
version	number	Data version
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)
tasks	StageTask[]	Task tree

StageTask

Field	Type	Description
id	string	Task ID
title	string	Task title
content	string | null	Task body/description
status	string	Status (e.g. “todo”, “doing”, “done”)
labels	string[]	Assigned label IDs
createdAt	number	Unix timestamp (seconds)
updatedAt	number	Unix timestamp (seconds)
children	StageTask[]	Nested sub-tasks

Manifest Configuration

{
  "capabilities": [
    "stages:read"
  ]
}

Notes

• This API is read-only. Resources cannot create, update, or delete stages or tasks.
• Stages are stored as JSON files in the project’s rightplace/stages/ directory.
• The task tree can be nested (tasks with children).