cleveragents/cleveragents-core

Fork 3

UAT: `SkillMcpServerSchema` requires `transport` as a mandatory field — spec-compliant MCP server configs without explicit transport are rejected #2123

New issue

Open

opened 2026-04-03 04:16:39 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:16:39 +00:00

Owner

Background and Context

The SkillMcpServerSchema in src/cleveragents/skills/schema.py requires transport as a mandatory field, but the specification defines MCP server configurations where transport is optional and inferred from the presence of command (stdio) vs url (SSE/streamable-http). Any user following the specification to configure MCP servers in their skill YAML files will have their files rejected at parse time because transport is mandatory in the current schema but the spec shows it as optional/inferred.

Additionally, the specification shows MCP server entries supporting an overrides field for per-tool capability metadata (e.g., marking specific tools as writes: true, specifying write_scope, or read_only: true). This field is entirely absent from the current schema — the schema only supports tool_filter (include/exclude filtering), not overrides (capability metadata overrides).

What was tested: Code-level analysis of src/cleveragents/skills/schema.py against the skill YAML configuration section of docs/specification.md.

Current Behavior

SkillMcpServerSchema declares transport as a mandatory Pydantic field:

class SkillMcpServerSchema(BaseModel):
    name: str = Field(...)
    transport: str = Field(..., description="Transport protocol: stdio | sse | streamable-http.")  # MANDATORY
    command: str | None = Field(default=None, ...)
    ...

A skill YAML following the spec (without explicit transport) fails with:

ValidationError: transport: Field required

The overrides field (for per-tool capability metadata) is also entirely absent from the schema.

Expected Behavior

Per docs/specification.md, the skill YAML configuration must accept MCP server entries without requiring an explicit transport field. Transport should be inferred: command present → stdio; url present → sse or streamable-http. The overrides field must also be supported for per-tool capability metadata.

Spec-compliant example that must parse successfully:

skill:
  name: local/devops-toolkit
  mcp_servers:
    - name: linear
      command: "npx @anthropic/mcp-linear"
      env:
        LINEAR_API_KEY: "${LINEAR_API_KEY}"
      overrides:
        - tool: create_issue
          writes: true
          write_scope: [linear:issues]
        - tool: list_issues
          read_only: true

Steps to Reproduce

Create a skill YAML file using the spec-compliant MCP server config (no explicit transport):

name: local/test-skill
description: Test skill
mcp_servers:
  - name: linear
    command: "npx @anthropic/mcp-linear"
    env:
      LINEAR_API_KEY: "${LINEAR_API_KEY}"

Call SkillConfigSchema.from_yaml(yaml_content)
Observe: Pydantic raises ValidationError: transport: Field required

Acceptance Criteria

SkillMcpServerSchema.transport is optional (defaults to None); transport is inferred from command (→ stdio) or url (→ sse/streamable-http) via a Pydantic validator
A SkillMcpServerToolOverrideSchema model is added to represent per-tool capability metadata (tool, writes, write_scope, read_only)
SkillMcpServerSchema gains an overrides: list[SkillMcpServerToolOverrideSchema] field (optional, defaults to [])
Spec-compliant skill YAML with no explicit transport parses without error
Spec-compliant skill YAML with overrides entries parses without error
Existing skill YAMLs that do include an explicit transport continue to parse correctly (backward compatible)
All Pyright type checks pass (nox -e typecheck)
All Behave unit tests pass (nox -e unit_tests)

Supporting Information

Code location: src/cleveragents/skills/schema.py — SkillMcpServerSchema class
Spec reference: docs/specification.md — skill YAML configuration section (MCP server entries)
Severity: High — any user following the specification will encounter this validation failure immediately upon loading a spec-compliant skill YAML

Metadata

Branch: fix/skill-mcp-server-schema-optional-transport
Commit Message: fix(skills): make transport optional and add overrides to SkillMcpServerSchema
Milestone: v3.7.0
Parent Epic: #392

Subtasks

Make transport optional in SkillMcpServerSchema with inferred default via Pydantic model_validator
Add SkillMcpServerToolOverrideSchema model with fields: tool: str, writes: bool, write_scope: list[str], read_only: bool
Add overrides: list[SkillMcpServerToolOverrideSchema] field to SkillMcpServerSchema (optional, default [])
Tests (Behave): Add scenarios for MCP server config with no explicit transport (stdio inferred from command, SSE inferred from url)
Tests (Behave): Add scenarios for MCP server config with overrides entries
Tests (Behave): Add regression scenario confirming explicit transport still works
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(skills): make transport optional and add overrides to SkillMcpServerSchema), 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/skill-mcp-server-schema-optional-transport).
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

## Background and Context The `SkillMcpServerSchema` in `src/cleveragents/skills/schema.py` requires `transport` as a mandatory field, but the specification defines MCP server configurations where `transport` is optional and inferred from the presence of `command` (stdio) vs `url` (SSE/streamable-http). Any user following the specification to configure MCP servers in their skill YAML files will have their files rejected at parse time because `transport` is mandatory in the current schema but the spec shows it as optional/inferred. Additionally, the specification shows MCP server entries supporting an `overrides` field for per-tool capability metadata (e.g., marking specific tools as `writes: true`, specifying `write_scope`, or `read_only: true`). This field is entirely absent from the current schema — the schema only supports `tool_filter` (include/exclude filtering), not `overrides` (capability metadata overrides). **What was tested:** Code-level analysis of `src/cleveragents/skills/schema.py` against the skill YAML configuration section of `docs/specification.md`. --- ## Current Behavior `SkillMcpServerSchema` declares `transport` as a mandatory Pydantic field: ```python class SkillMcpServerSchema(BaseModel): name: str = Field(...) transport: str = Field(..., description="Transport protocol: stdio | sse | streamable-http.") # MANDATORY command: str | None = Field(default=None, ...) ... ``` A skill YAML following the spec (without explicit `transport`) fails with: ``` ValidationError: transport: Field required ``` The `overrides` field (for per-tool capability metadata) is also entirely absent from the schema. --- ## Expected Behavior Per `docs/specification.md`, the skill YAML configuration must accept MCP server entries without requiring an explicit `transport` field. Transport should be inferred: `command` present → `stdio`; `url` present → `sse` or `streamable-http`. The `overrides` field must also be supported for per-tool capability metadata. **Spec-compliant example that must parse successfully:** ```yaml skill: name: local/devops-toolkit mcp_servers: - name: linear command: "npx @anthropic/mcp-linear" env: LINEAR_API_KEY: "${LINEAR_API_KEY}" overrides: - tool: create_issue writes: true write_scope: [linear:issues] - tool: list_issues read_only: true ``` --- ## Steps to Reproduce 1. Create a skill YAML file using the spec-compliant MCP server config (no explicit `transport`): ```yaml name: local/test-skill description: Test skill mcp_servers: - name: linear command: "npx @anthropic/mcp-linear" env: LINEAR_API_KEY: "${LINEAR_API_KEY}" ``` 2. Call `SkillConfigSchema.from_yaml(yaml_content)` 3. **Observe:** Pydantic raises `ValidationError: transport: Field required` --- ## Acceptance Criteria - [ ] `SkillMcpServerSchema.transport` is optional (defaults to `None`); transport is inferred from `command` (→ `stdio`) or `url` (→ `sse`/`streamable-http`) via a Pydantic validator - [ ] A `SkillMcpServerToolOverrideSchema` model is added to represent per-tool capability metadata (`tool`, `writes`, `write_scope`, `read_only`) - [ ] `SkillMcpServerSchema` gains an `overrides: list[SkillMcpServerToolOverrideSchema]` field (optional, defaults to `[]`) - [ ] Spec-compliant skill YAML with no explicit `transport` parses without error - [ ] Spec-compliant skill YAML with `overrides` entries parses without error - [ ] Existing skill YAMLs that do include an explicit `transport` continue to parse correctly (backward compatible) - [ ] All Pyright type checks pass (`nox -e typecheck`) - [ ] All Behave unit tests pass (`nox -e unit_tests`) --- ## Supporting Information - **Code location:** `src/cleveragents/skills/schema.py` — `SkillMcpServerSchema` class - **Spec reference:** `docs/specification.md` — skill YAML configuration section (MCP server entries) - **Severity:** High — any user following the specification will encounter this validation failure immediately upon loading a spec-compliant skill YAML --- ## Metadata - **Branch**: `fix/skill-mcp-server-schema-optional-transport` - **Commit Message**: `fix(skills): make transport optional and add overrides to SkillMcpServerSchema` - **Milestone**: v3.7.0 - **Parent Epic**: #392 --- ## Subtasks - [ ] Make `transport` optional in `SkillMcpServerSchema` with inferred default via Pydantic `model_validator` - [ ] Add `SkillMcpServerToolOverrideSchema` model with fields: `tool: str`, `writes: bool`, `write_scope: list[str]`, `read_only: bool` - [ ] Add `overrides: list[SkillMcpServerToolOverrideSchema]` field to `SkillMcpServerSchema` (optional, default `[]`) - [ ] Tests (Behave): Add scenarios for MCP server config with no explicit transport (stdio inferred from `command`, SSE inferred from `url`) - [ ] Tests (Behave): Add scenarios for MCP server config with `overrides` entries - [ ] Tests (Behave): Add regression scenario confirming explicit `transport` still works - [ ] 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(skills): make transport optional and add overrides to SkillMcpServerSchema`), 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/skill-mcp-server-schema-optional-transport`). - 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.7.0 milestone

2026-04-03 04:16:43 +00:00

freemo added a new dependency

2026-04-03 04:17:40 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-03 04:20:11 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo referenced this issue

2026-04-03 04:22:00 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:04 +00:00

freemo commented

2026-04-03 18:28:14 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.

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

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner