Skip to content

💫 Toolkit to help you get started with SDD or any other process!

15.6 KB
Raw Blame
"""Explicit MCP dispositions for the complete ``specify workflow`` hierarchy.

Only workflow.list has a shared operation and adapter. Unavailable records
describe the conservative union of CLI paths, not a future MCP contract.

Effect boundaries worth retaining when adapters are introduced:

* Project resolution does not load integrations by default
  (``specify_cli._require_specify_project``).
* Run/resume explicitly load integrations and custom steps before execution.
  Add/update also import custom steps while validating workflow definitions.
* Catalog search/info can write project caches. Authenticated HTTP can invoke
  ``az account get-access-token`` through the configured Azure CLI provider,
  so even discovery/download paths may require execution capability.
* Catalog configuration and overlay operations are local; step installation
  copies/validates Python packages without importing them. Its HTTP source
  paths can nevertheless invoke the authentication provider.

Unavailable entries retain prospective tool names for parity checks only;
they do not expand MCP discovery or the legacy server command catalog.
"""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path
from typing import Literal

from mcp.server import MCPServer

from ._operation_list import WORKFLOW_LIST_OPERATION
from .mcp_list import register as register_list

WorkflowDisposition = Literal["available", "unavailable", "excluded"]
WorkflowCapability = Literal[
    "local-read", "project-write", "execution", "self-modifying"
]
WorkflowNetworkAccess = Literal["none", "optional", "required"]


@dataclass(frozen=True)
class WorkflowToolInventory:
    """One hierarchy-owned MCP disposition for a registered workflow CLI leaf."""

    operation_id: str
    cli_path: str
    mcp_tool_name: str
    disposition_reason: str | None
    capabilities: frozenset[WorkflowCapability]
    network_access: WorkflowNetworkAccess
    contract_version: str | None = None
    disposition: WorkflowDisposition = "unavailable"


_LOCAL_READ: frozenset[WorkflowCapability] = frozenset({"local-read"})
_LOCAL_WRITE: frozenset[WorkflowCapability] = frozenset({"local-read", "project-write"})
_WRITE_AND_EXECUTION: frozenset[WorkflowCapability] = frozenset(
    {"local-read", "project-write", "execution"}
)

WORKFLOW_TOOLS = (
    WorkflowToolInventory(
        operation_id="workflow.add",
        cli_path="specify workflow add",
        mcp_tool_name="specify_workflow_add",
        disposition_reason=(
            "Source selection, custom-step loading, trust prompts and transactional "
            "installation remain CLI-owned; no shared typed add operation or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.disable",
        cli_path="specify workflow disable",
        mcp_tool_name="specify_workflow_disable",
        disposition_reason=(
            "The registry mutation uses _commands._set_workflow_enabled with CLI "
            "errors/output; no shared typed disable operation or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.enable",
        cli_path="specify workflow enable",
        mcp_tool_name="specify_workflow_enable",
        disposition_reason=(
            "The registry mutation uses _commands._set_workflow_enabled with CLI "
            "errors/output; no shared typed enable operation or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.info",
        cli_path="specify workflow info",
        mcp_tool_name="specify_workflow_info",
        disposition_reason=(
            "Installed-definition/catalog selection and result rendering remain in "
            "command_info; no shared typed info operation or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.list",
        cli_path="specify workflow list",
        mcp_tool_name="specify_workflow_list",
        disposition_reason=None,
        disposition="available",
        contract_version=WORKFLOW_LIST_OPERATION.contract_version,
        capabilities=WORKFLOW_LIST_OPERATION.capabilities,
        network_access=WORKFLOW_LIST_OPERATION.network_access,
    ),
    WorkflowToolInventory(
        operation_id="workflow.remove",
        cli_path="specify workflow remove",
        mcp_tool_name="specify_workflow_remove",
        disposition_reason=(
            "Staged directory removal and attempted directory recovery after registry "
            "failure remain in command_remove; no shared typed remove operation or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.resolve",
        cli_path="specify workflow resolve",
        mcp_tool_name="specify_workflow_resolve",
        disposition_reason=(
            "overlay.operations.workflow_resolve renders CLI diagnostics and returns "
            "a dictionary or None; no shared typed resolve outcome or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.resume",
        cli_path="specify workflow resume",
        mcp_tool_name="specify_workflow_resume",
        disposition_reason=(
            "Owner-root resolution, integration loading and CLI input/error mapping "
            "surround WorkflowEngine.resume; no shared typed resume contract or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.run",
        cli_path="specify workflow run",
        mcp_tool_name="specify_workflow_run",
        disposition_reason=(
            "Integration/custom-step loading, inputs and CLI error handling surround "
            "WorkflowEngine.execute; no shared typed run contract or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.search",
        cli_path="specify workflow search",
        mcp_tool_name="specify_workflow_search",
        disposition_reason=(
            "WorkflowCatalog.search supplies catalog data but command_search owns "
            "mapping/rendering; no shared typed search outcome or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.status",
        cli_path="specify workflow status",
        mcp_tool_name="specify_workflow_status",
        disposition_reason=(
            "RunState.load/list_runs results and JSON/error mapping are assembled in "
            "command_status; no shared typed status operation or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.update",
        cli_path="specify workflow update",
        mcp_tool_name="specify_workflow_update",
        disposition_reason=(
            "Custom-step loading, version selection, confirmation and installation "
            "remain CLI-owned; no shared typed update operation or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    # Catalog configuration reads/writes URLs; it does not fetch their contents.
    WorkflowToolInventory(
        operation_id="workflow.catalog.add",
        cli_path="specify workflow catalog add",
        mcp_tool_name="specify_workflow_catalog_add",
        disposition_reason=(
            "WorkflowCatalog.add_catalog mutates configuration, but its command-level "
            "request/error/outcome contract and MCP adapter are not defined."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.catalog.list",
        cli_path="specify workflow catalog list",
        mcp_tool_name="specify_workflow_catalog_list",
        disposition_reason=(
            "WorkflowCatalog.get_catalog_configs returns dictionaries rendered by the "
            "CLI; no shared typed catalog-list outcome or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.catalog.remove",
        cli_path="specify workflow catalog remove",
        mcp_tool_name="specify_workflow_catalog_remove",
        disposition_reason=(
            "WorkflowCatalog.remove_catalog owns configuration edits, but the CLI "
            "maps arguments/errors; no shared typed removal contract or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.add",
        cli_path="specify workflow overlay add",
        mcp_tool_name="specify_workflow_overlay_add",
        disposition_reason=(
            "workflow_overlay_add stages overlay files but prints CLI diagnostics and "
            "returns Path or None; no shared typed add contract or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.disable",
        cli_path="specify workflow overlay disable",
        mcp_tool_name="specify_workflow_overlay_disable",
        disposition_reason=(
            "workflow_overlay_disable uses CLI-bound overlay mutation/error helpers; "
            "no shared typed disable outcome or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.enable",
        cli_path="specify workflow overlay enable",
        mcp_tool_name="specify_workflow_overlay_enable",
        disposition_reason=(
            "workflow_overlay_enable uses CLI-bound overlay mutation/error helpers; "
            "no shared typed enable outcome or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.list",
        cli_path="specify workflow overlay list",
        mcp_tool_name="specify_workflow_overlay_list",
        disposition_reason=(
            "workflow_overlay_list prints CLI diagnostics and returns dictionaries "
            "or None; no shared typed list outcome or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.remove",
        cli_path="specify workflow overlay remove",
        mcp_tool_name="specify_workflow_overlay_remove",
        disposition_reason=(
            "workflow_overlay_remove deletes local files with CLI-bound error reporting; "
            "no shared typed remove outcome or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.overlay.set-priority",
        cli_path="specify workflow overlay set-priority",
        mcp_tool_name="specify_workflow_overlay_set_priority",
        disposition_reason=(
            "workflow_overlay_set_priority uses CLI-bound YAML mutation/error helpers; "
            "no shared typed priority-change outcome or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.add",
        cli_path="specify workflow step add",
        mcp_tool_name="specify_workflow_step_add",
        disposition_reason=(
            "Package validation/install helpers exist, but source/trust selection and "
            "command-level outcomes remain CLI-owned; no typed add contract or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.info",
        cli_path="specify workflow step info",
        mcp_tool_name="specify_workflow_step_info",
        disposition_reason=(
            "Builtin/installed/catalog selection and result rendering remain in "
            "command_info; no shared typed step-info outcome or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.list",
        cli_path="specify workflow step list",
        mcp_tool_name="specify_workflow_step_list",
        disposition_reason=(
            "The CLI combines STEP_REGISTRY and StepRegistry dictionaries for display; "
            "no shared typed step-list outcome or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.remove",
        cli_path="specify workflow step remove",
        mcp_tool_name="specify_workflow_step_remove",
        disposition_reason=(
            "Registry removal, direct package deletion and attempted registry restoration "
            "on deletion failure remain in command_remove; no shared typed step-remove "
            "operation or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.search",
        cli_path="specify workflow step search",
        mcp_tool_name="specify_workflow_step_search",
        disposition_reason=(
            "StepCatalog.search supplies catalog data but the CLI maps/renders it; "
            "no shared typed step-search outcome or MCP adapter."
        ),
        capabilities=_WRITE_AND_EXECUTION,
        network_access="optional",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.catalog.add",
        cli_path="specify workflow step catalog add",
        mcp_tool_name="specify_workflow_step_catalog_add",
        disposition_reason=(
            "StepCatalog.add_catalog mutates configuration, but its command-level "
            "request/error/outcome contract and MCP adapter are not defined."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.catalog.list",
        cli_path="specify workflow step catalog list",
        mcp_tool_name="specify_workflow_step_catalog_list",
        disposition_reason=(
            "StepCatalog.get_catalog_configs returns dictionaries rendered by the CLI; "
            "no shared typed step-catalog-list outcome or MCP adapter."
        ),
        capabilities=_LOCAL_READ,
        network_access="none",
    ),
    WorkflowToolInventory(
        operation_id="workflow.step.catalog.remove",
        cli_path="specify workflow step catalog remove",
        mcp_tool_name="specify_workflow_step_catalog_remove",
        disposition_reason=(
            "StepCatalog.remove_catalog edits configuration, but the CLI maps "
            "arguments/errors; no shared typed removal contract or MCP adapter."
        ),
        capabilities=_LOCAL_WRITE,
        network_access="none",
    ),
)


def register(server: MCPServer, *, launch_directory: Path) -> None:
    """Register only the workflow list operation from its owning hierarchy."""
    record = next(
        item for item in WORKFLOW_TOOLS if item.operation_id == "workflow.list"
    )
    if record.disposition == "available":
        register_list(
            server, launch_directory=launch_directory, tool_name=record.mcp_tool_name
        )