docs, manuals
This commit is contained in:
@@ -4,6 +4,9 @@
|
||||
The goal is to keep future package extraction cheap without adding packaging
|
||||
overhead before the APIs settle.
|
||||
|
||||
For the short operator-facing map of the current nouns and tool families, start
|
||||
with [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
|
||||
|
||||
## Packages
|
||||
|
||||
| Package | Responsibility |
|
||||
|
||||
@@ -5,6 +5,9 @@ Tools, workflow node specs, prompts, resources, and admin controls all belong to
|
||||
a source. The MCP server, workflow planning, and future UI surfaces are
|
||||
projections of those sources.
|
||||
|
||||
If you need the practical "which thing do I call?" view before the domain model,
|
||||
start with [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
|
||||
|
||||
This avoids the current trap where broker admin tools, transparent proxy admin
|
||||
tools, workflow node specs, and upstream MCP tools all look like unrelated
|
||||
systems.
|
||||
|
||||
@@ -0,0 +1,462 @@
|
||||
# wf_mcp End-To-End Runbook
|
||||
|
||||
This runbook shows one complete successful path through the platform:
|
||||
|
||||
```text
|
||||
configured connection
|
||||
-> refreshed catalog
|
||||
-> source/capability discovery
|
||||
-> direct capability test
|
||||
-> saved workflow artifact
|
||||
-> saved deployment
|
||||
-> validated deployment
|
||||
-> deployment run
|
||||
```
|
||||
|
||||
The example uses an imaginary upstream MCP connection:
|
||||
|
||||
```text
|
||||
demo.personal
|
||||
```
|
||||
|
||||
which exposes one workflow-ready capability:
|
||||
|
||||
```text
|
||||
demo.personal.echo_tool
|
||||
```
|
||||
|
||||
The saved artifact uses the logical source alias `demo`, so the same workflow can
|
||||
later be deployed against `demo.work` or another compatible account.
|
||||
|
||||
## 0. Know The Three Names
|
||||
|
||||
This example deliberately uses three related names:
|
||||
|
||||
| Name | Meaning |
|
||||
| --- | --- |
|
||||
| `demo.personal` | concrete configured connection/source |
|
||||
| `demo.personal.echo_tool` | concrete discovered workflow capability |
|
||||
| `demo.echo_tool` | logical capability ref stored in the saved artifact |
|
||||
|
||||
The deployment later binds:
|
||||
|
||||
```json
|
||||
{
|
||||
"demo": "demo.personal"
|
||||
}
|
||||
```
|
||||
|
||||
That is the important separation between reusable workflow definition and
|
||||
concrete account choice.
|
||||
|
||||
## 1. Add Or Confirm The Connection
|
||||
|
||||
If the connection does not exist yet:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.add_connection
|
||||
arguments:
|
||||
{
|
||||
"connection_id": "demo.personal",
|
||||
"server": "demo",
|
||||
"account": "personal",
|
||||
"metadata": {
|
||||
"transport": "stdio",
|
||||
"command": "python",
|
||||
"args": ["path/to/demo_server.py"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If it already exists, inspect the configured set:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.list_connections
|
||||
arguments: {}
|
||||
```
|
||||
|
||||
Expected idea:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "demo.personal",
|
||||
"server": "demo",
|
||||
"account": "personal",
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 2. Refresh The Upstream Catalog
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.refresh_connection_catalog
|
||||
arguments:
|
||||
{
|
||||
"connection_id": "demo.personal"
|
||||
}
|
||||
```
|
||||
|
||||
This is the discovery step. It asks the upstream MCP server what it currently
|
||||
exposes and updates the stored catalog snapshot.
|
||||
|
||||
After this succeeds, these views become useful:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.get_catalog
|
||||
arguments: {}
|
||||
```
|
||||
|
||||
for the raw upstream MCP snapshot, and:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.get_planner_catalog
|
||||
arguments: {}
|
||||
```
|
||||
|
||||
for the planner-facing node-spec view.
|
||||
|
||||
Prefer the progressive-discovery tools below for ordinary use; full catalogs can
|
||||
be large.
|
||||
|
||||
## 3. Discover The Source
|
||||
|
||||
First list compact source summaries:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.list_sources
|
||||
arguments:
|
||||
{
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
Then inspect only the source you care about:
|
||||
|
||||
```yaml
|
||||
tool: wf.admin.inspect_source
|
||||
arguments:
|
||||
{
|
||||
"source_id": "demo.personal"
|
||||
}
|
||||
```
|
||||
|
||||
You want to confirm:
|
||||
|
||||
- the source is enabled
|
||||
- it is planner-visible
|
||||
- it owns the expected generated node spec / workflow capability
|
||||
|
||||
## 4. Discover And Inspect The Workflow Capability
|
||||
|
||||
Find the workflow-ready capability:
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.list_capabilities
|
||||
arguments:
|
||||
{
|
||||
"source_id": "demo.personal",
|
||||
"query": "echo",
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
Then inspect its full contract:
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.inspect_capability
|
||||
arguments:
|
||||
{
|
||||
"qualified_name": "demo.personal.echo_tool"
|
||||
}
|
||||
```
|
||||
|
||||
This is where you learn:
|
||||
|
||||
- input schema
|
||||
- output schema
|
||||
- declared outcomes
|
||||
- whether it is async
|
||||
- whether it is actually a good workflow-facing contract
|
||||
|
||||
## 5. Test The Capability Directly
|
||||
|
||||
Before composing a workflow, call the node contract once:
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.call_capability
|
||||
arguments:
|
||||
{
|
||||
"qualified_name": "demo.personal.echo_tool",
|
||||
"payload": {
|
||||
"text": "hello"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"outcome": "ok",
|
||||
"output": {
|
||||
"echoed": "hello"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is the authoring REPL step. It tests the workflow-facing contract, not just
|
||||
the raw upstream MCP tool call.
|
||||
|
||||
## 6. Save A Workflow Artifact
|
||||
|
||||
Create a one-node workflow that:
|
||||
|
||||
- accepts `input.text`
|
||||
- calls the discovered echo capability
|
||||
- stores `echoed` into workflow state
|
||||
- ends on the node's `ok` outcome
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.create_artifact_from_plan
|
||||
arguments:
|
||||
{
|
||||
"artifact_id": "echo",
|
||||
"version": 1,
|
||||
"title": "Echo",
|
||||
"outcomes": ["completed"],
|
||||
"source_bindings": {
|
||||
"demo": "demo.personal"
|
||||
},
|
||||
"plan": {
|
||||
"name": "echo",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"text": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["text"]
|
||||
},
|
||||
"state_schema": {
|
||||
"fields": {
|
||||
"echoed": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"output_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"echoed": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["echoed"]
|
||||
},
|
||||
"start": "echo",
|
||||
"nodes": [
|
||||
{
|
||||
"id": "echo",
|
||||
"type": "node",
|
||||
"node": "demo.personal.echo_tool",
|
||||
"in_map": {
|
||||
"input.text": "text"
|
||||
},
|
||||
"out_map": {
|
||||
"echoed": "state.echoed"
|
||||
}
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"from": "echo",
|
||||
"outcome": "ok",
|
||||
"to": "__end__"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Important behavior:
|
||||
|
||||
- because `source_bindings` says `"demo": "demo.personal"`, the saved artifact
|
||||
is normalized to logical node ref `demo.echo_tool`
|
||||
- the saved dependency contract records what was observed from
|
||||
`demo.personal.echo_tool` at creation time
|
||||
|
||||
Inspect the saved result if needed:
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.inspect_artifact
|
||||
arguments:
|
||||
{
|
||||
"artifact_id": "echo",
|
||||
"version": 1
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Save A Deployment
|
||||
|
||||
Artifacts are reusable definitions. Deployments decide which concrete sources
|
||||
run them.
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.save_deployment
|
||||
arguments:
|
||||
{
|
||||
"deployment": {
|
||||
"id": "echo.personal",
|
||||
"artifact_id": "echo",
|
||||
"artifact_version": 1,
|
||||
"bindings": {
|
||||
"demo": "demo.personal",
|
||||
"wf.std": "wf.std"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `wf.std` self-binding is present when the saved graph depends on standard
|
||||
library capabilities. This tiny echo graph does not need much from `wf.std`, but
|
||||
keeping local system-source bindings explicit is the current general pattern.
|
||||
|
||||
## 8. Validate Before Running
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.validate_deployment
|
||||
arguments:
|
||||
{
|
||||
"deployment_id": "echo.personal"
|
||||
}
|
||||
```
|
||||
|
||||
You want a runnable result with no blocking diagnostics.
|
||||
|
||||
Validation catches problems such as:
|
||||
|
||||
- a bound source is disabled or missing
|
||||
- a required capability disappeared
|
||||
- the saved dependency schema snapshot drifted from the live capability
|
||||
|
||||
## 9. Run The Deployment
|
||||
|
||||
```yaml
|
||||
tool: wf.workflow.run_deployment
|
||||
arguments:
|
||||
{
|
||||
"deployment_id": "echo.personal",
|
||||
"workflow_input": {
|
||||
"text": "hello"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Expected shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "completed",
|
||||
"output": {
|
||||
"echoed": "hello"
|
||||
},
|
||||
"diagnostics": [],
|
||||
"trace_count": 1
|
||||
}
|
||||
```
|
||||
|
||||
## 10. Rebind The Same Artifact Later
|
||||
|
||||
If another compatible account appears:
|
||||
|
||||
```text
|
||||
demo.work
|
||||
```
|
||||
|
||||
you do **not** need to rewrite artifact version `1`.
|
||||
|
||||
Create another deployment:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "echo.work",
|
||||
"artifact_id": "echo",
|
||||
"artifact_version": 1,
|
||||
"bindings": {
|
||||
"demo": "demo.work",
|
||||
"wf.std": "wf.std"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then validate it. If `demo.work.echo_tool` is compatible with the saved contract,
|
||||
the same workflow artifact can run there.
|
||||
|
||||
## Full Minimal Sequence
|
||||
|
||||
For a client that already has an enabled connection, the normal minimal flow is:
|
||||
|
||||
```text
|
||||
wf.admin.refresh_connection_catalog
|
||||
wf.admin.list_sources
|
||||
wf.workflow.list_capabilities
|
||||
wf.workflow.inspect_capability
|
||||
wf.workflow.call_capability
|
||||
wf.workflow.create_artifact_from_plan
|
||||
wf.workflow.save_deployment
|
||||
wf.workflow.validate_deployment
|
||||
wf.workflow.run_deployment
|
||||
```
|
||||
|
||||
## Common Failure Points
|
||||
|
||||
### The connection exists but nothing is discoverable
|
||||
|
||||
Check:
|
||||
|
||||
1. `wf.admin.list_connections`
|
||||
2. `wf.admin.refresh_connection_catalog`
|
||||
3. `wf.admin.inspect_source`
|
||||
|
||||
A configured connection can exist with zero loaded capabilities until refresh
|
||||
succeeds.
|
||||
|
||||
### The upstream server has tools but no prompts/resources
|
||||
|
||||
That is valid. `resources/list` and `prompts/list` are optional MCP families.
|
||||
A tools-only server should still refresh successfully.
|
||||
|
||||
### The raw proxy tool is callable but not pleasant in a graph
|
||||
|
||||
That is the raw-tool versus workflow-capability distinction. Use or build a
|
||||
workflow-facing wrapper when the raw tool's shape is provider-centric.
|
||||
|
||||
### The deployment used to run but now fails validation
|
||||
|
||||
Likely causes:
|
||||
|
||||
- source disabled
|
||||
- capability removed
|
||||
- schema drift from the saved dependency snapshot
|
||||
|
||||
Inspect:
|
||||
|
||||
```text
|
||||
wf.admin.inspect_source
|
||||
wf.workflow.inspect_artifact
|
||||
wf.workflow.validate_deployment
|
||||
```
|
||||
|
||||
## Read Next
|
||||
|
||||
- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md) for the short mental
|
||||
model and tool-family map
|
||||
- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md) for non-happy-path
|
||||
discovery and deployment failures
|
||||
- [`workflow_capabilities.md`](workflow_capabilities.md) for raw tool versus
|
||||
workflow capability
|
||||
- [`workflow_artifacts.md`](workflow_artifacts.md) for immutable artifacts,
|
||||
deployments, and dependency contracts
|
||||
@@ -0,0 +1,293 @@
|
||||
# wf_mcp Operator Manual
|
||||
|
||||
This is the short practical map for using the current MCP-facing platform.
|
||||
|
||||
Use this document when you need to answer:
|
||||
|
||||
- what object am I looking at?
|
||||
- which tool family manages it?
|
||||
- what is the normal path from "I connected a server" to "a workflow runs"?
|
||||
|
||||
For deeper design notes, follow the links at the end.
|
||||
|
||||
## What This Server Is
|
||||
|
||||
The public MCP server exposes three kinds of things at once:
|
||||
|
||||
1. proxied upstream MCP capabilities such as `everything.default.echo`
|
||||
2. local control-plane tools such as `wf.admin.list_sources`
|
||||
3. local workflow authoring/runtime tools such as
|
||||
`wf.workflow.list_capabilities`
|
||||
|
||||
Those are different surfaces over one platform. They should not be confused
|
||||
with each other just because MCP transports them all.
|
||||
|
||||
## The Nouns
|
||||
|
||||
| Noun | Meaning | Example |
|
||||
| --- | --- | --- |
|
||||
| Connection | A configured upstream MCP account/profile with auth and transport settings. | `everything.default` |
|
||||
| Source | A named owner of capabilities. A source may be local or backed by a connection. | `wf.std`, `wf.mcp`, `everything.default` |
|
||||
| Catalog | A discovered snapshot of backend MCP capabilities. | tools/resources/prompts loaded from `everything.default` |
|
||||
| Workflow capability | A workflow-ready `NodeSpec` contract that graphs can consume. | `wf.std.runtime_error`, `everything.default.echo` |
|
||||
| Artifact | An immutable saved workflow definition or saved wrapper workflow. | `codex_echo_probe` version `2` |
|
||||
| Deployment | A runnable binding from an artifact version to concrete runtime sources. | `codex_echo_probe.prod` |
|
||||
|
||||
The most important split:
|
||||
|
||||
```text
|
||||
connection != source
|
||||
raw MCP tool != workflow capability
|
||||
artifact != deployment
|
||||
```
|
||||
|
||||
## The Surfaces
|
||||
|
||||
### `wf.admin`
|
||||
|
||||
Privileged control plane.
|
||||
|
||||
Use it for:
|
||||
|
||||
- registering and editing connections
|
||||
- refreshing backend catalogs
|
||||
- inspecting configured sources
|
||||
- reading platform status and events
|
||||
- mutating config
|
||||
|
||||
Typical tools:
|
||||
|
||||
- `wf.admin.list_connections`
|
||||
- `wf.admin.add_connection`
|
||||
- `wf.admin.refresh_connection_catalog`
|
||||
- `wf.admin.list_sources`
|
||||
- `wf.admin.inspect_source`
|
||||
- `wf.admin.get_catalog`
|
||||
- `wf.admin.get_planner_catalog`
|
||||
|
||||
`wf.admin` is not meant to be a normal workflow dependency.
|
||||
|
||||
### `wf.workflow`
|
||||
|
||||
Workflow authoring and execution surface.
|
||||
|
||||
Use it for:
|
||||
|
||||
- discovering workflow-ready capabilities
|
||||
- inspecting and directly test-calling one capability
|
||||
- creating saved artifacts
|
||||
- listing and inspecting saved artifacts
|
||||
- saving deployments
|
||||
- validating and running deployments
|
||||
|
||||
Typical tools:
|
||||
|
||||
- `wf.workflow.list_capabilities`
|
||||
- `wf.workflow.inspect_capability`
|
||||
- `wf.workflow.call_capability`
|
||||
- `wf.workflow.create_artifact_from_plan`
|
||||
- `wf.workflow.list_artifacts`
|
||||
- `wf.workflow.inspect_artifact`
|
||||
- `wf.workflow.save_deployment`
|
||||
- `wf.workflow.validate_deployment`
|
||||
- `wf.workflow.run_deployment`
|
||||
|
||||
### Proxied Upstream Tools
|
||||
|
||||
These are the upstream MCP tools themselves, projected under connection/source
|
||||
names such as:
|
||||
|
||||
```text
|
||||
everything.default.echo
|
||||
context7.default.query_docs
|
||||
```
|
||||
|
||||
They are useful for direct interactive use and for capability discovery. They
|
||||
are not automatically good workflow abstractions; a workflow may want a cleaner
|
||||
wrapper with explicit outcomes and a smaller contract.
|
||||
|
||||
## Human Operator Workflow
|
||||
|
||||
### 1. Register Or Update A Connection
|
||||
|
||||
Use the config/admin surface:
|
||||
|
||||
```text
|
||||
wf.admin.add_connection
|
||||
wf.admin.update_connection
|
||||
wf.admin.enable_connection
|
||||
wf.admin.disable_connection
|
||||
```
|
||||
|
||||
A connection can exist before any catalog has been fetched. In that state it
|
||||
should still appear as a source with zero discovered capabilities.
|
||||
|
||||
### 2. Refresh Its Catalog
|
||||
|
||||
```text
|
||||
wf.admin.refresh_connection_catalog
|
||||
```
|
||||
|
||||
This asks the upstream MCP server for its current supported capability families.
|
||||
`tools/list` is required for workflow-facing discovery. `resources/list` and
|
||||
`prompts/list` are optional; a server that does not implement them can still be
|
||||
a valid tools-only source.
|
||||
|
||||
### 3. Inspect The Platform View
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
wf.admin.list_sources
|
||||
wf.admin.inspect_source
|
||||
wf.admin.get_catalog
|
||||
wf.admin.get_planner_catalog
|
||||
```
|
||||
|
||||
Prefer `list_sources` first. It is the compact inventory. Inspect one source
|
||||
only when you need its full owned-capability list.
|
||||
|
||||
### 4. Manage Saved Workflows
|
||||
|
||||
Use `wf.workflow.*` for artifacts and deployments:
|
||||
|
||||
```text
|
||||
create artifact -> inspect artifact -> save deployment -> validate deployment
|
||||
```
|
||||
|
||||
Artifacts are immutable saved definitions. Deployments are where those saved
|
||||
definitions bind to concrete runtime sources/accounts.
|
||||
|
||||
## LLM Client Workflow
|
||||
|
||||
An LLM author should usually avoid starting from giant raw catalogs.
|
||||
|
||||
### 1. Discover Sources
|
||||
|
||||
```text
|
||||
wf.admin.list_sources
|
||||
```
|
||||
|
||||
This tells the client what exists and which sources are planner-visible.
|
||||
|
||||
### 2. Discover Workflow-Ready Capabilities
|
||||
|
||||
```text
|
||||
wf.workflow.list_capabilities
|
||||
wf.workflow.inspect_capability
|
||||
```
|
||||
|
||||
Use the compact list first, then inspect only the likely candidates.
|
||||
|
||||
### 3. Test One Capability Directly
|
||||
|
||||
```text
|
||||
wf.workflow.call_capability
|
||||
```
|
||||
|
||||
This is the workflow-facing REPL step. It is different from directly calling a
|
||||
raw upstream MCP tool because it exercises the `NodeSpec` contract that the
|
||||
graph would consume.
|
||||
|
||||
### 4. Build And Save
|
||||
|
||||
```text
|
||||
wf.workflow.create_artifact_from_plan
|
||||
wf.workflow.save_deployment
|
||||
```
|
||||
|
||||
Artifacts should prefer logical source aliases in saved plans. Deployments bind
|
||||
those logical aliases to concrete sources such as `context7.default`.
|
||||
|
||||
### 5. Validate And Run
|
||||
|
||||
```text
|
||||
wf.workflow.validate_deployment
|
||||
wf.workflow.run_deployment
|
||||
```
|
||||
|
||||
Use `run_deployment` rather than expecting newly saved workflows to appear as
|
||||
brand-new MCP tools. Many LLM harnesses do not reliably refresh callable tool
|
||||
schemas mid-session.
|
||||
|
||||
## Which Tool Do I Use?
|
||||
|
||||
| I want to... | Use |
|
||||
| --- | --- |
|
||||
| See configured upstream accounts | `wf.admin.list_connections` |
|
||||
| Add or edit an upstream account | `wf.admin.add_connection`, `wf.admin.update_connection` |
|
||||
| Re-fetch what an upstream server exposes | `wf.admin.refresh_connection_catalog` |
|
||||
| See all capability owners | `wf.admin.list_sources` |
|
||||
| See everything one source owns | `wf.admin.inspect_source` |
|
||||
| See raw backend MCP snapshots | `wf.admin.get_catalog` |
|
||||
| See planner-visible workflow-ready nodes | `wf.admin.get_planner_catalog` or preferably `wf.workflow.list_capabilities` |
|
||||
| Find one workflow-ready node | `wf.workflow.list_capabilities` |
|
||||
| Read one node contract in full | `wf.workflow.inspect_capability` |
|
||||
| Test one node directly | `wf.workflow.call_capability` |
|
||||
| Save a workflow definition | `wf.workflow.create_artifact_from_plan` |
|
||||
| List saved workflows/wrappers | `wf.workflow.list_artifacts` |
|
||||
| Bind a saved workflow to concrete sources | `wf.workflow.save_deployment` |
|
||||
| Check whether a deployment can run | `wf.workflow.validate_deployment` |
|
||||
| Execute a saved workflow | `wf.workflow.run_deployment` |
|
||||
|
||||
## Common Confusions
|
||||
|
||||
### `get_catalog` Versus `get_planner_catalog`
|
||||
|
||||
`get_catalog` is the backend MCP snapshot view. It answers:
|
||||
|
||||
```text
|
||||
what did upstream MCP connections expose?
|
||||
```
|
||||
|
||||
`get_planner_catalog` is the workflow-planning view. It answers:
|
||||
|
||||
```text
|
||||
what workflow-ready node specs can the planner use?
|
||||
```
|
||||
|
||||
The second includes local workflow sources such as `wf.std` and `wf.mcp`; the
|
||||
first does not.
|
||||
|
||||
### Source Versus Connection
|
||||
|
||||
Every upstream connection becomes a source, but not every source is a
|
||||
connection.
|
||||
|
||||
Examples:
|
||||
|
||||
- `everything.default`: both a connection and a source
|
||||
- `wf.std`: a local source, not a connection
|
||||
- `wf.admin`: a privileged local source, not a connection
|
||||
|
||||
### Raw Tool Versus Workflow Capability
|
||||
|
||||
A raw MCP tool is shaped for the provider. A workflow capability is shaped for
|
||||
graph composition.
|
||||
|
||||
A raw tool can be directly callable and still be an awkward workflow node if it
|
||||
uses provider-specific result envelopes, status strings, or transport-level
|
||||
errors where a graph wants explicit outcomes.
|
||||
|
||||
### Artifact Versus Deployment
|
||||
|
||||
An artifact is the immutable saved workflow definition.
|
||||
|
||||
A deployment is the runnable instance that binds it to concrete source choices.
|
||||
Different deployments can point the same artifact version at different MCP
|
||||
accounts.
|
||||
|
||||
## Read Next
|
||||
|
||||
- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md) for one full
|
||||
connection-to-deployment example
|
||||
- [`wf_mcp_troubleshooting.md`](wf_mcp_troubleshooting.md) for missing-source,
|
||||
missing-capability, and unrunnable-deployment cases
|
||||
- [`wf_mcp_architecture.md`](wf_mcp_architecture.md) for package boundaries and
|
||||
hot-reload behavior
|
||||
- [`wf_mcp_capability_sources.md`](wf_mcp_capability_sources.md) for the source
|
||||
model
|
||||
- [`workflow_capabilities.md`](workflow_capabilities.md) for raw versus
|
||||
workflow-facing capability design
|
||||
- [`workflow_artifacts.md`](workflow_artifacts.md) for immutable artifacts,
|
||||
deployments, and saved workflows as future nodes
|
||||
@@ -0,0 +1,366 @@
|
||||
# wf_mcp Troubleshooting
|
||||
|
||||
This guide is organized by symptom. It assumes you already know the normal flow
|
||||
from [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md).
|
||||
|
||||
Use the smallest useful inspection first. Prefer compact discovery tools before
|
||||
dumping full catalogs.
|
||||
|
||||
## Quick Triage Ladder
|
||||
|
||||
When something is missing or will not run, inspect in this order:
|
||||
|
||||
1. `wf.admin.list_connections`
|
||||
2. `wf.admin.list_sources`
|
||||
3. `wf.admin.inspect_source`
|
||||
4. `wf.workflow.list_capabilities`
|
||||
5. `wf.workflow.inspect_capability`
|
||||
6. `wf.workflow.validate_deployment`
|
||||
|
||||
That sequence tells you whether the problem is:
|
||||
|
||||
- no configured connection
|
||||
- no source
|
||||
- no discovered capabilities
|
||||
- no workflow-ready capability
|
||||
- or a saved deployment dependency problem
|
||||
|
||||
## A Connection Exists But No Source Appears
|
||||
|
||||
Check:
|
||||
|
||||
```text
|
||||
wf.admin.list_connections
|
||||
wf.admin.list_sources
|
||||
```
|
||||
|
||||
Expected model:
|
||||
|
||||
- configured upstream connections should appear as connection sources even
|
||||
before a catalog snapshot has been fetched
|
||||
- a newly added source may have zero capabilities until refresh succeeds
|
||||
|
||||
If the connection exists but its source does not appear, that is a platform bug,
|
||||
not a normal "refresh first" state.
|
||||
|
||||
## A Source Exists But Has No Capabilities
|
||||
|
||||
Check:
|
||||
|
||||
```text
|
||||
wf.admin.inspect_source
|
||||
wf.admin.refresh_connection_catalog
|
||||
```
|
||||
|
||||
Likely causes:
|
||||
|
||||
- the source was never refreshed
|
||||
- refresh failed
|
||||
- the upstream server exposes no usable capabilities
|
||||
|
||||
Important distinction:
|
||||
|
||||
- `tools/list` is the important workflow-facing discovery family
|
||||
- `resources/list` and `prompts/list` are optional MCP families
|
||||
|
||||
A tools-only server that returns MCP `Method not found` for prompts/resources is
|
||||
still valid and should refresh successfully.
|
||||
|
||||
## I Refreshed But Still Cannot Find The Capability
|
||||
|
||||
Check both views:
|
||||
|
||||
```text
|
||||
wf.admin.inspect_source
|
||||
wf.workflow.list_capabilities
|
||||
```
|
||||
|
||||
If the source inventory shows an upstream **tool** but
|
||||
`wf.workflow.list_capabilities` does not show a corresponding planner-visible
|
||||
node spec, the capability may not currently be projected as workflow-ready.
|
||||
|
||||
Remember:
|
||||
|
||||
```text
|
||||
raw upstream tool != workflow capability
|
||||
```
|
||||
|
||||
The raw tool can still be callable through the proxy while not being a pleasant
|
||||
or allowed workflow node.
|
||||
|
||||
## The Tool Exists In The Server, But My LLM Client Cannot Call It
|
||||
|
||||
This can be a harness/tool-list refresh problem rather than a server problem.
|
||||
|
||||
Symptoms:
|
||||
|
||||
- the MCP server's `tools/list` changed
|
||||
- inspector or logs show the new tool
|
||||
- the current LLM turn still cannot call it
|
||||
|
||||
Some LLM harnesses do not reliably rebuild callable tool schemas after
|
||||
`tools/list` changes mid-session. The platform therefore keeps stable tools such
|
||||
as:
|
||||
|
||||
```text
|
||||
wf.workflow.list_capabilities
|
||||
wf.workflow.call_capability
|
||||
wf.workflow.run_deployment
|
||||
```
|
||||
|
||||
Use those stable control-plane tools instead of depending on a brand-new dynamic
|
||||
MCP tool becoming callable immediately.
|
||||
|
||||
## A Config Change Says `requires_reload`
|
||||
|
||||
Connection config mutation tools stage file-backed changes. They do not
|
||||
immediately remount the live proxy/provider set.
|
||||
|
||||
If a response says:
|
||||
|
||||
```text
|
||||
requires_reload: true
|
||||
```
|
||||
|
||||
then the next action is the server reload path, not repeated rediscovery against
|
||||
the old mounted set.
|
||||
|
||||
After reload, inspect:
|
||||
|
||||
```text
|
||||
wf.admin.list_connections
|
||||
wf.admin.list_sources
|
||||
```
|
||||
|
||||
## `validate_deployment` Says `binding_missing`
|
||||
|
||||
Meaning:
|
||||
|
||||
```text
|
||||
the artifact requires a logical source alias, but the deployment does not bind it
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
artifact requires: demo.echo_tool
|
||||
deployment bindings: {}
|
||||
```
|
||||
|
||||
Fix:
|
||||
|
||||
- add a binding such as `"demo": "demo.personal"`
|
||||
- then validate again
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
wf.workflow.inspect_artifact
|
||||
wf.workflow.save_deployment
|
||||
wf.workflow.validate_deployment
|
||||
```
|
||||
|
||||
## `validate_deployment` Says `source_missing`
|
||||
|
||||
Meaning:
|
||||
|
||||
```text
|
||||
the deployment binds a logical source to a concrete source id that is not
|
||||
available now
|
||||
```
|
||||
|
||||
Likely causes:
|
||||
|
||||
- the connection was removed
|
||||
- the deployment points at the wrong account id
|
||||
- this environment never had that source configured
|
||||
|
||||
Fix:
|
||||
|
||||
- reconnect/register the source
|
||||
- or rebind the deployment to another compatible source
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
wf.admin.list_sources
|
||||
wf.workflow.inspect_artifact
|
||||
wf.workflow.save_deployment
|
||||
```
|
||||
|
||||
## `validate_deployment` Says `source_disabled`
|
||||
|
||||
Meaning:
|
||||
|
||||
```text
|
||||
the bound source exists, but it is not enabled
|
||||
```
|
||||
|
||||
Fix:
|
||||
|
||||
- enable the source/connection when that is the correct operational choice
|
||||
- or bind to another compatible enabled source
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
wf.admin.inspect_source
|
||||
wf.admin.enable_connection
|
||||
wf.workflow.validate_deployment
|
||||
```
|
||||
|
||||
## `validate_deployment` Says `capability_missing`
|
||||
|
||||
Meaning:
|
||||
|
||||
```text
|
||||
the concrete source exists, but it no longer exposes the required capability
|
||||
```
|
||||
|
||||
Likely causes:
|
||||
|
||||
- upstream server changed
|
||||
- catalog is stale
|
||||
- deployment is bound to the wrong account/source
|
||||
|
||||
Fix path:
|
||||
|
||||
1. refresh the source catalog
|
||||
2. inspect the source inventory
|
||||
3. if the capability is genuinely gone, rebind or migrate the artifact
|
||||
|
||||
Use:
|
||||
|
||||
```text
|
||||
wf.admin.refresh_connection_catalog
|
||||
wf.admin.inspect_source
|
||||
wf.workflow.inspect_artifact
|
||||
wf.workflow.validate_deployment
|
||||
```
|
||||
|
||||
## `validate_deployment` Says `schema_changed`
|
||||
|
||||
Meaning:
|
||||
|
||||
```text
|
||||
the capability still exists, but its current schema hashes differ from the saved
|
||||
artifact contract snapshot
|
||||
```
|
||||
|
||||
The artifact is immutable. The environment changed around it.
|
||||
|
||||
Inspect:
|
||||
|
||||
```text
|
||||
wf.workflow.inspect_artifact
|
||||
wf.workflow.inspect_capability
|
||||
wf.workflow.validate_deployment
|
||||
```
|
||||
|
||||
Then decide:
|
||||
|
||||
- migrate/create a new artifact version
|
||||
- rebind to a compatible source
|
||||
- or adjust deployment drift policy when the change is known acceptable
|
||||
|
||||
Current drift policies:
|
||||
|
||||
| Policy | Behavior |
|
||||
| --- | --- |
|
||||
| `block` | treat drift as an error |
|
||||
| `warn` | return a warning diagnostic |
|
||||
| `allow` | suppress schema-drift diagnostics |
|
||||
|
||||
Prefer `block` unless a human has actually reviewed the changed contract.
|
||||
|
||||
## `run_deployment` Returns `unrunnable`
|
||||
|
||||
`run_deployment` validates dependencies before execution. If blocking
|
||||
diagnostics exist, it returns an unrunnable result instead of trying to execute a
|
||||
broken graph.
|
||||
|
||||
Inspect the returned diagnostics first. Then use the matching section above:
|
||||
|
||||
- `binding_missing`
|
||||
- `source_missing`
|
||||
- `source_disabled`
|
||||
- `capability_missing`
|
||||
- `schema_changed`
|
||||
|
||||
Do not debug runtime behavior before dependency validation is clean.
|
||||
|
||||
## `run_deployment` Refuses An Interrupting Artifact
|
||||
|
||||
Interrupting saved artifacts are not fully supported through the current saved
|
||||
artifact execution path yet.
|
||||
|
||||
Expected diagnostic:
|
||||
|
||||
```text
|
||||
interrupting_artifact_unsupported
|
||||
```
|
||||
|
||||
That is a known platform limitation, not a missing deployment binding.
|
||||
|
||||
## A Raw MCP Tool Works But The Workflow Version Is Awkward
|
||||
|
||||
This is often not a bug.
|
||||
|
||||
Raw tools are provider-facing. Workflow nodes are graph-facing. A tool may need a
|
||||
wrapper when it:
|
||||
|
||||
- encodes status inside output fields
|
||||
- uses provider-specific envelopes
|
||||
- has human-oriented inputs rather than stable graph-oriented inputs
|
||||
- needs explicit workflow outcomes where the transport only exposes generic
|
||||
success/error behavior
|
||||
|
||||
See [`workflow_capabilities.md`](workflow_capabilities.md).
|
||||
|
||||
## MCP Resources Or Prompts Are Missing
|
||||
|
||||
First ask whether the upstream server actually supports them.
|
||||
|
||||
Check:
|
||||
|
||||
```text
|
||||
wf.admin.inspect_source
|
||||
```
|
||||
|
||||
If the source has tools but no prompts/resources, that may be completely valid.
|
||||
MCP servers are not required to implement every capability family.
|
||||
|
||||
## What To Capture In A Bug Report
|
||||
|
||||
For a control-plane discovery bug:
|
||||
|
||||
```text
|
||||
wf.admin.list_connections
|
||||
wf.admin.list_sources
|
||||
wf.admin.inspect_source(<id>)
|
||||
wf.admin.get_connection_statuses
|
||||
```
|
||||
|
||||
For a deployment bug:
|
||||
|
||||
```text
|
||||
wf.workflow.inspect_artifact(<id>, <version>)
|
||||
wf.workflow.list_deployments
|
||||
wf.workflow.validate_deployment(<deployment_id>)
|
||||
```
|
||||
|
||||
For a proxy visibility bug:
|
||||
|
||||
```text
|
||||
whether tools/list changed
|
||||
whether the MCP inspector sees it
|
||||
whether the LLM harness can call it in the same session
|
||||
```
|
||||
|
||||
## Read Next
|
||||
|
||||
- [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md) for the mental model
|
||||
- [`wf_mcp_end_to_end_runbook.md`](wf_mcp_end_to_end_runbook.md) for the happy
|
||||
path
|
||||
- [`workflow_artifacts.md`](workflow_artifacts.md) for dependency diagnostics
|
||||
and drift policy
|
||||
@@ -3,6 +3,9 @@
|
||||
This document captures the current design direction for saved workflows. It is a
|
||||
design note, not an implementation status document.
|
||||
|
||||
For the current operator workflow around artifacts and deployments, see
|
||||
[`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
|
||||
|
||||
## Ownership Boundary
|
||||
|
||||
Saved workflows are not inherently MCP concerns. `wf_mcp` is one capability
|
||||
|
||||
@@ -3,6 +3,9 @@
|
||||
This document separates the things an MCP-facing platform can expose from the
|
||||
things a workflow should usually consume.
|
||||
|
||||
For the short operator/client workflow using these concepts, see
|
||||
[`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
|
||||
|
||||
The short version:
|
||||
|
||||
```text
|
||||
|
||||
Reference in New Issue
Block a user