paperclip/doc/TASKS-mcp.md

Task Management MCP Interface

Function contracts for the Paperclip task management system. Defines the operations available to agents (and external tools) via MCP. Refer to TASKS.md for the underlying data model.

All operations return JSON. IDs are UUIDs. Timestamps are ISO 8601. Issue identifiers (e.g. ENG-123) are accepted anywhere an issue id is expected.

---

Issues

list_issues

List and filter issues in the workspace.

Parameter	Type	Required	Notes
query	string	no	Free-text search across title and description
teamId	string	no	Filter by team
status	string	no	Filter by specific workflow state
stateType	string	no	Filter by state category: triage, backlog, unstarted, started, completed, cancelled
assigneeId	string	no	Filter by assignee (agent id)
projectId	string	no	Filter by project
parentId	string	no	Filter by parent issue (returns sub-issues)
labelIds	string[]	no	Filter to issues with ALL of these labels
priority	number	no	Filter by priority (0-4)
includeArchived	boolean	no	Include archived issues. Default: false
orderBy	string	no	created, updated, priority, due_date. Default: created
limit	number	no	Max results. Default: 50
after	string	no	Cursor for forward pagination
before	string	no	Cursor for backward pagination

Returns: { issues: Issue[], pageInfo: { hasNextPage, endCursor, hasPreviousPage, startCursor } }

---

get_issue

Retrieve a single issue by ID or identifier, with all relations expanded.

Parameter	Type	Required	Notes
id	string	yes	UUID or human-readable identifier (e.g. ENG-123)

Returns: Full Issue object including:

• state (expanded WorkflowState)
• assignee (expanded Agent, if set)
• labels (expanded Label[])
• relations (IssueRelation[] with expanded related issues)
• children (sub-issue summaries: id, identifier, title, state, assignee)
• parent (summary, if this is a sub-issue)
• comments (Comment[], most recent first)

---

create_issue

Create a new issue.

Parameter	Type	Required	Notes
title	string	yes
teamId	string	yes	Team the issue belongs to
description	string	no	Markdown
status	string	no	Workflow state. Default: team's default state
priority	number	no	0-4. Default: 0 (none)
estimate	number	no	Point estimate
dueDate	string	no	ISO date
assigneeId	string	no	Agent to assign
projectId	string	no	Project to associate with
milestoneId	string	no	Milestone within the project
parentId	string	no	Parent issue (makes this a sub-issue)
goalId	string	no	Linked goal/objective
labelIds	string[]	no	Labels to apply
sortOrder	number	no	Ordering within views

Returns: Created Issue object with computed fields (identifier, createdAt, etc.)

Side effects:

• If parentId is set, inherits projectId from parent (unless explicitly provided)
• identifier is auto-generated from team key + next sequence number

---

update_issue

Update an existing issue.

Parameter	Type	Required	Notes
id	string	yes	UUID or identifier
title	string	no
description	string	no
status	string	no	Transition to a new workflow state
priority	number	no	0-4
estimate	number	no
dueDate	string	no	ISO date, or null to clear
assigneeId	string	no	Agent id, or null to unassign
projectId	string	no	Project id, or null to remove from project
milestoneId	string	no	Milestone id, or null to clear
parentId	string	no	Reparent, or null to promote to standalone
goalId	string	no	Goal id, or null to unlink
labelIds	string[]	no	Replaces all labels (not additive)
teamId	string	no	Move to a different team
sortOrder	number	no	Ordering within views

Returns: Updated Issue object.

Side effects:

• Changing status to a state with category started sets startedAt (if not already set)
• Changing status to completed sets completedAt
• Changing status to cancelled sets cancelledAt
• Moving to completed/cancelled with sub-issue auto-close enabled completes open sub-issues
• Changing teamId re-assigns the identifier (e.g. ENG-42 → DES-18); old identifier preserved in previousIdentifiers

---

archive_issue

Soft-archive an issue. Sets archivedAt. Does not delete.

Parameter	Type	Required
id	string	yes

Returns: { success: true }

---

list_my_issues

List issues assigned to a specific agent. Convenience wrapper around list_issues with assigneeId pre-filled.

Parameter	Type	Required	Notes
agentId	string	yes	The agent whose issues to list
stateType	string	no	Filter by state category
orderBy	string	no	Default: priority
limit	number	no	Default: 50

Returns: Same shape as list_issues.

---

Workflow States

list_workflow_states

List workflow states for a team, grouped by category.

Parameter	Type	Required
teamId	string	yes

Returns: { states: WorkflowState[] } -- ordered by category (triage, backlog, unstarted, started, completed, cancelled), then by position within each category.

---

get_workflow_state

Look up a workflow state by name or ID.

Parameter	Type	Required	Notes
teamId	string	yes
query	string	yes	State name or UUID

Returns: Single WorkflowState object.

---

Teams

list_teams

List all teams in the workspace.

Parameter	Type	Required
query	string	no	Filter by name

Returns: { teams: Team[] }

---

get_team

Get a team by name, key, or ID.

Parameter	Type	Required	Notes
query	string	yes	Team name, key, or UUID

Returns: Single Team object.

---

Projects

list_projects

List projects in the workspace.

Parameter	Type	Required	Notes
teamId	string	no	Filter to projects containing issues from this team
status	string	no	Filter by status: backlog, planned, in_progress, completed, cancelled
includeArchived	boolean	no	Default: false
limit	number	no	Default: 50
after	string	no	Cursor

Returns: { projects: Project[], pageInfo }

---

get_project

Get a project by name or ID.

Parameter	Type	Required
query	string	yes

Returns: Single Project object including milestones[] and issue count by state category.

---

create_project

Parameter	Type	Required
name	string	yes
description	string	no
summary	string	no
leadId	string	no
startDate	string	no
targetDate	string	no

Returns: Created Project object. Status defaults to backlog.

---

update_project

Parameter	Type	Required
id	string	yes
name	string	no
description	string	no
summary	string	no
status	string	no
leadId	string	no
startDate	string	no
targetDate	string	no

Returns: Updated Project object.

---

archive_project

Soft-archive a project. Sets archivedAt. Does not delete.

Parameter	Type	Required
id	string	yes

Returns: { success: true }

---

Milestones

list_milestones

Parameter	Type	Required
projectId	string	yes

Returns: { milestones: Milestone[] } -- ordered by sortOrder.

---

get_milestone

Get a milestone by ID.

Parameter	Type	Required
id	string	yes

Returns: Single Milestone object with issue count by state category.

---

create_milestone

Parameter	Type	Required
projectId	string	yes
name	string	yes
description	string	no
targetDate	string	no
sortOrder	number	no

Returns: Created Milestone object.

---

update_milestone

Parameter	Type	Required
id	string	yes
name	string	no
description	string	no
targetDate	string	no
sortOrder	number	no

Returns: Updated Milestone object.

---

Labels

list_labels

List labels available for a team (includes workspace-level labels).

Parameter	Type	Required	Notes
teamId	string	no	If omitted, returns only workspace labels

Returns: { labels: Label[] } -- grouped by label group, ungrouped labels listed separately.

---

get_label

Get a label by name or ID.

Parameter	Type	Required	Notes
query	string	yes	Label name or UUID

Returns: Single Label object.

---

create_label

Parameter	Type	Required	Notes
name	string	yes
color	string	no	Hex color. Auto-assigned if omitted
description	string	no
teamId	string	no	Omit for workspace-level label
groupId	string	no	Parent label group

Returns: Created Label object.

---

update_label

Parameter	Type	Required
id	string	yes
name	string	no
color	string	no
description	string	no

Returns: Updated Label object.

---

Issue Relations

list_issue_relations

List all relations for an issue.

Parameter	Type	Required
issueId	string	yes

Returns: { relations: IssueRelation[] } -- each with expanded relatedIssue summary (id, identifier, title, state).

---

create_issue_relation

Create a relation between two issues.

Parameter	Type	Required	Notes
issueId	string	yes	Source issue
relatedIssueId	string	yes	Target issue
type	string	yes	related, blocks, blocked_by, duplicate

Returns: Created IssueRelation object.

Side effects:

• duplicate auto-transitions the source issue to a cancelled state
• Creating blocks from A->B implicitly means B is blocked_by A (both directions visible when querying either issue)

---

delete_issue_relation

Remove a relation between two issues.

Parameter	Type	Required
id	string	yes

Returns: { success: true }

---

Comments

list_comments

List comments on an issue.

Parameter	Type	Required	Notes
issueId	string	yes
limit	number	no	Default: 50

Returns: { comments: Comment[] } -- threaded (top-level comments with nested children).

---

create_comment

Add a comment to an issue.

Parameter	Type	Required	Notes
issueId	string	yes
body	string	yes	Markdown
parentId	string	no	Reply to an existing comment (thread)

Returns: Created Comment object.

---

update_comment

Update a comment's body.

Parameter	Type	Required
id	string	yes
body	string	yes

Returns: Updated Comment object.

---

resolve_comment

Mark a comment thread as resolved.

Parameter	Type	Required
id	string	yes

Returns: Updated Comment with resolvedAt set.

---

Initiatives

list_initiatives

Parameter	Type	Required	Notes
status	string	no	planned, active, completed
limit	number	no	Default: 50

Returns: { initiatives: Initiative[] }

---

get_initiative

Parameter	Type	Required
query	string	yes

Returns: Single Initiative object with expanded projects[] (summaries with status and issue count).

---

create_initiative

Parameter	Type	Required
name	string	yes
description	string	no
ownerId	string	no
targetDate	string	no
projectIds	string[]	no

Returns: Created Initiative object. Status defaults to planned.

---

update_initiative

Parameter	Type	Required
id	string	yes
name	string	no
description	string	no
status	string	no
ownerId	string	no
targetDate	string	no
projectIds	string[]	no

Returns: Updated Initiative object.

---

archive_initiative

Soft-archive an initiative. Sets archivedAt. Does not delete.

Parameter	Type	Required
id	string	yes

Returns: { success: true }

---

Summary

Entity	list	get	create	update	delete/archive
Issue	x	x	x	x	archive
WorkflowState	x	x	--	--	--
Team	x	x	--	--	--
Project	x	x	x	x	archive
Milestone	x	x	x	x	--
Label	x	x	x	x	--
IssueRelation	x	--	x	--	x
Comment	x	--	x	x	resolve
Initiative	x	x	x	x	archive

Total: 35 operations

Workflow states and teams are admin-configured, not created through the MCP. The MCP is primarily for agents to manage their work: create issues, update status, coordinate via relations and comments, and understand project context.