💫 Toolkit to help you get started with SDD or any other process!
Feat/4913 workflow mcp inventory (#5054)
Nishanth B8ab84fc92d4b
diff --git a/src/specify_cli/workflows/_mcp.py b/src/specify_cli/workflows/_mcp.pynew file mode 100644index 000000000..4477c00d7--- /dev/null+++ b/src/specify_cli/workflows/_mcp.py@@ -0,0 +1,377 @@+"""Explicit MCP dispositions for the complete ``specify workflow`` hierarchy.++No workflow adapter is registered yet. These records describe the conservative+union of the current CLI paths, not a promise of 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 typing import Literal++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=(+ "WorkflowRegistry.list returns registry dictionaries rendered by the CLI; "+ "no shared typed list outcome or MCP adapter."+ ),+ capabilities=_LOCAL_READ,+ network_access="none",+ ),+ 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",+ ),+)diff --git a/tests/specify_cli/workflows/test_mcp.py b/tests/specify_cli/workflows/test_mcp.pynew file mode 100644index 000000000..ff5676789--- /dev/null+++ b/tests/specify_cli/workflows/test_mcp.py@@ -0,0 +1,548 @@+"""Parity between real workflow CLI registration and its explicit MCP inventory."""++from __future__ import annotations++import asyncio+import io+import json+from collections import Counter+from collections.abc import Sequence+from dataclasses import FrozenInstanceError, replace+from types import SimpleNamespace+from typing import TypedDict++import pytest+from mcp.server import MCPServer+from mcp.types import Tool+from typer.core import TyperGroup+from typer.main import get_command+from typer.testing import CliRunner++from specify_cli import app+from specify_cli.mcp_server.catalog import (+ CommandAdapterError,+ describe_command,+ list_commands,+)+from specify_cli.mcp_server.server import create_server+from specify_cli.workflows import _commands, _mcp+from specify_cli.workflows.step import catalog as step_catalog+++def _workflow_cli_paths() -> list[str]:+ """Walk the registered CLI, including future nested groups, without dispatch."""+ root = get_command(app)++ def walk(group: TyperGroup, prefix: str) -> list[str]:+ paths = []+ for name, command in group.commands.items():+ path = f"{prefix} {name}"+ if isinstance(command, TyperGroup):+ paths.extend(walk(command, path))+ else:+ paths.append(path)+ return paths++ return walk(root.commands["workflow"], "specify workflow")+++def _assert_synthetic_discovery_shape(+ record: _mcp.WorkflowToolInventory, tools: Sequence[Tool]+) -> None:+ """Check discovery cardinality/schema shape, not operation correspondence."""+ matching = [tool for tool in tools if tool.name == record.mcp_tool_name]+ assert len(matching) == 1, (+ f"Expected exactly one registered tool for {record.operation_id}; got {len(matching)}"+ )+ tool = matching[0]+ assert tool.input_schema.get("type") == "object", (+ f"Missing input schema: {tool.name}"+ )+ assert tool.output_schema and tool.output_schema.get("type") == "object", (+ f"Missing output schema: {tool.name}"+ )+++def _assert_inventory(+ records: Sequence[_mcp.WorkflowToolInventory],+ cli_paths: Sequence[str],+ tools: Sequence[Tool],+) -> None:+ """Validate accounting and fail closed for available workflow records.++ No shared workflow operation descriptors exist yet. Real available records+ must fail closed until operation-specific assertions bind their descriptor,+ version, effects and adapter schemas, as in the artifact inventory tests.+ A matching name and object schemas alone cannot establish that binding.+ """+ for label, values in (+ ("operation IDs", [item.operation_id for item in records]),+ ("CLI paths", [item.cli_path for item in records]),+ ("tool names", [item.mcp_tool_name for item in records]),+ ):+ duplicates = sorted(+ value for value, count in Counter(values).items() if count > 1+ )+ assert not duplicates, f"Duplicate {label}: {duplicates}"++ inventory_paths = {item.cli_path for item in records}+ missing = sorted(set(cli_paths) - inventory_paths)+ stale = sorted(inventory_paths - set(cli_paths))+ assert not missing, f"Missing CLI paths: {missing}"+ assert not stale, f"Stale CLI paths: {stale}"++ for item in records:+ assert item.cli_path.startswith("specify workflow "), item.cli_path+ expected_id = item.cli_path.removeprefix("specify ").replace(" ", ".")+ assert item.operation_id == expected_id, (+ f"Invalid operation ID: {item.operation_id}"+ )+ expected_tool = "specify_" + expected_id.replace(".", "_").replace("-", "_")+ assert item.mcp_tool_name == expected_tool, (+ f"Invalid tool name: {item.mcp_tool_name}"+ )+ assert item.disposition in {"available", "unavailable", "excluded"}, (+ f"Invalid disposition: {item.operation_id}"+ )+ assert isinstance(item.capabilities, frozenset) and item.capabilities, (+ f"Invalid capabilities: {item.operation_id}"+ )+ assert item.capabilities <= {+ "local-read",+ "project-write",+ "execution",+ "self-modifying",+ }, f"Invalid capabilities: {item.operation_id}"+ assert item.network_access in {"none", "optional", "required"}, (+ f"Invalid network access: {item.operation_id}"+ )+ assert item.contract_version is None or (+ isinstance(item.contract_version, str) and item.contract_version.strip()+ ), f"Invalid contract version: {item.operation_id}"++ matching = [tool for tool in tools if tool.name == item.mcp_tool_name]+ if item.disposition == "available":+ assert item.contract_version, f"Missing contract: {item.operation_id}"+ assert item.disposition_reason is None, (+ f"Available reason: {item.operation_id}"+ )+ _assert_synthetic_discovery_shape(item, tools)+ raise AssertionError(+ f"No workflow operation contract evidence: {item.operation_id}"+ )+ else:+ assert item.contract_version is None, (+ f"Nonavailable tool has contract version: {item.operation_id}"+ )+ assert (+ isinstance(item.disposition_reason, str)+ and item.disposition_reason.strip()+ ), f"Missing disposition reason: {item.operation_id}"+ assert not matching, f"Nonavailable tool registered: {item.operation_id}"++ inventory_names = {item.mcp_tool_name for item in records}+ unexpected = sorted(+ tool.name+ for tool in tools+ if tool.name.startswith("specify_workflow_")+ and tool.name not in inventory_names+ )+ assert not unexpected, f"Uninventoried workflow tools: {unexpected}"+++def test_workflow_inventory_matches_actual_cli_and_server(tmp_path):+ server = create_server(launch_directory=tmp_path)+ tools = asyncio.run(server.list_tools())++ _assert_inventory(_mcp.WORKFLOW_TOOLS, _workflow_cli_paths(), tools)+++def test_inventory_records_are_immutable():+ with pytest.raises(FrozenInstanceError):+ _mcp.WORKFLOW_TOOLS[0].disposition = "available"++[email protected]("location", ["root", "nested"])+def test_new_registered_cli_leaf_requires_disposition(monkeypatch, location):+ target = _commands.workflow_app if location == "root" else step_catalog.catalog_app+ # Isolate the registration list before adding a command; monkeypatch restores+ # the original object, including on failure. Do not call register() again.+ monkeypatch.setattr(target, "registered_commands", list(target.registered_commands))++ @target.command("inventory-probe")+ def probe():+ raise AssertionError("CLI traversal must not execute handlers")++ path = (+ "specify workflow inventory-probe"+ if location == "root"+ else "specify workflow step catalog inventory-probe"+ )+ paths = _workflow_cli_paths()+ assert path in paths+ with pytest.raises(AssertionError, match="Missing CLI paths"):+ _assert_inventory(_mcp.WORKFLOW_TOOLS, paths, [])+++def test_missing_inventory_entry_is_rejected():+ with pytest.raises(AssertionError, match="Missing CLI paths"):+ _assert_inventory(_mcp.WORKFLOW_TOOLS[1:], _workflow_cli_paths(), [])+++def test_stale_inventory_entry_is_rejected():+ stale = replace(+ _mcp.WORKFLOW_TOOLS[0],+ operation_id="workflow.removed",+ cli_path="specify workflow removed",+ mcp_tool_name="specify_workflow_removed",+ )+ with pytest.raises(AssertionError, match="Stale CLI paths"):+ _assert_inventory((*_mcp.WORKFLOW_TOOLS, stale), _workflow_cli_paths(), [])+++ "field,label",+ [+ ("operation_id", "operation IDs"),+ ("cli_path", "CLI paths"),+ ("mcp_tool_name", "tool names"),+ ],+)+def test_duplicate_inventory_identity_is_rejected(field, label):+ records = list(_mcp.WORKFLOW_TOOLS)+ records[1] = replace(records[1], **{field: getattr(records[0], field)})+ with pytest.raises(AssertionError, match=f"Duplicate {label}"):+ _assert_inventory(records, _workflow_cli_paths(), [])+++ "changes,message",+ [+ ({"operation_id": "workflow.wrong"}, "Invalid operation ID"),+ ({"mcp_tool_name": "specify_workflow_wrong"}, "Invalid tool name"),+ ({"disposition": "unknown"}, "Invalid disposition"),+ ({"capabilities": frozenset()}, "Invalid capabilities"),+ ({"capabilities": frozenset({"read-only"})}, "Invalid capabilities"),+ ({"capabilities": {"local-read"}}, "Invalid capabilities"),+ ({"network_access": "sometimes"}, "Invalid network access"),+ ({"contract_version": " "}, "Invalid contract version"),+ ],+)+def test_invalid_inventory_metadata_is_rejected(changes, message):+ records = list(_mcp.WORKFLOW_TOOLS)+ records[0] = replace(records[0], **changes)+ with pytest.raises(AssertionError, match=message):+ _assert_inventory(records, _workflow_cli_paths(), [])++[email protected]("disposition", ["unavailable", "excluded"])[email protected]("reason", [None, "", " \n\t"])+def test_nonavailable_disposition_requires_explanation(disposition, reason):+ record = replace(+ _mcp.WORKFLOW_TOOLS[0],+ disposition=disposition,+ disposition_reason=reason,+ )+ with pytest.raises(AssertionError, match="Missing disposition reason"):+ _assert_inventory([record], [record.cli_path], [])++[email protected]("disposition", ["unavailable", "excluded"])+def test_nonavailable_record_cannot_declare_contract_version(disposition):+ record = replace(+ _mcp.WORKFLOW_TOOLS[0], disposition=disposition, contract_version="1"+ )+ with pytest.raises(AssertionError, match="Nonavailable tool has contract version"):+ _assert_inventory([record], [record.cli_path], [])+++class _ProbeResult(TypedDict):+ value: str+++class _UnrelatedResult(TypedDict):+ unrelated: int+++def available_record_and_tool():+ """Synthetic shape/count probe, not evidence of a workflow.add contract."""+ record = replace(+ _mcp.WORKFLOW_TOOLS[0],+ disposition="available",+ disposition_reason=None,+ contract_version="1",+ )+ server = MCPServer(name="workflow-inventory-test")++ def probe(value: str) -> _ProbeResult:+ return {"value": value}++ server.add_tool(probe, name=record.mcp_tool_name, structured_output=True)+ tools = asyncio.run(server.list_tools())+ assert len(tools) == 1+ return record, tools[0]++[email protected]("count", [0, 1, 2])+def test_available_record_requires_exactly_one_matching_tool(+ available_record_and_tool, count+):+ record, tool = available_record_and_tool+ tools = (+ [tool] * count+ ) # Duplicate discovery is invalid even if an SDK deduplicates registration.+ if count == 1:+ _assert_synthetic_discovery_shape(record, tools)+ else:+ with pytest.raises(+ AssertionError, match="Expected exactly one registered tool"+ ):+ _assert_synthetic_discovery_shape(record, tools)++[email protected]("version", ["1", "999-fabricated"])+def test_correctly_named_unrelated_contract_is_rejected(version):+ record = replace(+ _mcp.WORKFLOW_TOOLS[0],+ disposition="available",+ disposition_reason=None,+ contract_version=version,+ capabilities=frozenset({"local-read"}),+ network_access="none",+ )++ def unrelated_operation(unrelated: bool) -> _UnrelatedResult:+ return {"unrelated": int(unrelated)}++ server = MCPServer(name="wrong-workflow-contract")+ server.add_tool(+ unrelated_operation, name=record.mcp_tool_name, structured_output=True+ )+ tools = asyncio.run(server.list_tools())+ assert len(tools) == 1+ assert tools[0].input_schema["type"] == "object"+ assert tools[0].output_schema["type"] == "object"+ with pytest.raises(AssertionError, match="No workflow operation contract evidence"):+ _assert_inventory([record], [record.cli_path], tools)+++def test_synthetic_probe_cannot_establish_real_workflow_availability(+ available_record_and_tool,+):+ record, tool = available_record_and_tool+ _assert_synthetic_discovery_shape(record, [tool])+ with pytest.raises(AssertionError, match="No workflow operation contract evidence"):+ _assert_inventory([record], [record.cli_path], [tool])+++ "changes,message",+ [+ ({"contract_version": None}, "Missing contract"),+ ({"disposition_reason": "not ready"}, "Available reason"),+ ],+)+def test_available_record_requires_contract(+ available_record_and_tool, changes, message+):+ record, tool = available_record_and_tool+ with pytest.raises(AssertionError, match=message):+ _assert_inventory([replace(record, **changes)], [record.cli_path], [tool])+++ "schema,message",+ [+ ({"input_schema": {}}, "Missing input schema"),+ ({"output_schema": None}, "Missing output schema"),+ ],+)+def test_available_tool_requires_typed_schemas(+ available_record_and_tool, schema, message+):+ record, tool = available_record_and_tool+ with pytest.raises(AssertionError, match=message):+ _assert_synthetic_discovery_shape(record, [tool.model_copy(update=schema)])++[email protected]("disposition", ["unavailable", "excluded"])+def test_nonavailable_record_cannot_register_tool(+ available_record_and_tool, disposition+):+ record, tool = available_record_and_tool+ record = replace(+ record,+ disposition=disposition,+ disposition_reason="Not offered through MCP.",+ contract_version=None,+ )+ with pytest.raises(AssertionError, match="Nonavailable tool registered"):+ _assert_inventory([record], [record.cli_path], [tool])+++def test_matching_registration_cannot_be_replaced_by_different_tool(+ available_record_and_tool,+):+ record, tool = available_record_and_tool+ with pytest.raises(AssertionError, match="Expected exactly one registered tool"):+ _assert_inventory(+ [record], [record.cli_path], [tool.model_copy(update={"name": "other"})]+ )+++def test_uninventoried_workflow_tool_is_rejected(available_record_and_tool):+ _, tool = available_record_and_tool+ with pytest.raises(AssertionError, match="Uninventoried workflow tools"):+ _assert_inventory([], [], [tool])+++def test_existing_server_and_legacy_catalog_are_unchanged(tmp_path):+ tools = asyncio.run(create_server(launch_directory=tmp_path).list_tools())+ assert Counter(tool.name for tool in tools) == Counter(+ {+ "specify_version": 1,+ "specify_artifact_list": 1,+ "specify_artifact_info": 1,+ "specify_list_commands": 1,+ "specify_describe_command": 1,+ "specify_run_command": 1,+ }+ )+ assert [item.command for item in list_commands().commands] == ["version"]+ assert describe_command("version").command == "version"+ with pytest.raises(CommandAdapterError) as exc:+ describe_command("workflow.run")+ assert exc.value.code == "unavailable_command"++[email protected]("operation_id", ["workflow.run", "workflow.resume"])+def test_execution_command_effects_include_persistence_and_optional_network(+ operation_id,+):+ # command_run.workflow_run reads a definition and calls WorkflowEngine.execute;+ # command_resume.workflow_resume reads RunState and calls WorkflowEngine.resume.+ # Both engine paths save checkpoints and dispatch executable steps. Command+ # steps can run offline; prompt steps can invoke networked integrations, so+ # networking is optional rather than required. See step/command and step/prompt.+ record = next(+ item for item in _mcp.WORKFLOW_TOOLS if item.operation_id == operation_id+ )+ assert record.capabilities == frozenset(+ {"local-read", "project-write", "execution"}+ )+ assert record.network_access == "optional"++[email protected]("step", [False, True], ids=["workflow", "step"])+def test_catalog_discovery_effects_include_cache_and_auth_execution(+ tmp_path, monkeypatch, step+):+ """Follow real CLI -> catalog -> HTTP -> auth paths, mocking only external IO."""+ from specify_cli.authentication import azure_devops, http+ from specify_cli.authentication.config import AuthConfigEntry++ (tmp_path / ".specify").mkdir()+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path))+ url = "https://inventory.invalid/catalog.json"+ monkeypatch.setenv(+ "SPECKIT_STEP_CATALOG_URL" if step else "SPECKIT_WORKFLOW_CATALOG_URL", url+ )+ monkeypatch.setattr(+ http,+ "_config_override",+ [+ AuthConfigEntry(+ hosts=("inventory.invalid",), provider="azure-devops", auth="azure-cli"+ ),+ ],+ )+ processes = []+ requests = []++ def run(argv, **kwargs):+ processes.append(argv)+ return SimpleNamespace(+ returncode=0, stdout='{"accessToken": "test-only"}', stderr=""+ )++ class Response(io.BytesIO):+ headers = {}++ def geturl(self):+ return url++ def open_request(request, **kwargs):+ requests.append(request.full_url)+ return Response(json.dumps({"steps" if step else "workflows": {}}).encode())++ monkeypatch.setattr(azure_devops.subprocess, "run", run)+ monkeypatch.setattr(+ http.urllib.request,+ "build_opener",+ lambda *args: SimpleNamespace(open=open_request),+ )+ args = ["workflow", "step", "search"] if step else ["workflow", "search"]+ result = CliRunner().invoke(app, args)+ assert result.exit_code == 0, result.output+ assert requests == [url]+ assert len(processes) == 1+ assert processes[0][1:3] == ["account", "get-access-token"]+ cache = tmp_path / ".specify" / "workflows"+ if step:+ cache /= "steps"+ assert len(list((cache / ".cache").glob("*.json"))) == 2++ operation = "workflow.step.search" if step else "workflow.search"+ record = next(+ item for item in _mcp.WORKFLOW_TOOLS if item.operation_id == operation+ )+ assert record.capabilities == frozenset(+ {"local-read", "project-write", "execution"}+ )+ assert record.network_access == "optional"++ # A warm cache needs neither network nor an authentication subprocess:+ # the static declaration is a union, not a claim every invocation uses IO.+ result = CliRunner().invoke(app, args)+ assert result.exit_code == 0, result.output+ assert requests == [url]+ assert len(processes) == 1+++ "suffix",+ [["list"], ["catalog", "list"], ["step", "list"], ["step", "catalog", "list"]],+)+def test_local_inventory_queries_do_not_load_integrations_or_fetch(+ tmp_path, monkeypatch, suffix+):+ from specify_cli.authentication import http+ from specify_cli.integrations import installer++ (tmp_path / ".specify").mkdir()+ monkeypatch.setenv("SPECIFY_INIT_DIR", str(tmp_path))+ # Use explicit catalog configuration rather than the operator's home files.+ monkeypatch.setenv(+ "SPECKIT_WORKFLOW_CATALOG_URL", "https://inventory.invalid/workflows.json"+ )+ monkeypatch.setenv(+ "SPECKIT_STEP_CATALOG_URL", "https://inventory.invalid/steps.json"+ )++ def unexpected(*args, **kwargs):+ pytest.fail(+ "A local inventory query must not load integrations or fetch catalogs"+ )++ monkeypatch.setattr(installer, "load_installed_integrations", unexpected)+ monkeypatch.setattr(http, "open_url", unexpected)+ result = CliRunner().invoke(app, ["workflow", *suffix])+ assert result.exit_code == 0, result.output+ record = next(+ item+ for item in _mcp.WORKFLOW_TOOLS+ if item.cli_path == " ".join(["specify", "workflow", *suffix])+ )+ assert record.capabilities == frozenset({"local-read"})+ assert record.network_access == "none"