MCP adjacent example: what the LLM would do

docs/workflow_capabilities.md

@@ -294,6 +294,23 @@ Recommended discovery order:
 4. Use `wf.workflow.call_capability` with a plain input object to test the
    selected contract once before composing it into a draft.
 
+For the copy-less wrapper authoring path, use:
+
+1. `wf.workflow.inspect_capability` to inspect the source capability and review
+   `wrapper_hints`.
+2. `wf.workflow.create_draft_workspace_from_capability` to create a patchable
+   draft workspace from those hints.
+3. Focused patch helpers such as `wf.workflow.set_step_input_map`,
+   `wf.workflow.set_step_output_map`, and `wf.workflow.set_draft_route` to fix
+   low-confidence hints or explicit `missing_decisions`.
+4. `wf.workflow.validate_draft_workspace` to refresh diagnostics.
+5. `wf.workflow.create_wrapper_from_workspace` to save the wrapper artifact.
+6. `wf.workflow.call_capability` with `workflow.<artifact_id>.v<version>` to
+   test the saved wrapper.
+
+See `examples/mcp_wrapper_authoring_flow.py` for the same flow through the
+Python handler layer.
+
 ## Wrapper Authoring Hints
 
 `wf.workflow.inspect_capability` returns `wrapper_hints` for planner-visible

examples/mcp_wrapper_authoring_flow.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from wf_artifacts import WorkflowDeployment
+from wf_mcp.workflow_surface import WorkflowSurfaceHandlers
+
+from mcp_workflow_surface import prepare_demo_service
+
+
+async def author_echo_wrapper_from_capability(root: Path) -> dict[str, Any]:
+    """Author, save, deploy, and run one wrapper from capability hints.
+
+    This mirrors the intended MCP client flow:
+    inspect one capability, create a patchable draft workspace from the returned
+    wrapper_hints, validate/save that workspace as a wrapper artifact, then test
+    the saved wrapper through `call_capability`.
+    """
+    service = await prepare_demo_service(root)
+    handlers = WorkflowSurfaceHandlers(service)
+
+    inspected = await handlers.inspect_capability(
+        qualified_name="demo.personal.echo_tool"
+    )
+    workspace = await handlers.create_draft_workspace_from_capability(
+        workspace_id="echo_wrapper_draft",
+        capability_name="demo.personal.echo_tool",
+        name="echo_wrapper",
+        title="Echo Wrapper Draft",
+    )
+    created = await handlers.create_wrapper_from_workspace(
+        workspace_id="echo_wrapper_draft",
+        artifact_id="echo_wrapper",
+        version=1,
+        title="Echo Wrapper",
+        outcomes=("ok", "error"),
+        source_bindings={"demo": "demo.personal"},
+    )
+
+    assert service.artifact_store is not None
+    service.artifact_store.save_deployment(
+        WorkflowDeployment(
+            id="echo_wrapper.personal",
+            artifact_id="echo_wrapper",
+            artifact_version=1,
+            bindings=[
+                {"logical_source": "demo", "concrete_source": "demo.personal"},
+                {"logical_source": "wf.std", "concrete_source": "wf.std"},
+            ],
+        )
+    )
+    called = await handlers.call_capability(
+        qualified_name="workflow.echo_wrapper.v1",
+        payload={"text": "hello"},
+        deployment_id="echo_wrapper.personal",
+    )
+    return {
+        "inspected_hints": inspected["wrapper_hints"],
+        "workspace": workspace,
+        "created": created,
+        "called": called,
+    }
+
+
+async def _amain() -> None:
+    root = Path("test-artifacts") / "examples" / "mcp_wrapper_authoring_flow"
+    payload = await author_echo_wrapper_from_capability(root)
+    print(payload["created"]["saved"], payload["called"]["outcome"])
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(_amain())