# MCP Tools Contract

Last updated: 2026-07-18.

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

Current implementation status:

- Agent Gateway exposes `/mcp` as JSON-RPC over HTTP.
- Implemented MCP methods: `initialize`, `ping`, `tools/list`, `tools/call`.
- `tools/list` returns only tools allowed by the authenticated agent session scopes.
- `tools/call` uses the same product runtime as REST tool endpoints.
- Server-sent event streaming is intentionally not required for the first product slice.

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

Current route:

```text
POST /mcp
POST /ontology-mcp
```

`/mcp` accepts only an Ops-purpose token. `/ontology-mcp` accepts only the
separately minted Ontology-purpose token and proxies the read-only Ontology MCP.
The two endpoints, credentials, and MCP server entries remain independent.

Required request headers for authenticated tool calls:

```text
Authorization: Bearer <agent-token>
Accept: application/json
MCP-Protocol-Version: 2025-06-18
```

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,
full comment bodies, and attachment metadata. The Tasker adapter caps comments at
1000 and reports truncation explicitly.

Required scope:

```text
issue:read
```

### `tasker_create_project`

Creates or idempotently resolves a project inside an explicitly granted
workspace. Only a long-lived agent-scoped session can call it; token-scoped run
grants cannot expand themselves. Tasker revalidates that the human owner is an
active workspace administrator before creating the project. The new project is
then added to the same agent's grants so subsequent card tools can address it.

Required scope:

```text
project:create
```

Allowed fields:

```text
workspace_slug
name
identifier (optional)
description (optional)
idempotency_key
```

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

Uploads a bounded file to an issue through Tasker's existing FileAsset and
S3/MinIO storage path. The MCP accepts base64 content only: it never reads a
client or server filesystem path and never fetches a remote URL. Raw content is
limited to 5 MiB and Tasker rechecks MIME allowlists, workspace storage limits,
project quota, and content deduplication.

Required scope:

```text
issue:attachment:write
```

Allowed fields:

```text
project_id
issue_id
file_name
content_type
content_base64
idempotency_key
```

### `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 requires this value for all write tools. The key is scoped by agent, hashed together with the tool name and normalized arguments, and stored with a processing/completed state.

Behavior:

- first successful request stores the tool result for 24 hours;
- duplicate key with identical arguments returns the stored result and does not call Tasker again;
- duplicate key with different arguments returns `idempotency_key_conflict`;
- duplicate key while the first request is still processing returns `idempotency_key_in_progress`;
- failed writes release the key so the same operation can be retried.

## 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
tasker_attach_server_path
tasker_attach_remote_url
```

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

Agent Gateway also exposes:

```text
GET /api/v1/agent-session/setup
```

This endpoint is authenticated by the same bearer token and returns:

- MCP server config template with `<agent-token>` placeholder;
- tools available to the current agent grants;
- generated AGENTS.md content with NODE.DC Tasker operating rules;
- no raw token echo.

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