cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [error-handling] MCPToolAdapter swallows exceptions from notification listeners #1868

New issue

Open

opened 2026-04-03 00:02:10 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 00:02:10 +00:00

Owner

Metadata

Branch: fix/error-handling-mcp-tool-adapter-notification-listeners
Commit Message: fix(mcp): implement configurable error handler for MCPToolAdapter notification listener exceptions
Milestone: v3.2.0
Parent Epic: #1669

Bug Report: [error-handling] — MCPToolAdapter swallows exceptions from notification listeners

Severity Assessment

Impact: A faulty notification listener can fail silently, preventing other components from reacting to MCP events and making it difficult to debug system behavior.
Likelihood: High. Any exception in a listener callback will be caught and silenced.
Priority: Medium

Location

File: src/cleveragents/mcp/adapter.py
Function/Class: MCPToolAdapter.dispatch_notification
Lines: 323-329

Description

The dispatch_notification method in MCPToolAdapter iterates through its listeners and calls them within a try...except Exception block. If a listener raises an exception, it is caught, logged, and then ignored. This "catch-and-log" approach completely swallows the exception, preventing it from propagating.

Per the project's Exception Propagation guidelines, exceptions should bubble up to the top level where they can be properly logged and handled. Bare catch-all exception handlers without re-raising are only acceptable when there is specific recovery logic — silently logging and continuing does not qualify.

Evidence

# src/cleveragents/mcp/adapter.py:325
        for listener in listeners:
            try:
                listener(method, payload)
            except Exception:
                logger.warning(
                    "Notification listener raised an exception for method '%s'",
                    method,
                    exc_info=True,
                )

Expected Behavior

The system should provide a mechanism to handle listener errors without completely silencing them. Options include:

Error Channel: Publish listener errors to a separate error channel or event queue.
Configurable Handler: Allow an optional error handler to be configured on the MCPToolAdapter to process exceptions.
Circuit Breaker: Implement a circuit breaker to automatically disable faulty listeners after a certain number of failures.

Actual Behavior

Exceptions in listener callbacks are caught and logged, but the exception is otherwise ignored. The dispatcher and other listeners are unaware that an error occurred.

Suggested Fix

Implement a configurable error handler for the MCPToolAdapter. This would allow the application to define custom logic for handling listener exceptions, such as re-raising, logging to a different system, or disabling the faulty listener.

Subtasks

Investigate MCPToolAdapter.dispatch_notification and document the full impact of the silent exception swallowing
Design a configurable error handler interface for MCPToolAdapter (following OCP/DIP principles)
Implement the configurable error handler on MCPToolAdapter, defaulting to re-raise or a strict fail-fast behavior
Update all call sites and usages of MCPToolAdapter to account for the new error handling contract
Tests (Behave): Add scenarios covering listener exception propagation and configurable error handler behavior
Tests (Robot): Add integration test verifying listener error handling in a real MCP dispatch scenario
Update documentation and docstrings to reflect the new error handling contract
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(mcp): implement configurable error handler for MCPToolAdapter notification listener exceptions), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/error-handling-mcp-tool-adapter-notification-listeners).
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: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/error-handling-mcp-tool-adapter-notification-listeners` - **Commit Message**: `fix(mcp): implement configurable error handler for MCPToolAdapter notification listener exceptions` - **Milestone**: v3.2.0 - **Parent Epic**: #1669 ## Bug Report: [error-handling] — MCPToolAdapter swallows exceptions from notification listeners ### Severity Assessment - **Impact**: A faulty notification listener can fail silently, preventing other components from reacting to MCP events and making it difficult to debug system behavior. - **Likelihood**: High. Any exception in a listener callback will be caught and silenced. - **Priority**: Medium ### Location - **File**: `src/cleveragents/mcp/adapter.py` - **Function/Class**: `MCPToolAdapter.dispatch_notification` - **Lines**: 323-329 ### Description The `dispatch_notification` method in `MCPToolAdapter` iterates through its listeners and calls them within a `try...except Exception` block. If a listener raises an exception, it is caught, logged, and then ignored. This "catch-and-log" approach completely swallows the exception, preventing it from propagating. Per the project's [Exception Propagation guidelines](CONTRIBUTING.md), exceptions should bubble up to the top level where they can be properly logged and handled. Bare catch-all exception handlers without re-raising are only acceptable when there is specific recovery logic — silently logging and continuing does not qualify. ### Evidence ```python # src/cleveragents/mcp/adapter.py:325 for listener in listeners: try: listener(method, payload) except Exception: logger.warning( "Notification listener raised an exception for method '%s'", method, exc_info=True, ) ``` ### Expected Behavior The system should provide a mechanism to handle listener errors without completely silencing them. Options include: 1. **Error Channel**: Publish listener errors to a separate error channel or event queue. 2. **Configurable Handler**: Allow an optional error handler to be configured on the `MCPToolAdapter` to process exceptions. 3. **Circuit Breaker**: Implement a circuit breaker to automatically disable faulty listeners after a certain number of failures. ### Actual Behavior Exceptions in listener callbacks are caught and logged, but the exception is otherwise ignored. The dispatcher and other listeners are unaware that an error occurred. ### Suggested Fix Implement a configurable error handler for the `MCPToolAdapter`. This would allow the application to define custom logic for handling listener exceptions, such as re-raising, logging to a different system, or disabling the faulty listener. ### Category error-handling ## Subtasks - [ ] Investigate `MCPToolAdapter.dispatch_notification` and document the full impact of the silent exception swallowing - [ ] Design a configurable error handler interface for `MCPToolAdapter` (following OCP/DIP principles) - [ ] Implement the configurable error handler on `MCPToolAdapter`, defaulting to re-raise or a strict fail-fast behavior - [ ] Update all call sites and usages of `MCPToolAdapter` to account for the new error handling contract - [ ] Tests (Behave): Add scenarios covering listener exception propagation and configurable error handler behavior - [ ] Tests (Robot): Add integration test verifying listener error handling in a real MCP dispatch scenario - [ ] Update documentation and docstrings to reflect the new error handling contract - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(mcp): implement configurable error handler for MCPToolAdapter notification listener exceptions`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/error-handling-mcp-tool-adapter-notification-listeners`). - 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: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.2.0 milestone

2026-04-03 00:02:15 +00:00

freemo commented

2026-04-03 00:04:54 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or error handling improvement.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or error handling improvement. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added a new dependency

2026-04-03 00:04:57 +00:00

#1669 Bug Hunting Session

freemo added the

labels

2026-04-03 00:06:30 +00:00

freemo referenced this issue

2026-04-03 00:08:57 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463

freemo removed the

labels

2026-04-03 00:28:05 +00:00

freemo commented

2026-04-05 08:39:51 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — This is a real error-handling violation (silent exception swallowing in MCP notification dispatch), but it does not cause data loss or block core functionality. The notification system still functions for non-failing listeners.
Milestone: v3.6.0 — Moving from v3.2.0 to v3.6.0. The v3.2.0 milestone (Decisions + Validations + Invariants) is focused on decision recording, plan tree, and invariant enforcement. This MCP adapter error-handling issue belongs in v3.6.0 (Advanced Concepts & Deferred Features) where MCP/A2A protocol work is scoped.
MoSCoW: Should Have — Per CONTRIBUTING.md error-handling guidelines, silent exception swallowing violates the fail-fast principle. This should be fixed but is not blocking any Must Have feature.
Parent Epic: #933 (A2A Protocol Compliance) — The MCPToolAdapter is part of the A2A/MCP integration layer.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — This is a real error-handling violation (silent exception swallowing in MCP notification dispatch), but it does not cause data loss or block core functionality. The notification system still functions for non-failing listeners. - **Milestone**: v3.6.0 — Moving from v3.2.0 to v3.6.0. The v3.2.0 milestone (Decisions + Validations + Invariants) is focused on decision recording, plan tree, and invariant enforcement. This MCP adapter error-handling issue belongs in v3.6.0 (Advanced Concepts & Deferred Features) where MCP/A2A protocol work is scoped. - **MoSCoW**: Should Have — Per CONTRIBUTING.md error-handling guidelines, silent exception swallowing violates the fail-fast principle. This should be fixed but is not blocking any Must Have feature. - **Parent Epic**: #933 (A2A Protocol Compliance) — The MCPToolAdapter is part of the A2A/MCP integration layer. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added a new dependency

2026-04-05 08:58:16 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo modified the milestone from v3.2.0 to v3.6.0

2026-04-05 08:58:41 +00:00