318 lines
5.2 KiB
Markdown
318 lines
5.2 KiB
Markdown
# MCP Tools Contract
|
|
|
|
Last updated: 2026-05-14.
|
|
|
|
## Position
|
|
|
|
The current Tasker / Plane fork does not expose a dedicated MCP server. It exposes REST endpoints and NODE.DC internal endpoints. The new module should expose MCP tools externally and translate those tool calls into validated Tasker adapter calls.
|
|
|
|
Codex should not call generic Tasker REST directly.
|
|
|
|
## Authentication
|
|
|
|
MCP clients authenticate to Agent Gateway with an opaque agent token.
|
|
|
|
Recommended transport options:
|
|
|
|
- HTTPS MCP endpoint for general clients;
|
|
- local stdio connector later if useful;
|
|
- REST fallback for non-MCP clients.
|
|
|
|
Token rules:
|
|
|
|
- token is opaque;
|
|
- server stores only token hash;
|
|
- token is scoped to one agent;
|
|
- token can be revoked immediately;
|
|
- token expires;
|
|
- owner blocked/annulled disables tokens.
|
|
|
|
## Tool list
|
|
|
|
### `tasker_get_agent_instructions`
|
|
|
|
Returns operating rules, allowed projects, card guide, and reporting expectations.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
workspace:read
|
|
```
|
|
|
|
### `tasker_list_projects`
|
|
|
|
Lists projects granted to the agent.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
project:read
|
|
```
|
|
|
|
### `tasker_get_project_context`
|
|
|
|
Returns project states, labels, members, and card-writing rules.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
project:read
|
|
```
|
|
|
|
### `tasker_search_issues`
|
|
|
|
Searches existing work items within granted projects.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:read
|
|
```
|
|
|
|
### `tasker_get_issue`
|
|
|
|
Returns one issue with description, structured blocks, labels, state, assignees, and comments summary.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:read
|
|
```
|
|
|
|
### `tasker_create_issue`
|
|
|
|
Creates a work item.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:create
|
|
```
|
|
|
|
Allowed fields:
|
|
|
|
```text
|
|
project_id
|
|
name
|
|
description_html
|
|
detail_layout
|
|
state_id
|
|
priority
|
|
label_ids
|
|
assignee_ids
|
|
start_date
|
|
target_date
|
|
parent_id
|
|
```
|
|
|
|
Validation:
|
|
|
|
- project must be granted;
|
|
- state must belong to project;
|
|
- labels must belong to project;
|
|
- assignees must be active project members;
|
|
- detail layout must match NODE.DC structured block schema.
|
|
|
|
### `tasker_update_issue`
|
|
|
|
Patches allowed issue fields.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:update
|
|
```
|
|
|
|
Allowed fields:
|
|
|
|
```text
|
|
name
|
|
description_html
|
|
detail_layout
|
|
priority
|
|
start_date
|
|
target_date
|
|
parent_id
|
|
```
|
|
|
|
Deletion, archive, and project transfer are not allowed.
|
|
|
|
### `tasker_move_issue`
|
|
|
|
Changes issue state and optional sort order.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:move
|
|
```
|
|
|
|
Allowed fields:
|
|
|
|
```text
|
|
state_id
|
|
sort_order
|
|
```
|
|
|
|
Validation:
|
|
|
|
- target state must belong to the same project;
|
|
- cancelled/completed moves are allowed only if the grant permits them.
|
|
|
|
### `tasker_set_issue_labels`
|
|
|
|
Sets or merges labels.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:label
|
|
```
|
|
|
|
Validation:
|
|
|
|
- labels must already exist in project for MVP;
|
|
- creating new labels can be added later under `label:create`.
|
|
|
|
### `tasker_assign_issue`
|
|
|
|
Sets assignees.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:assign
|
|
```
|
|
|
|
Validation:
|
|
|
|
- assignees must be active project members;
|
|
- if the user asks to add a workspace member to the project, use `tasker_add_existing_project_member` first.
|
|
|
|
### `tasker_add_existing_project_member`
|
|
|
|
Adds an existing workspace member to a granted project.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
project:member:add_existing
|
|
```
|
|
|
|
Validation:
|
|
|
|
- target user must already be an active workspace member;
|
|
- target user role cannot exceed workspace role;
|
|
- launcher-managed workspace rules must be respected;
|
|
- the request should be traceable to an explicit human instruction or reporting policy.
|
|
|
|
### `tasker_append_comment`
|
|
|
|
Adds a comment to an issue.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:comment
|
|
```
|
|
|
|
Allowed fields:
|
|
|
|
```text
|
|
comment_html
|
|
```
|
|
|
|
### `tasker_update_structured_blocks`
|
|
|
|
Replaces or patches NODE.DC structured blocks in `detail_layout`.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:structured_blocks:write
|
|
```
|
|
|
|
Supported blocks:
|
|
|
|
```text
|
|
text
|
|
checker
|
|
```
|
|
|
|
Canonical key:
|
|
|
|
```text
|
|
nodedc_structured_blocks
|
|
```
|
|
|
|
The tool should support high-level patch actions:
|
|
|
|
```text
|
|
append_text_block
|
|
append_checker
|
|
update_checker_item
|
|
replace_blocks
|
|
append_implementation_note
|
|
```
|
|
|
|
### `tasker_start_work_session`
|
|
|
|
Starts a reporting session for a project or issue.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:comment
|
|
```
|
|
|
|
This is mainly for enterprise reporting mode.
|
|
|
|
### `tasker_finish_work_session`
|
|
|
|
Finishes a reporting session and appends summary/validation notes.
|
|
|
|
Required scope:
|
|
|
|
```text
|
|
issue:comment
|
|
issue:structured_blocks:write
|
|
```
|
|
|
|
## Idempotency
|
|
|
|
All write tools must accept:
|
|
|
|
```text
|
|
idempotency_key
|
|
```
|
|
|
|
Agent Gateway stores result mapping and returns the prior result for duplicate keys.
|
|
|
|
## Denied tools
|
|
|
|
These should not exist in MVP:
|
|
|
|
```text
|
|
tasker_delete_issue
|
|
tasker_archive_issue
|
|
tasker_delete_comment
|
|
tasker_delete_label
|
|
tasker_delete_project
|
|
tasker_invite_workspace_member
|
|
tasker_raw_api_request
|
|
```
|
|
|
|
## Instruction pack
|
|
|
|
`tasker_get_agent_instructions` should include the effective card guide. The local Codex setup file should instruct the agent to call this tool before planning Tasker changes.
|
|
|
|
Minimum instruction:
|
|
|
|
```text
|
|
Before creating or updating Tasker cards, call tasker_get_agent_instructions.
|
|
Use Tasker for durable project planning, current architecture, planned architecture, stage checkers, implementation notes, and validation results.
|
|
Do not create multiple top-level cards for substeps of one product topic.
|
|
Do not delete or archive cards.
|
|
Do not operate outside granted projects.
|
|
```
|