Comments and files

9 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.

Tool	What it does	Kind
`get_file_store_status`	Whether this server has somewhere to put a file	Read · idempotent · no outside service
`list_comments`	List the comments on an entity	Read · idempotent · no outside service
`list_files`	List an entity’s attachments	Read · idempotent · no outside service
`list_inbox_comments`	Others’ comments across your workspace	Read · idempotent · no outside service
`add_comment`	Add a comment	Write · no outside service
`add_file_link`	Attach a link	Write · no outside service
`delete_comment`	Delete a comment	Write · destructive · idempotent · no outside service
`remove_file`	Remove an attachment	Write · destructive · idempotent · no outside service
`update_comment`	Edit a comment	Write · idempotent · no outside service

get_file_store_status

Whether this server has somewhere to put a file. configured means the deployment has a blob store, so an upload route answers with a token rather than a refusal. A picture or an attachment can be offered only when it is true.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/files/store`
CLI	`doers files get-file-store-status`
Touches	`files`
Operation	`getFileStoreStatus`

Input

This tool takes no arguments.

Output

Output fields

Field	Type	Allowed values	Description
`configured`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_file_store_status",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: files can be stored."
      }
    ],
    "structuredContent": {
      "configured": true
    }
  }
}

doers files get-file-store-status

list_comments

List the comments on an entity. Returns the comments on a task, project or area, oldest first. Attachments are not exposed by the API: only their count is.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/comments`
CLI	`doers comments list`
Touches	`areas`, `commentAttachments`, `comments`, `projects`, `tasks`, `user`
Operation	`listComments`

Input

Field	Type	Required	Default	Allowed values	Description
`parentKind` (query)	string	yes		`task`, `project`, `area`	Which kind of entity carries the comments.
`parentId` (query)	string	yes		UUID	Id of the parent task, project or area.
`limit` (query)	integer	no	`50`	1 to 100	How many comments to return.

Output

Output fields

Field	Type	Allowed values	Description
`comments`	object[]
`comments[].id`	string
`comments[].body`	string
`comments[].authorId`	string
`comments[].author`	object \| null
`comments[].author.id`	string
`comments[].author.name`	string \| null
`comments[].author.username`	string \| null
`comments[].author.image`	string \| null
`comments[].createdAt`	number		Epoch milliseconds.
`comments[].attachmentCount`	integer	-9007199254740991 to 9007199254740991
`comments[].preview`	object \| null
`comments[].preview.url`	string \| null
`comments[].preview.title`	string \| null
`comments[].preview.description`	string \| null
`comments[].preview.image`	string \| null
`comments[].preview.siteName`	string \| null
`comments[].canEdit`	boolean
`comments[].canRemove`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_comments",
    "arguments": {
      "parentKind": "task",
      "parentId": "e4712596-8b3b-4104-8fbc-4802d1e40a71",
      "limit": 50
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- Notes for the Acme launch."
      }
    ],
    "structuredContent": {
      "comments": [
        {
          "id": "c44bb2fd-5169-49da-878a-e0bfedcd5672",
          "body": "Notes for the Acme launch.",
          "authorId": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
          "author": {
            "id": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
            "name": "Acme",
            "username": "ada",
            "image": "https://acme.example/ada.png"
          },
          "createdAt": 1790069400000,
          "attachmentCount": 3,
          "preview": {
            "url": "https://acme.example/brief",
            "title": "Prepare the Acme quarterly review",
            "description": "Notes for the Acme launch.",
            "image": "https://acme.example/ada.png",
            "siteName": "Notes for the Acme launch."
          },
          "canEdit": true,
          "canRemove": true
        }
      ]
    }
  }
}

doers comments list e4712596-8b3b-4104-8fbc-4802d1e40a71 --parent-kind task --limit 50

list_files

List an entity’s attachments. The links attached to a task, project or area, newest first.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/files`
CLI	`doers files list`
Touches	`files`
Operation	`listFiles`

Input

Field	Type	Required	Default	Allowed values	Description
`parentKind` (query)	string	yes		`task`, `project`, `area`	Which kind of entity carries the comments.
`parentId` (query)	string	yes		UUID	Id of the parent task, project or area.

Output

Output fields

Field	Type	Description
`files`	object[]
`files[].id`	string
`files[].name`	string
`files[].url`	string
`files[].mime`	string \| null
`files[].createdAt`	number	Epoch milliseconds.
`files[].preview`	object \| null	OpenGraph card, filled in out of band. `null` until it is.
`files[].preview.url`	string \| null
`files[].preview.title`	string \| null
`files[].preview.description`	string \| null
`files[].preview.image`	string \| null
`files[].preview.siteName`	string \| null
`files[].canRemove`	boolean
`files[].external`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "parentKind": "task",
      "parentId": "e4712596-8b3b-4104-8fbc-4802d1e40a71"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [3b9c358f-36f0-431b-8ad3-e14f309c7cf1] Acme"
      }
    ],
    "structuredContent": {
      "files": [
        {
          "id": "3b9c358f-36f0-431b-8ad3-e14f309c7cf1",
          "name": "Acme",
          "url": "https://acme.example/brief",
          "mime": "Notes for the Acme launch.",
          "createdAt": 1790069400000,
          "preview": {
            "url": "https://acme.example/brief",
            "title": "Prepare the Acme quarterly review",
            "description": "Notes for the Acme launch.",
            "image": "https://acme.example/ada.png",
            "siteName": "Notes for the Acme launch."
          },
          "canRemove": true,
          "external": true
        }
      ]
    }
  }
}

doers files list --parent-kind task --parent-id e4712596-8b3b-4104-8fbc-4802d1e40a71

list_inbox_comments

Others’ comments across your workspace. Feeds the Inbox: the most recent comments left by someone else on your tasks, projects and areas: newest first, each with the entity it targets. Your own comments never appear here; they live in their threads.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/inbox/comments`
CLI	`doers comments list-inbox`
Touches	`areas`, `commentAttachments`, `comments`, `projects`, `tasks`, `user`
Operation	`listInboxComments`

Input

Field	Type	Required	Default	Allowed values	Description
`limit` (query)	integer	no	`50`	1 to 100	How many comments to return.

Output

Output fields

Field	Type	Allowed values	Description
`items`	object[]
`items[].comment`	object
`items[].comment.id`	string
`items[].comment.body`	string
`items[].comment.authorId`	string
`items[].comment.author`	object \| null
`items[].comment.author.id`	string
`items[].comment.author.name`	string \| null
`items[].comment.author.username`	string \| null
`items[].comment.author.image`	string \| null
`items[].comment.createdAt`	number		Epoch milliseconds.
`items[].comment.attachmentCount`	integer	-9007199254740991 to 9007199254740991
`items[].comment.preview`	object \| null
`items[].comment.preview.url`	string \| null
`items[].comment.preview.title`	string \| null
`items[].comment.preview.description`	string \| null
`items[].comment.preview.image`	string \| null
`items[].comment.preview.siteName`	string \| null
`items[].comment.canEdit`	boolean
`items[].comment.canRemove`	boolean
`items[].target`	object
`items[].target.kind`	string	`task`, `project`, `area`	Which kind of entity carries the comments.
`items[].target.id`	string	UUID	Identifier of a row.
`items[].target.title`	string

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_inbox_comments",
    "arguments": {
      "limit": 50
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- Prepare the Acme quarterly review: Notes for the Acme launch."
      }
    ],
    "structuredContent": {
      "items": [
        {
          "comment": {
            "id": "c44bb2fd-5169-49da-878a-e0bfedcd5672",
            "body": "Notes for the Acme launch.",
            "authorId": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
            "author": {
              "id": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
              "name": "Acme",
              "username": "ada",
              "image": "https://acme.example/ada.png"
            },
            "createdAt": 1790069400000,
            "attachmentCount": 3,
            "preview": {
              "url": "https://acme.example/brief",
              "title": "Prepare the Acme quarterly review",
              "description": "Notes for the Acme launch.",
              "image": "https://acme.example/ada.png",
              "siteName": "Notes for the Acme launch."
            },
            "canEdit": true,
            "canRemove": true
          },
          "target": {
            "kind": "task",
            "id": "34a04005-bcaf-406e-8c99-0bd9637d9fdb",
            "title": "Prepare the Acme quarterly review"
          }
        }
      ]
    }
  }
}

doers comments list-inbox --limit 50

add_comment

Add a comment. Posts a comment on a task, project or area. The first link in the text is unfurled in the background (OpenGraph preview) without blocking the response. On a shared task the commenter role is enough.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/comments`
CLI	`doers comments add`
Touches	`areas`, `commentAttachments`, `comments`, `projects`, `tasks`, `user`
Operation	`addComment`

Input

Field	Type	Required	Allowed values	Description
`parentKind`	string	yes	`task`, `project`, `area`	Which kind of entity carries the comments.
`parentId`	string	yes	UUID	Id of the parent task, project or area.
`body`	string	yes	1 to 10000 characters	The comment text, as markdown.

Output

Output fields

Field	Type	Allowed values	Description
`comment`	object
`comment.id`	string
`comment.body`	string
`comment.authorId`	string
`comment.author`	object \| null
`comment.author.id`	string
`comment.author.name`	string \| null
`comment.author.username`	string \| null
`comment.author.image`	string \| null
`comment.createdAt`	number		Epoch milliseconds.
`comment.attachmentCount`	integer	-9007199254740991 to 9007199254740991
`comment.preview`	object \| null
`comment.preview.url`	string \| null
`comment.preview.title`	string \| null
`comment.preview.description`	string \| null
`comment.preview.image`	string \| null
`comment.preview.siteName`	string \| null
`comment.canEdit`	boolean
`comment.canRemove`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_comment",
    "arguments": {
      "parentKind": "task",
      "parentId": "e4712596-8b3b-4104-8fbc-4802d1e40a71",
      "body": "Notes for the Acme launch."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: comment added."
      }
    ],
    "structuredContent": {
      "comment": {
        "id": "c44bb2fd-5169-49da-878a-e0bfedcd5672",
        "body": "Notes for the Acme launch.",
        "authorId": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
        "author": {
          "id": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
          "name": "Acme",
          "username": "ada",
          "image": "https://acme.example/ada.png"
        },
        "createdAt": 1790069400000,
        "attachmentCount": 3,
        "preview": {
          "url": "https://acme.example/brief",
          "title": "Prepare the Acme quarterly review",
          "description": "Notes for the Acme launch.",
          "image": "https://acme.example/ada.png",
          "siteName": "Notes for the Acme launch."
        },
        "canEdit": true,
        "canRemove": true
      }
    }
  }
}

doers comments add e4712596-8b3b-4104-8fbc-4802d1e40a71 "Notes for the Acme launch." --parent-kind task

add_file_link

Attach a link. Attaches an external link to a task, project or area. A minimal preview (the address and the site it points at) is stored immediately; the rest of the card is filled in out of band, so a site that refuses the request costs nothing.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/files`
CLI	`doers files add-file-link`
Touches	`files`
Operation	`addFileLink`

Input

Field	Type	Required	Allowed values	Description
`parentKind`	string	yes	`task`, `project`, `area`	Which kind of entity carries the comments.
`parentId`	string	yes	UUID	Id of the parent task, project or area.
`url`	string	yes	URL, 0 to 2048 characters	An `http` or `https` address.
`name`	string	no	0 to 200 characters	No description in the registry.

Output

Output fields

Field	Type	Description
`file`	object
`file.id`	string
`file.name`	string
`file.url`	string
`file.mime`	string \| null
`file.createdAt`	number	Epoch milliseconds.
`file.preview`	object \| null	OpenGraph card, filled in out of band. `null` until it is.
`file.preview.url`	string \| null
`file.preview.title`	string \| null
`file.preview.description`	string \| null
`file.preview.image`	string \| null
`file.preview.siteName`	string \| null
`file.canRemove`	boolean
`file.external`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add_file_link",
    "arguments": {
      "parentKind": "task",
      "parentId": "e4712596-8b3b-4104-8fbc-4802d1e40a71",
      "url": "https://acme.example/brief",
      "name": "Acme"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: “Acme” attached [3b9c358f-36f0-431b-8ad3-e14f309c7cf1]."
      }
    ],
    "structuredContent": {
      "file": {
        "id": "3b9c358f-36f0-431b-8ad3-e14f309c7cf1",
        "name": "Acme",
        "url": "https://acme.example/brief",
        "mime": "Notes for the Acme launch.",
        "createdAt": 1790069400000,
        "preview": {
          "url": "https://acme.example/brief",
          "title": "Prepare the Acme quarterly review",
          "description": "Notes for the Acme launch.",
          "image": "https://acme.example/ada.png",
          "siteName": "Notes for the Acme launch."
        },
        "canRemove": true,
        "external": true
      }
    }
  }
}

doers files add-file-link --parent-kind task --parent-id e4712596-8b3b-4104-8fbc-4802d1e40a71 --url https://acme.example/brief --name Acme

delete_comment

Delete a comment. Removes a comment and its attachments. The author may always delete their own; anyone else needs to own the entity the thread hangs off. This deletion is not reversible.


Kind	Write · destructive · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`DELETE https://api.doers.sh/v2/comments/{commentId}`
CLI	`doers comments delete`
Touches	`areas`, `commentAttachments`, `comments`, `projects`, `tasks`, `user`
Operation	`deleteComment`

Input

Field	Type	Required	Default	Allowed values	Description
`commentId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`commentId`	string

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_comment",
    "arguments": {
      "commentId": "c44bb2fd-5169-49da-878a-e0bfedcd5672"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: comment deleted."
      }
    ],
    "structuredContent": {
      "commentId": "c44bb2fd-5169-49da-878a-e0bfedcd5672"
    }
  }
}

doers comments delete c44bb2fd-5169-49da-878a-e0bfedcd5672

remove_file

Remove an attachment. Detaches a link. Nothing else is touched.


Kind	Write · destructive · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`DELETE https://api.doers.sh/v2/files/{fileId}`
CLI	`doers files remove`
Touches	`files`
Operation	`removeFile`

Input

Field	Type	Required	Default	Allowed values	Description
`fileId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`removed`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "remove_file",
    "arguments": {
      "fileId": "3b9c358f-36f0-431b-8ad3-e14f309c7cf1"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: attachment removed."
      }
    ],
    "structuredContent": {
      "removed": true
    }
  }
}

doers files remove 3b9c358f-36f0-431b-8ad3-e14f309c7cf1

update_comment

Edit a comment. Rewrites the text of a comment. Only its author may edit it: owning the task, project or area the thread hangs off is not enough, because a thread is a record of who said what.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/comments/{commentId}`
CLI	`doers comments update`
Touches	`areas`, `commentAttachments`, `comments`, `projects`, `tasks`, `user`
Operation	`updateComment`

Input

Field	Type	Required	Default	Allowed values	Description
`commentId` (path)	string	yes		UUID	Identifier of a row.
`body`	string	yes		1 to 10000 characters	The replacement text, as markdown.

Output

Output fields

Field	Type	Allowed values	Description
`comment`	object
`comment.id`	string
`comment.body`	string
`comment.authorId`	string
`comment.author`	object \| null
`comment.author.id`	string
`comment.author.name`	string \| null
`comment.author.username`	string \| null
`comment.author.image`	string \| null
`comment.createdAt`	number		Epoch milliseconds.
`comment.attachmentCount`	integer	-9007199254740991 to 9007199254740991
`comment.preview`	object \| null
`comment.preview.url`	string \| null
`comment.preview.title`	string \| null
`comment.preview.description`	string \| null
`comment.preview.image`	string \| null
`comment.preview.siteName`	string \| null
`comment.canEdit`	boolean
`comment.canRemove`	boolean

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_comment",
    "arguments": {
      "commentId": "c44bb2fd-5169-49da-878a-e0bfedcd5672",
      "body": "Notes for the Acme launch."
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: comment edited."
      }
    ],
    "structuredContent": {
      "comment": {
        "id": "c44bb2fd-5169-49da-878a-e0bfedcd5672",
        "body": "Notes for the Acme launch.",
        "authorId": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
        "author": {
          "id": "63648586-8971-4ac5-8ca3-3c4a0e1800a8",
          "name": "Acme",
          "username": "ada",
          "image": "https://acme.example/ada.png"
        },
        "createdAt": 1790069400000,
        "attachmentCount": 3,
        "preview": {
          "url": "https://acme.example/brief",
          "title": "Prepare the Acme quarterly review",
          "description": "Notes for the Acme launch.",
          "image": "https://acme.example/ada.png",
          "siteName": "Notes for the Acme launch."
        },
        "canEdit": true,
        "canRemove": true
      }
    }
  }
}

doers comments update c44bb2fd-5169-49da-878a-e0bfedcd5672 "Notes for the Acme launch."

MCP server

Tool reference

Comments and files

get_file_store_status

Input

Output

Example

list_comments

Input

Output

Example

list_files

Input

Output

Example

list_inbox_comments

Input

Output

Example

add_comment

Input

Output

Example

add_file_link

Input

Output

Example

delete_comment

Input

Output

Example

remove_file

Input

Output

Example

update_comment

Input

Output

Example

​get_file_store_status

​Input

​Output

​Example

​list_comments

​Input

​Output

​Example

​list_files

​Input

​Output

​Example

​list_inbox_comments

​Input

​Output

​Example

​add_comment

​Input

​Output

​Example

​add_file_link

​Input

​Output

​Example

​delete_comment

​Input

​Output

​Example

​remove_file

​Input

​Output

​Example

​update_comment

​Input

​Output

​Example

get_file_store_status

Input

Output

Example

list_comments

Input

Output

Example

list_files

Input

Output

Example

list_inbox_comments

Input

Output

Example

add_comment

Input

Output

Example

add_file_link

Input

Output

Example

delete_comment

Input

Output

Example

remove_file

Input

Output

Example

update_comment

Input

Output

Example