ARCH - CODEX AGENTS: архитектура Agent Gateway и MCP-контракта

2026-05-14 19:11:23 +03:00
commit 97d98a7bcb
7 changed files with 1247 additions and 0 deletions
@@ -0,0 +1,317 @@
+# 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.
+```