Proposal: update specification — MCPToolAdapter MCP 1.4.0 error extraction #3078

Closed
opened 2026-04-05 05:24:38 +00:00 by freemo · 3 comments
Owner

Spec Update Proposal

This proposal covers one spec gap discovered by comparing recently merged PRs against docs/specification.md.

(Gap 1 — agents plan list --namespace — has been removed per @freemo's feedback: the --namespace option is being removed from the source code and will not be added to the specification.)


Gap 2: MCPToolAdapter error extraction protocol not specified (MCP 1.4.0)

Triggered by: PR #2600fix(mcp): extract error message from content[0].text per MCP 1.4.0 protocol

What changed in the implementation:
PR #2600 fixed MCPToolAdapter.invoke() to extract error messages from content[0].text (the MCP 1.4.0 standard location) rather than from a non-standard error key. The fix includes safe guards: isinstance(content, list) and len(content) > 0 before accessing content[0], with "unknown error" as the fallback when content is absent or malformed.

What spec section needs updating:

Section: MCPToolAdapter execute() (lines 21931–21939)

Current text:

3. **execute()**: Translates a `Tool.execute(params, ctx)` call into an MCP `tools/call` JSON-RPC request. Before dispatching:
   - Rewrites file paths to sandbox-relative paths
   - Validates params against `inputSchema`
   - Checks capability metadata against plan access policy
   - Creates a checkpoint if the tool is marked checkpointable

   After the MCP tool returns its `content[]` response, the adapter:
   - Parses the result into the CleverAgents `Result` format
   - Records any resource mutations as `Change` objects in the plan's `ChangeSet`

Proposed addition to the "After the MCP tool returns" bullet list:

   After the MCP tool returns its `content[]` response, the adapter:
   - Parses the result into the CleverAgents `Result` format
   - For error responses (`isError: true`), extracts the error message from `content[0].text` per the MCP 1.4.0 protocol; falls back to `"unknown error"` when `content` is absent or malformed
   - Records any resource mutations as `Change` objects in the plan's `ChangeSet`

Rationale: The MCP 1.4.0 protocol places error messages in content[0].text, not in a top-level error key. The spec previously said "Parses the result" without specifying how errors are extracted. This is a genuine implementation improvement that discovered a protocol compliance requirement — the spec should document the correct extraction path so future implementors don't repeat the original mistake.


Scope

Sections affected:

  1. ## Infrastructure Layer > MCPToolAdapter > execute() — error extraction bullet

Classification

Minor spec update — this is a clarification/addition that aligns the spec with correct, already-merged implementation. No architectural changes.


@freemo — Gap 1 has been removed per your feedback. This proposal now covers only Gap 2 (MCPToolAdapter MCP 1.4.0 error extraction). Please review and approve if you're satisfied.


Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Spec Update Proposal This proposal covers one spec gap discovered by comparing recently merged PRs against `docs/specification.md`. *(Gap 1 — `agents plan list --namespace` — has been removed per @freemo's feedback: the `--namespace` option is being removed from the source code and will not be added to the specification.)* --- ### Gap 2: MCPToolAdapter error extraction protocol not specified (MCP 1.4.0) **Triggered by**: PR #2600 — `fix(mcp): extract error message from content[0].text per MCP 1.4.0 protocol` **What changed in the implementation**: PR #2600 fixed `MCPToolAdapter.invoke()` to extract error messages from `content[0].text` (the MCP 1.4.0 standard location) rather than from a non-standard `error` key. The fix includes safe guards: `isinstance(content, list) and len(content) > 0` before accessing `content[0]`, with `"unknown error"` as the fallback when `content` is absent or malformed. **What spec section needs updating**: **Section: MCPToolAdapter execute()** (lines 21931–21939) Current text: ``` 3. **execute()**: Translates a `Tool.execute(params, ctx)` call into an MCP `tools/call` JSON-RPC request. Before dispatching: - Rewrites file paths to sandbox-relative paths - Validates params against `inputSchema` - Checks capability metadata against plan access policy - Creates a checkpoint if the tool is marked checkpointable After the MCP tool returns its `content[]` response, the adapter: - Parses the result into the CleverAgents `Result` format - Records any resource mutations as `Change` objects in the plan's `ChangeSet` ``` Proposed addition to the "After the MCP tool returns" bullet list: ``` After the MCP tool returns its `content[]` response, the adapter: - Parses the result into the CleverAgents `Result` format - For error responses (`isError: true`), extracts the error message from `content[0].text` per the MCP 1.4.0 protocol; falls back to `"unknown error"` when `content` is absent or malformed - Records any resource mutations as `Change` objects in the plan's `ChangeSet` ``` **Rationale**: The MCP 1.4.0 protocol places error messages in `content[0].text`, not in a top-level `error` key. The spec previously said "Parses the result" without specifying how errors are extracted. This is a genuine implementation improvement that discovered a protocol compliance requirement — the spec should document the correct extraction path so future implementors don't repeat the original mistake. --- ## Scope Sections affected: 1. `## Infrastructure Layer > MCPToolAdapter > execute()` — error extraction bullet ## Classification **Minor spec update** — this is a clarification/addition that aligns the spec with correct, already-merged implementation. No architectural changes. --- @freemo — Gap 1 has been removed per your feedback. This proposal now covers only Gap 2 (MCPToolAdapter MCP 1.4.0 error extraction). Please review and approve if you're satisfied. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
freemo added this to the v3.6.0 milestone 2026-04-05 05:24:59 +00:00
Author
Owner

Label compliance fix applied:

  • Removed conflicting label: Type/Automation
  • Retained: Type/Task
  • Reason: Issue had two conflicting Type/* labels. This is a spec update proposal (task work), not an automation tracking issue. Type/Task is the correct classification.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Removed conflicting label: `Type/Automation` - Retained: `Type/Task` - Reason: Issue had two conflicting `Type/*` labels. This is a spec update proposal (task work), not an automation tracking issue. `Type/Task` is the correct classification. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Author
Owner

For gap 1, we are removing this from the source code and wont be adding it to the specification. For gap 2 that's fine, I could approve of that one on its own. Please modify this ticket and its description to remove gap 1 then tag me in a comment to let me know it is updated. I will review again and evaluate final approval.

For gap 1, we are removing this from the source code and wont be adding it to the specification. For gap 2 that's fine, I could approve of that one on its own. Please modify this ticket and its description to remove gap 1 then tag me in a comment to let me know it is updated. I will review again and evaluate final approval.
freemo changed title from Proposal: update specification — plan list --namespace option and MCPToolAdapter MCP 1.4.0 error extraction to Proposal: update specification — MCPToolAdapter MCP 1.4.0 error extraction 2026-04-05 16:19:38 +00:00
Author
Owner

Closing this issue as superseded.

  • Gap 1 (plan list --namespace): Removed per @freemo's feedback — the --namespace option is being removed from source code and will not be added to the spec.
  • Gap 2 (MCPToolAdapter MCP 1.4.0 error extraction): Covered by issue #3330 (which was independently created, approved by CTO, and has State/Verified). The spec change has been implemented in PR #3390.

No further action needed on this issue.


Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

Closing this issue as superseded. - **Gap 1** (plan list --namespace): Removed per @freemo's feedback — the `--namespace` option is being removed from source code and will not be added to the spec. - **Gap 2** (MCPToolAdapter MCP 1.4.0 error extraction): Covered by issue #3330 (which was independently created, approved by CTO, and has `State/Verified`). The spec change has been implemented in PR #3390. No further action needed on this issue. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#3078
No description provided.