UAT: docs/api/mcp.md contains 6 incorrect API signatures — MCPToolResult.content, MCPToolAdapter.connect()/invoke() async, McpClientConfig.auto_stop_idle_secs, McpRegistry.register(), MCPRefreshHook(), and register_tools() all wrong #2118

Open
opened 2026-04-03 04:13:26 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: fix/docs-api-mcp-incorrect-signatures
  • Commit Message: fix(docs): correct 6 incorrect API signatures in docs/api/mcp.md
  • Milestone: v3.7.0
  • Parent Epic: #399

Bug Report

Severity Assessment

  • Impact: High — docs/api/mcp.md is the primary API reference for the MCP subsystem. All 6 discrepancies cause runtime errors (AttributeError, TypeError, ValidationError, or ImportError) for any user following the documentation exactly.
  • Likelihood: Certain — every user who copies the documented usage patterns will encounter at least one of these errors.
  • Priority: High

What Was Tested

Code-level comparison of docs/api/mcp.md against the actual implementation in src/cleveragents/mcp/.

Expected Behavior

The API documentation in docs/api/mcp.md should accurately reflect the actual implementation in src/cleveragents/mcp/ for all public types, field names, method signatures, and constructor arguments.

Actual Behavior — Specific Discrepancies

1. MCPToolResult field name wrong

  • Doc shows (docs/api/mcp.md line 55): content: Any
  • Actual implementation (src/cleveragents/mcp/adapter.py line 132): data: dict[str, Any]
  • Impact: result.content raises AttributeError

2. MCPToolAdapter.connect() and invoke() shown as async

  • Doc shows (docs/api/mcp.md lines 52–57): await adapter.connect(), result = await adapter.invoke(...)
  • Actual implementation (src/cleveragents/mcp/adapter.py): Both are synchronous methods (no async def)
  • Impact: await adapter.connect() raises TypeError: object NoneType can't be used in 'await' expression

3. McpClientConfig field name wrong

  • Doc shows (docs/api/mcp.md line 119): McpClientConfig(server=server_config, auto_stop_idle_secs=60)
  • Actual implementation (src/cleveragents/mcp/client.py line 78): field is idle_timeout_seconds
  • Impact: McpClientConfig(auto_stop_idle_secs=60) raises ValidationError

4. McpRegistry.register() signature wrong

  • Doc shows (docs/api/mcp.md lines 141–143): reg.register("my-server", client)
  • Actual implementation (src/cleveragents/mcp/registry.py line 50): register(config: McpClientConfig, namespace: str, transport=None) -> McpClient
  • Impact: reg.register("my-server", client) raises TypeError

5. MCPRefreshHook constructor and usage wrong

  • Doc shows (docs/api/mcp.md lines 156–158): hook = MCPRefreshHook(skill_registry) and adapter.on_tools_changed(hook.on_tools_changed)
  • Actual implementation (src/cleveragents/mcp/refresh_hook.py line 59): MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5) — adapter is the first argument, and there is no on_tools_changed method on the adapter
  • Impact: MCPRefreshHook(skill_registry) raises TypeError

6. register_tools() missing required namespace parameter

  • Doc shows (docs/api/mcp.md line 51–58): adapter.register_tools(registry)
  • Actual implementation (src/cleveragents/mcp/adapter.py line 529): register_tools(self, registry, namespace: str, tool_filter=None)namespace is required
  • Impact: adapter.register_tools(registry) raises TypeError: missing required argument 'namespace'

Code Locations

  • Documentation: docs/api/mcp.md lines 51–58, 52–57, 119, 141–143, 156–158, 55
  • Implementation: src/cleveragents/mcp/adapter.py, src/cleveragents/mcp/client.py, src/cleveragents/mcp/registry.py, src/cleveragents/mcp/refresh_hook.py

Subtasks

  • Audit docs/api/mcp.md against all public symbols in src/cleveragents/mcp/ to confirm the 6 discrepancies and identify any additional ones
  • Fix discrepancy 1: Update MCPToolResult field from content: Any to data: dict[str, Any] in docs/api/mcp.md
  • Fix discrepancy 2: Remove await from adapter.connect() and adapter.invoke() examples in docs/api/mcp.md — both are synchronous
  • Fix discrepancy 3: Update McpClientConfig field from auto_stop_idle_secs to idle_timeout_seconds in docs/api/mcp.md
  • Fix discrepancy 4: Update McpRegistry.register() signature in docs/api/mcp.md to match actual: register(config: McpClientConfig, namespace: str, transport=None) -> McpClient
  • Fix discrepancy 5: Update MCPRefreshHook constructor in docs/api/mcp.md to MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5) and remove the non-existent adapter.on_tools_changed() call
  • Fix discrepancy 6: Update register_tools() example in docs/api/mcp.md to include the required namespace argument: adapter.register_tools(registry, namespace="my-ns")
  • Perform a full cross-check of all remaining code examples in docs/api/mcp.md against the implementation to catch any further discrepancies
  • Write a Behave scenario (@tdd_expected_fail) that validates the documented API signatures match the actual implementation (import and call each documented symbol with the documented signature)
  • Run nox -e typecheck and confirm no type errors
  • Run nox -e lint and confirm no lint errors
  • Run nox -e unit_tests and confirm all tests pass
  • Run nox -e coverage_report and confirm coverage ≥ 97%

Definition of Done

  • All 6 documented API signatures in docs/api/mcp.md match the actual implementation in src/cleveragents/mcp/
  • MCPToolResult.data (not .content) is documented correctly
  • MCPToolAdapter.connect() and invoke() are documented as synchronous (no await)
  • McpClientConfig(idle_timeout_seconds=60) is the documented form (not auto_stop_idle_secs)
  • McpRegistry.register(config, namespace, transport=None) is the documented signature
  • MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5) is the documented constructor
  • adapter.register_tools(registry, namespace="...") includes the required namespace argument
  • A Behave unit test scenario validates the documented API signatures against the actual implementation
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(docs): correct 6 incorrect API signatures in docs/api/mcp.md), followed by a blank line, then additional detail lines
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/docs-api-mcp-incorrect-signatures)
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done
  • All nox stages pass
  • Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/docs-api-mcp-incorrect-signatures` - **Commit Message**: `fix(docs): correct 6 incorrect API signatures in docs/api/mcp.md` - **Milestone**: v3.7.0 - **Parent Epic**: #399 ## Bug Report ### Severity Assessment - **Impact**: High — `docs/api/mcp.md` is the primary API reference for the MCP subsystem. All 6 discrepancies cause runtime errors (`AttributeError`, `TypeError`, `ValidationError`, or `ImportError`) for any user following the documentation exactly. - **Likelihood**: Certain — every user who copies the documented usage patterns will encounter at least one of these errors. - **Priority**: High ### What Was Tested Code-level comparison of `docs/api/mcp.md` against the actual implementation in `src/cleveragents/mcp/`. ### Expected Behavior The API documentation in `docs/api/mcp.md` should accurately reflect the actual implementation in `src/cleveragents/mcp/` for all public types, field names, method signatures, and constructor arguments. ### Actual Behavior — Specific Discrepancies **1. `MCPToolResult` field name wrong** - Doc shows (`docs/api/mcp.md` line 55): `content: Any` - Actual implementation (`src/cleveragents/mcp/adapter.py` line 132): `data: dict[str, Any]` - Impact: `result.content` raises `AttributeError` **2. `MCPToolAdapter.connect()` and `invoke()` shown as async** - Doc shows (`docs/api/mcp.md` lines 52–57): `await adapter.connect()`, `result = await adapter.invoke(...)` - Actual implementation (`src/cleveragents/mcp/adapter.py`): Both are synchronous methods (no `async def`) - Impact: `await adapter.connect()` raises `TypeError: object NoneType can't be used in 'await' expression` **3. `McpClientConfig` field name wrong** - Doc shows (`docs/api/mcp.md` line 119): `McpClientConfig(server=server_config, auto_stop_idle_secs=60)` - Actual implementation (`src/cleveragents/mcp/client.py` line 78): field is `idle_timeout_seconds` - Impact: `McpClientConfig(auto_stop_idle_secs=60)` raises `ValidationError` **4. `McpRegistry.register()` signature wrong** - Doc shows (`docs/api/mcp.md` lines 141–143): `reg.register("my-server", client)` - Actual implementation (`src/cleveragents/mcp/registry.py` line 50): `register(config: McpClientConfig, namespace: str, transport=None) -> McpClient` - Impact: `reg.register("my-server", client)` raises `TypeError` **5. `MCPRefreshHook` constructor and usage wrong** - Doc shows (`docs/api/mcp.md` lines 156–158): `hook = MCPRefreshHook(skill_registry)` and `adapter.on_tools_changed(hook.on_tools_changed)` - Actual implementation (`src/cleveragents/mcp/refresh_hook.py` line 59): `MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5)` — adapter is the first argument, and there is no `on_tools_changed` method on the adapter - Impact: `MCPRefreshHook(skill_registry)` raises `TypeError` **6. `register_tools()` missing required `namespace` parameter** - Doc shows (`docs/api/mcp.md` line 51–58): `adapter.register_tools(registry)` - Actual implementation (`src/cleveragents/mcp/adapter.py` line 529): `register_tools(self, registry, namespace: str, tool_filter=None)` — `namespace` is required - Impact: `adapter.register_tools(registry)` raises `TypeError: missing required argument 'namespace'` ### Code Locations - **Documentation**: `docs/api/mcp.md` lines 51–58, 52–57, 119, 141–143, 156–158, 55 - **Implementation**: `src/cleveragents/mcp/adapter.py`, `src/cleveragents/mcp/client.py`, `src/cleveragents/mcp/registry.py`, `src/cleveragents/mcp/refresh_hook.py` ## Subtasks - [ ] Audit `docs/api/mcp.md` against all public symbols in `src/cleveragents/mcp/` to confirm the 6 discrepancies and identify any additional ones - [ ] Fix discrepancy 1: Update `MCPToolResult` field from `content: Any` to `data: dict[str, Any]` in `docs/api/mcp.md` - [ ] Fix discrepancy 2: Remove `await` from `adapter.connect()` and `adapter.invoke()` examples in `docs/api/mcp.md` — both are synchronous - [ ] Fix discrepancy 3: Update `McpClientConfig` field from `auto_stop_idle_secs` to `idle_timeout_seconds` in `docs/api/mcp.md` - [ ] Fix discrepancy 4: Update `McpRegistry.register()` signature in `docs/api/mcp.md` to match actual: `register(config: McpClientConfig, namespace: str, transport=None) -> McpClient` - [ ] Fix discrepancy 5: Update `MCPRefreshHook` constructor in `docs/api/mcp.md` to `MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5)` and remove the non-existent `adapter.on_tools_changed()` call - [ ] Fix discrepancy 6: Update `register_tools()` example in `docs/api/mcp.md` to include the required `namespace` argument: `adapter.register_tools(registry, namespace="my-ns")` - [ ] Perform a full cross-check of all remaining code examples in `docs/api/mcp.md` against the implementation to catch any further discrepancies - [ ] Write a Behave scenario (`@tdd_expected_fail`) that validates the documented API signatures match the actual implementation (import and call each documented symbol with the documented signature) - [ ] Run `nox -e typecheck` and confirm no type errors - [ ] Run `nox -e lint` and confirm no lint errors - [ ] Run `nox -e unit_tests` and confirm all tests pass - [ ] Run `nox -e coverage_report` and confirm coverage ≥ 97% ## Definition of Done - [ ] All 6 documented API signatures in `docs/api/mcp.md` match the actual implementation in `src/cleveragents/mcp/` - [ ] `MCPToolResult.data` (not `.content`) is documented correctly - [ ] `MCPToolAdapter.connect()` and `invoke()` are documented as synchronous (no `await`) - [ ] `McpClientConfig(idle_timeout_seconds=60)` is the documented form (not `auto_stop_idle_secs`) - [ ] `McpRegistry.register(config, namespace, transport=None)` is the documented signature - [ ] `MCPRefreshHook(adapter, skill_registry, debounce_seconds=0.5)` is the documented constructor - [ ] `adapter.register_tools(registry, namespace="...")` includes the required `namespace` argument - [ ] A Behave unit test scenario validates the documented API signatures against the actual implementation - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(docs): correct 6 incorrect API signatures in docs/api/mcp.md`), followed by a blank line, then additional detail lines - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/docs-api-mcp-incorrect-signatures`) - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-03 04:13:30 +00:00
freemo self-assigned this 2026-04-03 16:58:05 +00:00
Author
Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
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.

Blocks
#399 Epic: Post-MVP Server & Clients
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2118
No description provided.