UAT: `MCPToolFilter` not exported from `cleveragents.mcp` package `init.py` — breaks plug-and-play tool provider ecosystem #2927

New issue

Open

opened 2026-04-05 02:50:54 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 02:50:54 +00:00

Owner

Metadata

Branch: fix/mcp-tool-filter-missing-export
Commit Message: fix(mcp): export MCPToolFilter from cleveragents.mcp package __init__.py
Milestone: v3.8.0
Parent Epic: #399

Background and Context

The spec describes MCP integration as a "plug-and-play tool provider ecosystem" — all public types needed to configure and filter MCP tool discovery must be importable from the top-level cleveragents.mcp package. MCPToolFilter is a core type used to control which MCP tools are exposed (include/exclude lists), and it is required for any consumer of the MCP adapter API.

During UAT of the MCP Integration feature area, the public API surface of the cleveragents.mcp package was analysed against this spec requirement. MCPToolFilter was found to be correctly defined in src/cleveragents/mcp/adapter.py and included in that module's __all__, but it is not re-exported from src/cleveragents/mcp/__init__.py.

Current Behavior

MCPToolFilter is defined in adapter.py and present in its __all__:

# src/cleveragents/mcp/adapter.py
__all__ = [
    "MCPCapabilityMetadata",
    "MCPServerConfig",
    "MCPToolAdapter",
    "MCPToolDescriptor",
    "MCPToolFilter",   # ← defined here
    "MCPToolResult",
    "MCPTransport",
]

However, src/cleveragents/mcp/__init__.py omits MCPToolFilter from both its import and its __all__:

# src/cleveragents/mcp/__init__.py  (current — broken)
from cleveragents.mcp.adapter import (
    MCPCapabilityMetadata,
    MCPServerConfig,
    MCPToolAdapter,
    MCPToolDescriptor,
    MCPToolResult,   # ← MCPToolFilter is missing
)

__all__ = [
    "MCPCapabilityMetadata",
    "MCPRefreshHook",
    "MCPServerConfig",
    "MCPToolAdapter",
    "MCPToolDescriptor",
    "MCPToolResult",   # ← MCPToolFilter missing
    "McpClient",
    ...
]

Steps to reproduce:

from cleveragents.mcp import MCPToolFilter  # raises ImportError

This means:

from cleveragents.mcp import MCPToolFilter raises ImportError.
Users must import from the internal cleveragents.mcp.adapter module instead of the public package API.
MCPToolAdapter.discover_tools(tool_filter) and MCPToolAdapter.register_tools(registry, namespace, tool_filter) accept MCPToolFilter, but it cannot be imported from the public package.

Affected files:

src/cleveragents/mcp/__init__.py — missing MCPToolFilter import and __all__ entry
src/cleveragents/mcp/adapter.py — MCPToolFilter is correctly defined and in __all__ (no change needed)

Expected Behavior

MCPToolFilter should be importable directly from the top-level cleveragents.mcp package:

from cleveragents.mcp import MCPToolFilter  # must not raise ImportError

__init__.py should include MCPToolFilter in both its from … import (…) statement and its __all__ list, consistent with every other public type exported from the package.

Acceptance Criteria

from cleveragents.mcp import MCPToolFilter succeeds without error.
MCPToolFilter appears in cleveragents.mcp.__all__.
No other public symbols are accidentally removed or added during the fix.
All existing Behave unit tests continue to pass (nox -e unit_tests).
All existing Robot integration tests continue to pass (nox -e integration_tests).
Pyright type-checking passes with no new errors (nox -e typecheck).
Unit test coverage remains ≥ 97% (nox -e coverage_report).

Supporting Information

Parent Epic: #399 — Epic: Post-MVP Server & Clients
Spec requirement: MCP integration must provide a "plug-and-play tool provider ecosystem" with a clean, fully-exported public API surface.
Code locations: src/cleveragents/mcp/__init__.py, src/cleveragents/mcp/adapter.py

Subtasks

Add MCPToolFilter to the from cleveragents.mcp.adapter import (…) statement in src/cleveragents/mcp/__init__.py
Add MCPToolFilter to __all__ in src/cleveragents/mcp/__init__.py
Verify no other symbols are inadvertently affected
Tests (Behave): Add/update scenario confirming MCPToolFilter is importable from cleveragents.mcp
Run nox -e typecheck — fix any type errors
Run nox -e unit_tests — confirm all pass
Run nox -e integration_tests — confirm all pass
Verify coverage ≥ 97% via nox -e 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.
from cleveragents.mcp import MCPToolFilter succeeds without ImportError.
MCPToolFilter is present in cleveragents.mcp.__all__.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(mcp): export MCPToolFilter from cleveragents.mcp package __init__.py), 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/mcp-tool-filter-missing-export).
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-uat-tester

## Metadata - **Branch**: `fix/mcp-tool-filter-missing-export` - **Commit Message**: `fix(mcp): export MCPToolFilter from cleveragents.mcp package __init__.py` - **Milestone**: v3.8.0 - **Parent Epic**: #399 ## Background and Context The spec describes MCP integration as a **"plug-and-play tool provider ecosystem"** — all public types needed to configure and filter MCP tool discovery must be importable from the top-level `cleveragents.mcp` package. `MCPToolFilter` is a core type used to control which MCP tools are exposed (include/exclude lists), and it is required for any consumer of the MCP adapter API. During UAT of the MCP Integration feature area, the public API surface of the `cleveragents.mcp` package was analysed against this spec requirement. `MCPToolFilter` was found to be correctly defined in `src/cleveragents/mcp/adapter.py` and included in that module's `__all__`, but it is **not** re-exported from `src/cleveragents/mcp/__init__.py`. ## Current Behavior `MCPToolFilter` is defined in `adapter.py` and present in its `__all__`: ```python # src/cleveragents/mcp/adapter.py __all__ = [ "MCPCapabilityMetadata", "MCPServerConfig", "MCPToolAdapter", "MCPToolDescriptor", "MCPToolFilter", # ← defined here "MCPToolResult", "MCPTransport", ] ``` However, `src/cleveragents/mcp/__init__.py` omits `MCPToolFilter` from both its import and its `__all__`: ```python # src/cleveragents/mcp/__init__.py (current — broken) from cleveragents.mcp.adapter import ( MCPCapabilityMetadata, MCPServerConfig, MCPToolAdapter, MCPToolDescriptor, MCPToolResult, # ← MCPToolFilter is missing ) __all__ = [ "MCPCapabilityMetadata", "MCPRefreshHook", "MCPServerConfig", "MCPToolAdapter", "MCPToolDescriptor", "MCPToolResult", # ← MCPToolFilter missing "McpClient", ... ] ``` **Steps to reproduce:** ```python from cleveragents.mcp import MCPToolFilter # raises ImportError ``` This means: 1. `from cleveragents.mcp import MCPToolFilter` raises `ImportError`. 2. Users must import from the internal `cleveragents.mcp.adapter` module instead of the public package API. 3. `MCPToolAdapter.discover_tools(tool_filter)` and `MCPToolAdapter.register_tools(registry, namespace, tool_filter)` accept `MCPToolFilter`, but it cannot be imported from the public package. **Affected files:** - `src/cleveragents/mcp/__init__.py` — missing `MCPToolFilter` import and `__all__` entry - `src/cleveragents/mcp/adapter.py` — `MCPToolFilter` is correctly defined and in `__all__` (no change needed) ## Expected Behavior `MCPToolFilter` should be importable directly from the top-level `cleveragents.mcp` package: ```python from cleveragents.mcp import MCPToolFilter # must not raise ImportError ``` `__init__.py` should include `MCPToolFilter` in both its `from … import (…)` statement and its `__all__` list, consistent with every other public type exported from the package. ## Acceptance Criteria - `from cleveragents.mcp import MCPToolFilter` succeeds without error. - `MCPToolFilter` appears in `cleveragents.mcp.__all__`. - No other public symbols are accidentally removed or added during the fix. - All existing Behave unit tests continue to pass (`nox -e unit_tests`). - All existing Robot integration tests continue to pass (`nox -e integration_tests`). - Pyright type-checking passes with no new errors (`nox -e typecheck`). - Unit test coverage remains ≥ 97% (`nox -e coverage_report`). ## Supporting Information - Parent Epic: #399 — Epic: Post-MVP Server & Clients - Spec requirement: MCP integration must provide a "plug-and-play tool provider ecosystem" with a clean, fully-exported public API surface. - Code locations: `src/cleveragents/mcp/__init__.py`, `src/cleveragents/mcp/adapter.py` ## Subtasks - [ ] Add `MCPToolFilter` to the `from cleveragents.mcp.adapter import (…)` statement in `src/cleveragents/mcp/__init__.py` - [ ] Add `MCPToolFilter` to `__all__` in `src/cleveragents/mcp/__init__.py` - [ ] Verify no other symbols are inadvertently affected - [ ] Tests (Behave): Add/update scenario confirming `MCPToolFilter` is importable from `cleveragents.mcp` - [ ] Run `nox -e typecheck` — fix any type errors - [ ] Run `nox -e unit_tests` — confirm all pass - [ ] Run `nox -e integration_tests` — confirm all pass - [ ] Verify coverage ≥ 97% via `nox -e 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. - `from cleveragents.mcp import MCPToolFilter` succeeds without `ImportError`. - `MCPToolFilter` is present in `cleveragents.mcp.__all__`. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(mcp): export MCPToolFilter from cleveragents.mcp package __init__.py`), 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/mcp-tool-filter-missing-export`). - 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-uat-tester

freemo added this to the v3.8.0 milestone

2026-04-05 02:51:01 +00:00

freemo added a new dependency

2026-04-05 02:51:37 +00:00

#399 Epic: Post-MVP Server & Clients

freemo commented

2026-04-05 03:01:16 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Confirmed
MoSCoW: Should Have

Valid finding verified during batch triage.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Confirmed - **MoSCoW**: Should Have Valid finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 06:15:22 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.2.0–v3.7.0 — Session Tracker #3094