cleveragents/cleveragents-core

Fork 3

feat(skill): add MCP refresh hooks #455

Merged

aditya merged 2 commits from feature/m4-skill-registry-refresh into master

2026-02-27 13:17:21 +00:00

aditya commented

2026-02-26 12:56:10 +00:00

Member

Description

Implements MCP refresh hooks for the skill registry. Adds SkillRegistry.refresh(name)
and refresh_all() to recompute flattened tool sets on demand, and wires MCP
notifications/tools/list_changed events to trigger them via a new MCPRefreshHook
class with configurable debouncing. Introduces SkillRefreshResult for structured
refresh outcome reporting.

Type of Change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Refactoring (no functional changes)
Documentation update
Test improvements
CI/CD changes

Quality Checklist

Code follows the project's coding standards (see CONTRIBUTING.md)
All public/protected methods have argument validation
Static typing is complete (no Any unless justified)
nox -s typecheck passes with no errors
nox -s lint passes with no errors
Unit tests written/updated (Behave scenarios in features/)
Integration tests written/updated (Robot suites in robot/) if applicable
Coverage remains above 97% (nox -s coverage_report)
No security issues introduced (nox -s security_scan)
No dead code introduced (nox -s dead_code)
Documentation updated if behavior changed

Testing

Behave unit tests were written before implementation (BDD-first). All tests
passed after implementation with no modifications to the test expectations.

Test Commands Run

nox -s unit_tests       # 19 Behave scenarios, 97 steps — all passed
nox -s typecheck        # 0 errors, 0 warnings
nox -s lint             # All checks passed
nox -s coverage_report  # SkillRefreshResult: 100%, MCPRefreshHook: 89%
nox -s security_scan    # No issues found

ISSUES CLOSED #168

Implementation Notes

New components

SkillRefreshResult (src/cleveragents/skills/refresh.py)
Immutable frozen dataclass summarising a refresh operation with refreshed,
failed, and skipped lists/dicts. Provides to_summary() for one-line
CLI/log output and merge() for aggregating per-skill results in refresh_all().

MCPRefreshHook (src/cleveragents/mcp/refresh_hook.py)
Registers itself as a notification listener on an MCPToolAdapter. On receiving
notifications/tools/list_changed, it schedules a threading.Timer to call
SkillRegistry.refresh_all() after debounce_seconds (default 0.5 s). Each
new notification resets the timer, coalescing bursts into a single refresh.
Thread-safe via threading.Lock. Exposes refresh_count and cancel().

Modified components

SkillRegistry (src/cleveragents/skills/registry.py)
Added refresh(name) and refresh_all(). Resolves tools via SkillResolver,
validates refs against ToolRegistry if configured, returns SkillRefreshResult.

MCPToolAdapter (src/cleveragents/mcp/adapter.py)
Added add_notification_listener(callback) and dispatch_notification(method, params)
for a generic, loosely-coupled notification fan-out mechanism.

Key design decisions

Debounce over immediate refresh: prevents refresh storms when MCP servers
emit multiple list_changed notifications in quick succession.
Graceful degradation: if no ToolRegistry is configured, refresh() skips
validation and counts the skill as refreshed, logging a single WARNING with
recovery steps rather than failing hard.
Immutable result type: SkillRefreshResult is frozen=True so callers
cannot mutate shared results passed across thread boundaries.

## Description Implements MCP refresh hooks for the skill registry. Adds `SkillRegistry.refresh(name)` and `refresh_all()` to recompute flattened tool sets on demand, and wires MCP `notifications/tools/list_changed` events to trigger them via a new `MCPRefreshHook` class with configurable debouncing. Introduces `SkillRefreshResult` for structured refresh outcome reporting. ## Type of Change - [ ] Bug fix (non-breaking change which fixes an issue) - [x] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] Refactoring (no functional changes) - [x] Documentation update - [x] Test improvements - [ ] CI/CD changes ## Quality Checklist - [x] Code follows the project's coding standards (see CONTRIBUTING.md) - [x] All public/protected methods have argument validation - [x] Static typing is complete (no `Any` unless justified) - [x] `nox -s typecheck` passes with no errors - [x] `nox -s lint` passes with no errors - [x] Unit tests written/updated (Behave scenarios in `features/`) - [x] Integration tests written/updated (Robot suites in `robot/`) if applicable - [x] Coverage remains above 97% (`nox -s coverage_report`) - [x] No security issues introduced (`nox -s security_scan`) - [ ] No dead code introduced (`nox -s dead_code`) - [x] Documentation updated if behavior changed ## Testing Behave unit tests were written **before** implementation (BDD-first). All tests passed after implementation with no modifications to the test expectations. ### Test Commands Run ```bash nox -s unit_tests # 19 Behave scenarios, 97 steps — all passed nox -s typecheck # 0 errors, 0 warnings nox -s lint # All checks passed nox -s coverage_report # SkillRefreshResult: 100%, MCPRefreshHook: 89% nox -s security_scan # No issues found ``` ## Related Issues ISSUES CLOSED #168 ## Implementation Notes ### New components **`SkillRefreshResult`** (`src/cleveragents/skills/refresh.py`) Immutable frozen dataclass summarising a refresh operation with `refreshed`, `failed`, and `skipped` lists/dicts. Provides `to_summary()` for one-line CLI/log output and `merge()` for aggregating per-skill results in `refresh_all()`. **`MCPRefreshHook`** (`src/cleveragents/mcp/refresh_hook.py`) Registers itself as a notification listener on an `MCPToolAdapter`. On receiving `notifications/tools/list_changed`, it schedules a `threading.Timer` to call `SkillRegistry.refresh_all()` after `debounce_seconds` (default 0.5 s). Each new notification resets the timer, coalescing bursts into a single refresh. Thread-safe via `threading.Lock`. Exposes `refresh_count` and `cancel()`. ### Modified components **`SkillRegistry`** (`src/cleveragents/skills/registry.py`) Added `refresh(name)` and `refresh_all()`. Resolves tools via `SkillResolver`, validates refs against `ToolRegistry` if configured, returns `SkillRefreshResult`. **`MCPToolAdapter`** (`src/cleveragents/mcp/adapter.py`) Added `add_notification_listener(callback)` and `dispatch_notification(method, params)` for a generic, loosely-coupled notification fan-out mechanism. ### Key design decisions - **Debounce over immediate refresh**: prevents refresh storms when MCP servers emit multiple `list_changed` notifications in quick succession. - **Graceful degradation**: if no `ToolRegistry` is configured, `refresh()` skips validation and counts the skill as refreshed, logging a single `WARNING` with recovery steps rather than failing hard. - **Immutable result type**: `SkillRefreshResult` is `frozen=True` so callers cannot mutate shared results passed across thread boundaries.

aditya added 5 commits

2026-02-26 12:56:10 +00:00

feat(skill): add MCP adapter for external tools ee82d6101e

Implement MCPToolAdapter to connect to external MCP servers, enumerate
tools, and register them in ToolRegistry with source="mcp". Includes
connect/reconnect/disconnect lifecycle with timeout enforcement, input
validation on invoke, capability inference, Behave/Robot/ASV tests, and
docs/reference/mcp_adapter.md.

ISSUES CLOSED: #159

chore(changelog): add MCP adapter entry 2deddd3fe2

refactor(mcp): fix mock placement, type annotation, and constructor validation

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / lint (pull_request) Successful in 14s

Details

CI / build (pull_request) Successful in 16s

Details

CI / typecheck (pull_request) Successful in 30s

Details

CI / quality (pull_request) Successful in 32s

Details

CI / security (pull_request) Successful in 34s

Details

CI / integration_tests (pull_request) Successful in 3m24s

Details

CI / unit_tests (pull_request) Successful in 10m40s

Details

CI / docker (pull_request) Successful in 1m4s

Details

CI / benchmark-regression (pull_request) Successful in 19m50s

Details

CI / coverage (pull_request) Successful in 28m33s

Details

2f9707cfdf

- Extract MockMCPTransport to features/mocks/mock_mcp_transport.py
- Use ToolRegistry type with TYPE_CHECKING in register_tools()
- Move transport config validation into __init__ via _validate_config()

Merge branch 'master' into feature/m3-mcp-adapter

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / quality (pull_request) Successful in 21s

Details

CI / lint (pull_request) Successful in 21s

Details

CI / build (pull_request) Successful in 21s

Details

CI / security (pull_request) Successful in 50s

Details

CI / typecheck (pull_request) Successful in 59s

Details

CI / integration_tests (pull_request) Successful in 4m18s

Details

CI / unit_tests (pull_request) Successful in 10m11s

Details

CI / docker (pull_request) Successful in 59s

Details

CI / benchmark-regression (pull_request) Successful in 20m36s

Details

CI / coverage (pull_request) Successful in 36m7s

Details

519e26fb02

feat(skill): add MCP refresh hooks

CI / benchmark-publish (pull_request) Has been skipped

Details

CI / quality (pull_request) Successful in 20s

Details

CI / lint (pull_request) Successful in 24s

Details

CI / build (pull_request) Successful in 27s

Details

CI / typecheck (pull_request) Successful in 34s

Details

CI / security (pull_request) Successful in 1m11s

Details

CI / integration_tests (pull_request) Successful in 4m40s

Details

CI / unit_tests (pull_request) Successful in 9m55s

Details

CI / docker (pull_request) Successful in 1m0s

Details

CI / benchmark-regression (pull_request) Successful in 25m30s

Details

CI / coverage (pull_request) Successful in 1h11m59s

Details

b25a886df8

Implement SkillRegistry.refresh(name) and refresh_all() to recompute
flattened tool sets on demand. Wire MCPToolAdapter.dispatch_notification()
to MCPRefreshHook, which debounces rapid notifications/tools/list_changed
bursts into a single refresh_all() call (default 0.5 s window).

Add safeguard that skips tool-ref validation when no ToolRegistry is
configured, emitting a single WARNING with recovery steps. Introduce
immutable SkillRefreshResult (refreshed/failed/skipped counts) with
to_summary() and merge() for CLI and log output.

New files:
- src/cleveragents/skills/refresh.py        (SkillRefreshResult)
- src/cleveragents/mcp/refresh_hook.py      (MCPRefreshHook)
- features/skill_refresh.feature            (19 Behave scenarios)
- features/steps/skill_refresh_steps.py
- robot/skill_refresh.robot                 (10 Robot tests)
- robot/helper_skill_refresh.py
- benchmarks/skill_refresh_bench.py         (ASV benchmarks)
- docs/reference/skill_refresh.md

Modified:
- src/cleveragents/skills/registry.py       (refresh, refresh_all)
- src/cleveragents/mcp/adapter.py           (notification listener API)
- src/cleveragents/skills/__init__.py       (export SkillRefreshResult)
- src/cleveragents/mcp/__init__.py          (export MCPRefreshHook)
- CHANGELOG.md

ISSUES CLOSED #168

aditya requested review from CoreRasurae

2026-02-26 12:56:17 +00:00

aditya added this to the v3.1.0 milestone

2026-02-26 12:56:29 +00:00

aditya changed title from ~~feature/m4-skill-registry-refresh~~ to feat(skill): add MCP refresh hooks

2026-02-26 14:55:15 +00:00

aditya added the

Type

Feature

label

2026-02-26 14:55:25 +00:00