Proposal: update specification — MCP lazy-start lifecycle and tool YAML wrapper key #1597

New issue

Open

opened 2026-04-02 23:02:59 +00:00 by freemo · 1 comment

freemo commented

2026-04-02 23:02:59 +00:00

Owner

Proposal: Specification Update

This proposal documents two implementation discoveries from recently merged PRs that improve on the existing specification. Both changes represent the implementation finding a better or more complete approach than what the spec described.

What Changed in the Implementation

Merged PRs triggering this proposal:

PR #938 (merged via d0ef5631): feat(mcp): implement lazy start/auto-stop and sandbox path rewriting for MCP tools
PR #1498 (merged 0022c9c0): fix(cli): handle tool: wrapper key in agents tool add YAML config

Change 1: MCP Lazy-Start Lifecycle and McpClient/McpRegistry

Current spec text (§ "MCP Server Lifecycle Management"):

The spec describes a 4-phase lifecycle where MCP servers start at actor activation (Phase 2). The spec does not document:

Lazy start (server starts on first call_tool(), not at activation)
Auto-stop on idle (configurable timeout, default 5 minutes)
Health monitoring with automatic restart on crash
The McpClient class wrapping MCPToolAdapter with these lifecycle features
The McpRegistry class providing namespace-isolated tracking of multiple MCP servers

What the implementation built:

# McpClient: lazy start, auto-stop, health monitoring
client = McpClient(McpClientConfig(
    server=MCPServerConfig(name="gh", transport="stdio", command="gh-mcp"),
    idle_timeout_seconds=300,       # auto-stop after 5 min idle
    health_check_interval_seconds=30,
    lazy_start=True,                # server starts on first call_tool()
    auto_restart=True,              # restart on health check failure
))
result = client.call_tool("list_repos", {"org": "acme"})  # server starts here

# McpRegistry: namespace-isolated multi-server management
registry = McpRegistry()
registry.register(client_config, namespace="github")
registry.register(client_config_2, namespace="jira")
result = registry.call_tool("github", "list_repos", {"org": "acme"})
registry.shutdown_all()

Rationale: Lazy start is a better design than eager start at actor activation — it avoids starting MCP servers that may never be used in a given plan execution. Auto-stop prevents resource leaks from long-running actors. Health monitoring with restart improves reliability. The McpRegistry provides clean namespace isolation for multi-server scenarios.

Proposed spec update (§ "MCP Server Lifecycle Management"):

Update the lifecycle diagram and prose to reflect:

Phase 2 (Actor Activation) now registers the MCP server config but does not start the server process
New Phase 2.5 (Lazy Start): server starts on first call_tool() invocation
New Phase 4.5 (Idle Auto-Stop): server stops after idle_timeout_seconds of inactivity (default: 300s)
New Phase 5 (Health Monitoring): periodic health checks; automatic restart on failure
Document McpClient and McpRegistry as the implementation classes
Update the Sandbox Path Rewriting section to name SandboxPathRewriter as the implementing class

Spec sections affected:

§ MCP Server Lifecycle Management — update diagram and prose
§ Sandbox Path Rewriting for MCP Tools — add SandboxPathRewriter class reference

Change 2: Tool YAML `tool:` Wrapper Key

Current spec text (§ "Informal YAML Schema" for tools):

The spec shows tool YAML files starting directly with name: at the top level. It does not document a tool: wrapper key.

What the implementation built:

# In agents tool add, the CLI now accepts both formats:
# Format 1 (existing): flat YAML
# name: local/my-tool
# description: ...

# Format 2 (new): tool: wrapper key
# tool:
#   name: local/my-tool
#   description: ...
#
# Also: cleveragents: version header is stripped if present

Rationale: The tool: wrapper key is consistent with how skill: and actor: YAML files are structured (they use a top-level entity-type key). This makes tool YAML files consistent with the rest of the YAML configuration ecosystem. The cleveragents: version header stripping is also consistent with how other config files handle schema versioning.

Proposed spec update (§ "Tool Registration and Management" and § "Informal YAML Schema"):

Add a note that tool YAML files may optionally use a tool: top-level wrapper key (consistent with skill: and actor: YAML format). Update the informal YAML schema example to show both formats. Document that a cleveragents: version header block is accepted and ignored.

Spec sections affected:

§ Tool Registration and Management — add note about tool: wrapper key
§ Informal YAML Schema (tool) — show both flat and wrapped formats

Scope Summary

Section	Change Type	Rationale
MCP Server Lifecycle Management	Enhancement	Implementation discovered lazy-start is better than eager-start
Sandbox Path Rewriting for MCP Tools	Clarification	Name the implementing class `SandboxPathRewriter`
Tool Registration and Management	Enhancement	`tool:` wrapper key makes YAML format consistent across entity types
Tool Informal YAML Schema	Enhancement	Show both flat and wrapped YAML formats

Please review and approve this proposal. Once approved (by removing the needs feedback label, adding State/Verified, or commenting with approval), the spec changes will be committed to a branch and a PR created for human review before merging.

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: ca-spec-updater

## Proposal: Specification Update This proposal documents two implementation discoveries from recently merged PRs that improve on the existing specification. Both changes represent the implementation finding a better or more complete approach than what the spec described. --- ### What Changed in the Implementation **Merged PRs triggering this proposal:** - **PR #938** (merged via `d0ef5631`): `feat(mcp): implement lazy start/auto-stop and sandbox path rewriting for MCP tools` - **PR #1498** (merged `0022c9c0`): `fix(cli): handle tool: wrapper key in agents tool add YAML config` --- ### Change 1: MCP Lazy-Start Lifecycle and McpClient/McpRegistry **Current spec text** (§ "MCP Server Lifecycle Management"): The spec describes a 4-phase lifecycle where MCP servers start at **actor activation** (Phase 2). The spec does not document: - Lazy start (server starts on first `call_tool()`, not at activation) - Auto-stop on idle (configurable timeout, default 5 minutes) - Health monitoring with automatic restart on crash - The `McpClient` class wrapping `MCPToolAdapter` with these lifecycle features - The `McpRegistry` class providing namespace-isolated tracking of multiple MCP servers **What the implementation built:** ```python # McpClient: lazy start, auto-stop, health monitoring client = McpClient(McpClientConfig( server=MCPServerConfig(name="gh", transport="stdio", command="gh-mcp"), idle_timeout_seconds=300, # auto-stop after 5 min idle health_check_interval_seconds=30, lazy_start=True, # server starts on first call_tool() auto_restart=True, # restart on health check failure )) result = client.call_tool("list_repos", {"org": "acme"}) # server starts here # McpRegistry: namespace-isolated multi-server management registry = McpRegistry() registry.register(client_config, namespace="github") registry.register(client_config_2, namespace="jira") result = registry.call_tool("github", "list_repos", {"org": "acme"}) registry.shutdown_all() ``` **Rationale:** Lazy start is a better design than eager start at actor activation — it avoids starting MCP servers that may never be used in a given plan execution. Auto-stop prevents resource leaks from long-running actors. Health monitoring with restart improves reliability. The `McpRegistry` provides clean namespace isolation for multi-server scenarios. **Proposed spec update** (§ "MCP Server Lifecycle Management"): Update the lifecycle diagram and prose to reflect: 1. Phase 2 (Actor Activation) now registers the MCP server config but does **not** start the server process 2. New Phase 2.5 (Lazy Start): server starts on first `call_tool()` invocation 3. New Phase 4.5 (Idle Auto-Stop): server stops after `idle_timeout_seconds` of inactivity (default: 300s) 4. New Phase 5 (Health Monitoring): periodic health checks; automatic restart on failure 5. Document `McpClient` and `McpRegistry` as the implementation classes 6. Update the Sandbox Path Rewriting section to name `SandboxPathRewriter` as the implementing class **Spec sections affected:** - `§ MCP Server Lifecycle Management` — update diagram and prose - `§ Sandbox Path Rewriting for MCP Tools` — add `SandboxPathRewriter` class reference --- ### Change 2: Tool YAML `tool:` Wrapper Key **Current spec text** (§ "Informal YAML Schema" for tools): The spec shows tool YAML files starting directly with `name:` at the top level. It does not document a `tool:` wrapper key. **What the implementation built:** ```python # In agents tool add, the CLI now accepts both formats: # Format 1 (existing): flat YAML # name: local/my-tool # description: ... # Format 2 (new): tool: wrapper key # tool: # name: local/my-tool # description: ... # # Also: cleveragents: version header is stripped if present ``` **Rationale:** The `tool:` wrapper key is consistent with how `skill:` and `actor:` YAML files are structured (they use a top-level entity-type key). This makes tool YAML files consistent with the rest of the YAML configuration ecosystem. The `cleveragents:` version header stripping is also consistent with how other config files handle schema versioning. **Proposed spec update** (§ "Tool Registration and Management" and § "Informal YAML Schema"): Add a note that tool YAML files may optionally use a `tool:` top-level wrapper key (consistent with `skill:` and `actor:` YAML format). Update the informal YAML schema example to show both formats. Document that a `cleveragents:` version header block is accepted and ignored. **Spec sections affected:** - `§ Tool Registration and Management` — add note about `tool:` wrapper key - `§ Informal YAML Schema` (tool) — show both flat and wrapped formats --- ### Scope Summary | Section | Change Type | Rationale | |---------|-------------|-----------| | MCP Server Lifecycle Management | Enhancement | Implementation discovered lazy-start is better than eager-start | | Sandbox Path Rewriting for MCP Tools | Clarification | Name the implementing class `SandboxPathRewriter` | | Tool Registration and Management | Enhancement | `tool:` wrapper key makes YAML format consistent across entity types | | Tool Informal YAML Schema | Enhancement | Show both flat and wrapped YAML formats | --- **Please review and approve this proposal.** Once approved (by removing the `needs feedback` label, adding `State/Verified`, or commenting with approval), the spec changes will be committed to a branch and a PR created for human review before merging. --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: ca-spec-updater

freemo added this to the v3.7.0 milestone

2026-04-02 23:04:32 +00:00

freemo referenced this issue

2026-04-02 23:05:13 +00:00

[Spec-Updater] Specification Evolution Session State #1587

freemo commented

2026-04-03 18:36:16 +00:00

Author

Owner

approved