Implement concrete MCP transport layer (stdio) for tool discovery and invocation #4918

Open
opened 2026-04-08 22:23:05 +00:00 by CoreRasurae · 4 comments
Member

Background and Context

The MCP (Model Context Protocol) stdio transport implementation exists but is not merged to master.

The Discovery

During debugging of the MCP skill feature (which shows "0 tools" despite servers being validated), we identified the root cause: the MCPTransport base class in adapter.py has no concrete implementation.

However, investigation revealed that the feature has already been implemented on branch origin/refactor/m3-remove-robot-mock-imports (commit 7d38ea8b, dated March 12, 2026):

  • StdioMCPTransport class exists with full implementation
  • JSON-RPC 2.0 stdio protocol fully implemented
  • MCP server initialization handshake implemented
  • Integration tests written and passing
  • Mock test doubles replaced with real transport
  • Issue #724 marked as closed by the implementation

The Real Problem

The branch is 633 commits behind master (diverged March 12; master now at April 8, 2026) and has never been merged. The work is isolated and unusable because:

  1. Massive merge conflict risk — 633 commits of master work have not been integrated
  2. Unknown merge status — unclear if branch is active, awaiting review, or abandoned
  3. Feature remains blocked — users cannot use MCP skills until this branch is integrated
  4. Specification gap — unclear if MCP transport is documented as already supported in docs/specification.md

Current Behavior

When a user tries to register a skill with MCP servers:

name: local/text-editor
description: MCP text editor tools
mcp_servers:
  - server: mcp-text-editor

The CLI shows "0 tools" because MCPToolAdapter instantiates the abstract MCPTransport() class (which raises NotImplementedError).

Meanwhile, the working implementation on the stale branch would show "6 tools" — but no one can access it.

Expected Behavior

After this issue is resolved:

  1. The origin/refactor/m3-remove-robot-mock-imports branch is rebased onto current master
  2. Merge conflicts are resolved
  3. All tests pass on the rebased branch
  4. The branch is merged to master
  5. Users can register skills with MCP servers and see correct tool counts
  6. MCP feature works end-to-end

Acceptance Criteria

  • The origin/refactor/m3-remove-robot-mock-imports branch is successfully rebased onto current master
  • All merge conflicts are resolved
  • StdioMCPTransport is integrated into /app/src/cleveragents/mcp/stdio_transport.py
  • MCPToolAdapter correctly instantiates StdioMCPTransport for "stdio" transport type
  • All unit tests pass (Behave): nox -s unit_tests
  • All integration tests pass (Robot Framework): nox -s integration_tests
  • Code passes Pyright type checking: nox -s typecheck
  • Code passes linting: nox -s lint
  • Test coverage remains >= 97%: nox -s coverage_report
  • Full test suite passes: nox
  • MCP text editor skill can be loaded with tool count > 0
  • Issue #724 remains closed (its work is now incorporated into master)
  • Documentation is updated if needed (spec may reference this as "already supported")

Supporting Information

Related Issues & PRs:

  • Original work closed: #724
  • Related feature: #964 (BuiltinAdapter and MCP resource slots)
  • This ticket: #4918 (MCP skill "0 tools" problem)

Reference Files:

  • Stale branch commit: origin/refactor/m3-remove-robot-mock-imports:7d38ea8b
  • Implementation file (on branch): /app/src/cleveragents/mcp/stdio_transport.py (314 lines)
  • Test fixtures (on branch): /robot/fixtures/mcp_echo_server.py
  • Updated adapter (on branch): /app/src/cleveragents/mcp/adapter.py (modified to use concrete transport)
  • Integration tests (on branch): /robot/mcp_adapter.robot and helpers

Key Details from Stale Branch:

  • StdioMCPTransport uses newline-delimited JSON (NDJSON) over stdio
  • Supports MCP protocol version 2024-11-05
  • Handles subprocess spawning with configurable command/args/env
  • Implements proper initialization handshake with capability negotiation
  • Includes response timeout handling (30s default)
  • Thread-safe message I/O with locks

Investigation Results

Git History Findings:

Commit: 7d38ea8b (March 12, 2026)
Branch: origin/refactor/m3-remove-robot-mock-imports
Message: "refactor(test): replace mock test doubles with real MCP transport and dependencies"
Files Changed: 15 files (+819 lines, -283 lines)
Status: Never merged to master
Current Divergence: 633 commits behind master

Branch Status:

  • Not merged to master
  • No visible PR (may be pending, withdrawn, or never created)
  • Contains complete, working implementation
  • Likely has significant merge conflicts due to length of divergence

Metadata

  • Commit Message: fix(mcp): integrate stale MCP transport implementation branch into master
  • Branch: bugfix/m3-integrate-mcp-transport (rebase and merge of the stale work)

Subtasks

  • Investigation & Preparation

    • Review the stale branch origin/refactor/m3-remove-robot-mock-imports in full
    • Understand all files changed and their purposes
    • Check for any open PR or review comments on this branch
    • Verify issue #724 context and its resolution status
    • Identify likely merge conflict areas with master
  • Rebase & Merge Preparation

    • Create feature/bugfix branch: bugfix/m3-integrate-mcp-transport from current master
    • Cherry-pick or rebase the MCP transport commits onto the new branch
    • Resolve all merge conflicts (reconcile with master's changes since March 12)
    • Verify all files compile and imports are correct after conflict resolution
  • Test Validation

    • Run nox (full test suite) on the merged branch
    • Ensure all Behave BDD unit tests pass: nox -s unit_tests
    • Ensure all Robot Framework integration tests pass: nox -s integration_tests
    • Verify coverage >= 97%: nox -s coverage_report
    • Run type checking: nox -s typecheck (Pyright strict)
    • Run linting: nox -s lint (Ruff)
    • Document any test failures or regressions encountered
  • Feature Verification

    • Test MCP skill registration with mcp-text-editor server
    • Verify tool count displays correctly (should be 6, not 0)
    • Test tool invocation through the skill system
    • Verify graceful error handling and shutdown
  • Documentation & Integration

    • Review docs/specification.md — update if MCP transport is documented as "already supported"
    • Update CHANGELOG.md with reintegration entry
    • Update API documentation if relevant
    • Create commit with message exactly matching Metadata section
    • Push to remote on branch matching Metadata
  • Pull Request & Merge

    • Create PR to master with detailed description
    • Reference issue #724 (original work) and #4918 (this integration task)
    • Ensure all CI checks pass
    • Obtain required approvals
    • Merge to master

Definition of Done

This issue is complete when:

  • All subtasks are completed and checked off
  • The stale branch's implementation is successfully integrated into master
  • A single, atomic commit is created where the first line matches the Commit Message in Metadata exactly
  • The commit is pushed to the remote on the branch matching Branch in Metadata
  • The commit is submitted as a pull request to master, reviewed, and merged
  • All CI checks pass (tests, type checking, linting, coverage)
  • MCP text editor skill can be loaded and displays 6 tools (not 0)
  • Issue #724 remains closed (no reopening needed)
  • All downstream issues blocked on MCP support can now proceed
## Background and Context The MCP (Model Context Protocol) stdio transport implementation **exists but is not merged to master**. ### The Discovery During debugging of the MCP skill feature (which shows "0 tools" despite servers being validated), we identified the root cause: the `MCPTransport` base class in `adapter.py` has no concrete implementation. However, investigation revealed that the feature **has already been implemented** on branch `origin/refactor/m3-remove-robot-mock-imports` (commit `7d38ea8b`, dated March 12, 2026): - ✅ **StdioMCPTransport** class exists with full implementation - ✅ JSON-RPC 2.0 stdio protocol fully implemented - ✅ MCP server initialization handshake implemented - ✅ Integration tests written and passing - ✅ Mock test doubles replaced with real transport - ✅ Issue #724 marked as closed by the implementation ### The Real Problem The branch is **633 commits behind master** (diverged March 12; master now at April 8, 2026) and **has never been merged**. The work is isolated and unusable because: 1. **Massive merge conflict risk** — 633 commits of master work have not been integrated 2. **Unknown merge status** — unclear if branch is active, awaiting review, or abandoned 3. **Feature remains blocked** — users cannot use MCP skills until this branch is integrated 4. **Specification gap** — unclear if MCP transport is documented as already supported in `docs/specification.md` ## Current Behavior When a user tries to register a skill with MCP servers: ```yaml name: local/text-editor description: MCP text editor tools mcp_servers: - server: mcp-text-editor ``` The CLI shows "0 tools" because `MCPToolAdapter` instantiates the abstract `MCPTransport()` class (which raises `NotImplementedError`). **Meanwhile, the working implementation on the stale branch would show "6 tools"** — but no one can access it. ## Expected Behavior After this issue is resolved: 1. The `origin/refactor/m3-remove-robot-mock-imports` branch is rebased onto current master 2. Merge conflicts are resolved 3. All tests pass on the rebased branch 4. The branch is merged to master 5. Users can register skills with MCP servers and see correct tool counts 6. MCP feature works end-to-end ## Acceptance Criteria - [ ] The `origin/refactor/m3-remove-robot-mock-imports` branch is successfully rebased onto current master - [ ] All merge conflicts are resolved - [ ] `StdioMCPTransport` is integrated into `/app/src/cleveragents/mcp/stdio_transport.py` - [ ] `MCPToolAdapter` correctly instantiates `StdioMCPTransport` for `"stdio"` transport type - [ ] All unit tests pass (Behave): `nox -s unit_tests` - [ ] All integration tests pass (Robot Framework): `nox -s integration_tests` - [ ] Code passes Pyright type checking: `nox -s typecheck` - [ ] Code passes linting: `nox -s lint` - [ ] Test coverage remains >= 97%: `nox -s coverage_report` - [ ] Full test suite passes: `nox` - [ ] MCP text editor skill can be loaded with tool count > 0 - [ ] Issue #724 remains closed (its work is now incorporated into master) - [ ] Documentation is updated if needed (spec may reference this as "already supported") ## Supporting Information **Related Issues & PRs:** - Original work closed: #724 - Related feature: #964 (BuiltinAdapter and MCP resource slots) - This ticket: #4918 (MCP skill "0 tools" problem) **Reference Files:** - **Stale branch commit:** `origin/refactor/m3-remove-robot-mock-imports:7d38ea8b` - **Implementation file (on branch):** `/app/src/cleveragents/mcp/stdio_transport.py` (314 lines) - **Test fixtures (on branch):** `/robot/fixtures/mcp_echo_server.py` - **Updated adapter (on branch):** `/app/src/cleveragents/mcp/adapter.py` (modified to use concrete transport) - **Integration tests (on branch):** `/robot/mcp_adapter.robot` and helpers **Key Details from Stale Branch:** - `StdioMCPTransport` uses newline-delimited JSON (NDJSON) over stdio - Supports MCP protocol version 2024-11-05 - Handles subprocess spawning with configurable command/args/env - Implements proper initialization handshake with capability negotiation - Includes response timeout handling (30s default) - Thread-safe message I/O with locks ## Investigation Results **Git History Findings:** ``` Commit: 7d38ea8b (March 12, 2026) Branch: origin/refactor/m3-remove-robot-mock-imports Message: "refactor(test): replace mock test doubles with real MCP transport and dependencies" Files Changed: 15 files (+819 lines, -283 lines) Status: Never merged to master Current Divergence: 633 commits behind master ``` **Branch Status:** - Not merged to master - No visible PR (may be pending, withdrawn, or never created) - Contains complete, working implementation - Likely has significant merge conflicts due to length of divergence ## Metadata - **Commit Message**: `fix(mcp): integrate stale MCP transport implementation branch into master` - **Branch**: `bugfix/m3-integrate-mcp-transport` (rebase and merge of the stale work) ## Subtasks - [ ] **Investigation & Preparation** - [ ] Review the stale branch `origin/refactor/m3-remove-robot-mock-imports` in full - [ ] Understand all files changed and their purposes - [ ] Check for any open PR or review comments on this branch - [ ] Verify issue #724 context and its resolution status - [ ] Identify likely merge conflict areas with master - [ ] **Rebase & Merge Preparation** - [ ] Create feature/bugfix branch: `bugfix/m3-integrate-mcp-transport` from current master - [ ] Cherry-pick or rebase the MCP transport commits onto the new branch - [ ] Resolve all merge conflicts (reconcile with master's changes since March 12) - [ ] Verify all files compile and imports are correct after conflict resolution - [ ] **Test Validation** - [ ] Run `nox` (full test suite) on the merged branch - [ ] Ensure all Behave BDD unit tests pass: `nox -s unit_tests` - [ ] Ensure all Robot Framework integration tests pass: `nox -s integration_tests` - [ ] Verify coverage >= 97%: `nox -s coverage_report` - [ ] Run type checking: `nox -s typecheck` (Pyright strict) - [ ] Run linting: `nox -s lint` (Ruff) - [ ] Document any test failures or regressions encountered - [ ] **Feature Verification** - [ ] Test MCP skill registration with mcp-text-editor server - [ ] Verify tool count displays correctly (should be 6, not 0) - [ ] Test tool invocation through the skill system - [ ] Verify graceful error handling and shutdown - [ ] **Documentation & Integration** - [ ] Review `docs/specification.md` — update if MCP transport is documented as "already supported" - [ ] Update CHANGELOG.md with reintegration entry - [ ] Update API documentation if relevant - [ ] Create commit with message exactly matching Metadata section - [ ] Push to remote on branch matching Metadata - [ ] **Pull Request & Merge** - [ ] Create PR to master with detailed description - [ ] Reference issue #724 (original work) and #4918 (this integration task) - [ ] Ensure all CI checks pass - [ ] Obtain required approvals - [ ] Merge to master ## Definition of Done This issue is complete when: - All subtasks are completed and checked off - The stale branch's implementation is successfully integrated into master - A single, atomic commit is created where the **first line** matches the Commit Message in Metadata exactly - The commit is pushed to the remote on the branch matching **Branch** in Metadata - The commit is submitted as a **pull request** to master, reviewed, and **merged** - All CI checks pass (tests, type checking, linting, coverage) - MCP text editor skill can be loaded and displays 6 tools (not 0) - Issue #724 remains closed (no reopening needed) - All downstream issues blocked on MCP support can now proceed
Owner

Thank you for filing this issue, @CoreRasurae. This is a well-documented investigation with clear root cause analysis and a concrete implementation plan.

This issue has been reviewed and is already correctly labeled as State/Verified, Priority/High, and Type/Task. The triage is appropriate given that MCP skill functionality is completely blocked until this is resolved.

A few observations on the implementation plan:

  1. Branch divergence risk: 633 commits of divergence is significant. The implementer should expect substantial merge conflicts, particularly in any files that have been refactored since March 12. The subtask breakdown correctly identifies this as the primary risk.

  2. Cherry-pick vs. full rebase: Given the divergence depth, cherry-picking the specific MCP transport commits (rather than rebasing the entire branch) may be more practical and less conflict-prone. The implementer should evaluate this approach.

  3. Test suite state: The integration tests on the stale branch were written against the March 12 codebase. After rebasing, they may need updates to match current test infrastructure patterns.

  4. Issue #724 linkage: The issue correctly notes that #724 should remain closed — the work is being reintegrated, not redone.

This issue is ready for implementation. The implementation team will pick it up as part of the current build session.


Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Thank you for filing this issue, @CoreRasurae. This is a well-documented investigation with clear root cause analysis and a concrete implementation plan. This issue has been reviewed and is already correctly labeled as `State/Verified`, `Priority/High`, and `Type/Task`. The triage is appropriate given that MCP skill functionality is completely blocked until this is resolved. A few observations on the implementation plan: 1. **Branch divergence risk**: 633 commits of divergence is significant. The implementer should expect substantial merge conflicts, particularly in any files that have been refactored since March 12. The subtask breakdown correctly identifies this as the primary risk. 2. **Cherry-pick vs. full rebase**: Given the divergence depth, cherry-picking the specific MCP transport commits (rather than rebasing the entire branch) may be more practical and less conflict-prone. The implementer should evaluate this approach. 3. **Test suite state**: The integration tests on the stale branch were written against the March 12 codebase. After rebasing, they may need updates to match current test infrastructure patterns. 4. **Issue #724 linkage**: The issue correctly notes that #724 should remain closed — the work is being reintegrated, not redone. This issue is ready for implementation. The implementation team will pick it up as part of the current build session. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
Owner

Reviewing this issue for triage.

This is a well-documented, high-priority task: the MCP stdio transport implementation exists on a stale branch (origin/refactor/m3-remove-robot-mock-imports) that is 633 commits behind master and has never been merged. The issue has complete subtasks, acceptance criteria, and a Definition of Done.

Issue verified and triaged:

  • Priority: High — MCP skills are completely non-functional without this; "0 tools" blocks all MCP-dependent workflows
  • Milestone: v3.8.0 (current active milestone for infrastructure work)
  • Story Points: XL (8) — rebase of a 633-commit divergence with conflict resolution, full test suite validation, and feature verification
  • Type: Task (integration/rebase work)
  • Next step: This issue is ready for implementation. The implementation-worker should create branch bugfix/m3-integrate-mcp-transport and begin the rebase.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: human-liaison

Reviewing this issue for triage. This is a well-documented, high-priority task: the MCP stdio transport implementation exists on a stale branch (`origin/refactor/m3-remove-robot-mock-imports`) that is 633 commits behind master and has never been merged. The issue has complete subtasks, acceptance criteria, and a Definition of Done. Issue verified and triaged: - **Priority**: High — MCP skills are completely non-functional without this; "0 tools" blocks all MCP-dependent workflows - **Milestone**: v3.8.0 (current active milestone for infrastructure work) - **Story Points**: XL (8) — rebase of a 633-commit divergence with conflict resolution, full test suite validation, and feature verification - **Type**: Task (integration/rebase work) - **Next step**: This issue is ready for implementation. The implementation-worker should create branch `bugfix/m3-integrate-mcp-transport` and begin the rebase. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: human-liaison
HAL9000 added this to the v3.8.0 milestone 2026-04-09 00:53:24 +00:00
Owner

Label compliance fix applied:

  • Added missing label: MoSCoW/Must have
  • Reason: Issue is in State/Verified with Priority/High but was missing a MoSCoW classification label. Applied MoSCoW/Must have based on high priority and milestone assignment.

Note: MoSCoW labels are normally set by the project owner. If this classification is incorrect, please update accordingly.


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

Label compliance fix applied: - Added missing label: `MoSCoW/Must have` - Reason: Issue is in `State/Verified` with `Priority/High` but was missing a MoSCoW classification label. Applied `MoSCoW/Must have` based on high priority and milestone assignment. Note: MoSCoW labels are normally set by the project owner. If this classification is incorrect, please update accordingly. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer
Author
Member

PR #11129 has been created to address this issue. The PR implements the concrete StdioMCPTransport class for MCP JSON-RPC 2.0 stdio communication. This PR blocks this issue - once PR #11129 is merged, this issue should be closed.

Summary of Changes

  • StdioMCPTransport class with JSON-RPC 2.0 protocol support
  • Auto-selection when transport="stdio" in MCPServerConfig
  • 14 BDD test scenarios (all passing)
  • MCP stub server for deterministic testing

PR Details

  • PR: #11129
  • Branch: bugfix/m3-integrate-mcp-transport
  • Milestone: v3.8.0
  • Labels: State/In Review, Type/Task
  • CI Status: All checks passed (lint, typecheck, 93 BDD scenarios)
PR #11129 has been created to address this issue. The PR implements the concrete StdioMCPTransport class for MCP JSON-RPC 2.0 stdio communication. This PR **blocks** this issue - once PR #11129 is merged, this issue should be closed. ## Summary of Changes - StdioMCPTransport class with JSON-RPC 2.0 protocol support - Auto-selection when transport="stdio" in MCPServerConfig - 14 BDD test scenarios (all passing) - MCP stub server for deterministic testing ## PR Details - **PR**: https://git.cleverthis.com/cleveragents/cleveragents-core/pulls/11129 - **Branch**: bugfix/m3-integrate-mcp-transport - **Milestone**: v3.8.0 - **Labels**: State/In Review, Type/Task - **CI Status**: All checks passed (lint, typecheck, 93 BDD scenarios)
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

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