lda-wf/docs/source_provider_guide.md

Source Provider Guide

Sources are the boundary where workflows call outside capability providers. The current provider families are:

• mcp: MCP tools/resources/prompts exposed as workflow capabilities.
• python: trusted in-process Python NodeSpec registries.
• built-in sources such as wf.std.

Use wf source diagnose <source_id> before debugging capability calls. It reports transport kind, auth reference, auth record presence, auth scheme compatibility, catalog snapshot counts, and non-secret diagnostics.

MCP HTTP Source

Use HTTP MCP for remote MCP servers:

{
  "kind": "mcp",
  "id": "vendor.default",
  "provider": "vendor",
  "account": "default",
  "transport": {
    "kind": "http",
    "url": "https://example.test/mcp"
  },
  "auth_ref": "vendor.default"
}

Supported HTTP auth schemes:

• bearer
• headers
• oauth_refresh_token

Check it:

wf --config wf.config.json source diagnose vendor.default

MCP Stdio Source

Use stdio MCP for local subprocess servers:

{
  "kind": "mcp",
  "id": "everything.default",
  "provider": "everything",
  "account": "default",
  "transport": {
    "kind": "stdio",
    "command": "uvx",
    "args": ["mcp-server-everything"]
  }
}

For stdio auth, use env auth so secrets become subprocess environment variables. HTTP bearer/OAuth auth is intentionally not applied to stdio transports.

Python Source

Python sources expose trusted in-process NodeSpec registries:

{
  "kind": "python",
  "id": "local.ops",
  "path": ".",
  "module": "my_source.ops",
  "registry": "registry"
}

Package-style modules are preferred. Relative imports inside the configured package are source-local; bare local imports use Python's normal global import cache and can collide if multiple sources reuse names like ops or helpers.

For the full runnable flow, see Python Source Runbook.

Auth Records And auth_ref

Source configs never store secret payloads directly. They point at an auth record:

{
  "auth_ref": "vendor.default"
}

Local/dev auth records are managed with:

wf admin auth save vendor.default --scheme bearer --payload-file auth.json
wf admin auth inspect vendor.default
wf admin auth delete vendor.default --confirm

Auth inspect/list responses show ids, schemes, metadata, and payload keys only. Payload values are write-only.

OAuth Refresh-Token Auth

Use oauth_refresh_token for HTTP providers where the platform can refresh an access token and apply Authorization: Bearer <access_token> to MCP HTTP requests.

Provider profiles live in config under auth.providers:

{
  "auth": {
    "providers": {
      "google": {
        "kind": "oauth_authorization_code_pkce",
        "auth_url": "https://accounts.google.com/o/oauth2/v2/auth",
        "token_url": "https://oauth2.googleapis.com/token",
        "client_id_env": "GOOGLE_OAUTH_CLIENT_ID",
        "client_secret_env": "GOOGLE_OAUTH_CLIENT_SECRET",
        "scopes": ["https://www.googleapis.com/auth/drive.readonly"],
        "extra_authorize_params": {
          "access_type": "offline",
          "prompt": "consent"
        }
      }
    }
  }
}

Login:

wf --config wf.config.json admin auth oauth-login google --id vendor.default

The stored refresh token is sensitive. The local file auth store is plaintext and intended for local/dev use only.

Google Drive MCP Caveat

Google Drive MCP is useful as a real remote MCP provider, but it is not a good regression fixture. In local testing it showed provider-specific permission friction and very low Drive MCP quota compared with the Drive REST API.

Use deterministic local fixtures for auth/runtime regression tests. Treat Google Drive MCP as manual smoke coverage only.

Diagnostic Loop

When a source call fails:

wf source diagnose <source_id>
wf source inspect <source_id>
wf cap list --source <source_id>
wf cap call <source_id>.<capability> --input '{}' --format compact

Use wf --verbose ... only when compact CLI errors are not enough.

Source Resource Refs

Resource refs are inert workflow data:

{
  "kind": "source_resource_ref",
  "logical_source": "drive",
  "uri": "demo://docs/welcome"
}

Input/output/state bindings treat this object as ordinary JSON. Only explicit platform helper nodes such as wf.source.read_resource dereference it. This keeps large MCP resource payloads out of workflow state unless the workflow asks for them.