# 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.
```