### HTTP Call Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Demonstrates how to make an HTTP GET request to an external API, including authorization headers.

```yaml
- id: call-api
  type: HttpCall
  inputs:
    url: "https://api.example.com/data"
    method: GET
    headers:
      Authorization: "Bearer {{secrets.API_KEY}}"
```

--------------------------------

### Install Dependencies

Source: https://github.com/qtsone/workflows-mcp/blob/main/benchmarks/README.md

Installs project dependencies and the fastembed library. Run this from the `workflows-mcp` directory.

```bash
uv sync --all-extras
uv pip install fastembed
```

--------------------------------

### Install workflows-mcp with uv

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Install the workflows-mcp package using uv. Requires Python 3.12+.

```bash
uv pip install workflows-mcp
```

--------------------------------

### EditFile Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of using the EditFile executor to replace a version string in a configuration file.

```yaml
- id: update-config
  type: EditFile
  inputs:
    path: "./config.json"
    operations:
      - type: regex_replace
        pattern: '"version": ".*"'
        replacement: '"version": "2.0.0"'
```

--------------------------------

### Visualize Task Tree Example Output

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

An example of the hierarchical output generated by the `agent-state-visualize` workflow, showing task status, execution time, and dependencies.

```bash
PR review [task-c4087afc] ● in-progress (1m6s)
├─ Phase: Context Gathering ✓ 9.8s (platform: github, files: 19)
├─ Phase: Initial Assessment ✓ 22.0s (risk: medium, focus: general)
├─ Phase: Investigation Loop ● 28.5s
│  ├─ Investigate: src/api.py ✓ 4.2s (severity: high)
│  ├─ Investigate: src/auth.py ✓ 5.1s (severity: medium)
│  ├─ Investigate: tests/test_api.py ✓ 3.5s (severity: low)
│  └─ Investigate: README.md ○ pending
├─ Phase: Synthesis ○ pending
└─ Phase: Action ○ pending
```

--------------------------------

### Query Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the `query` operation, demonstrating how to specify scope and query parameters.

```APIDOC
### query

```json
{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory", "compartment": "contract-r2"},
  "query": {"text": "scope precedence", "mode": "search", "radius": 1}
}
```
```

--------------------------------

### SQL Raw Query Example (SQLite)

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of executing a raw SQL query against a SQLite database. Use '?' for positional parameters.

```yaml
# Raw SQL mode - SQLite query
- id: get_users
  type: Sql
  inputs:
    engine: sqlite
    path: "/data/app.db"
    sql: "SELECT * FROM users WHERE status = ?"
    params: ["active"]
```

--------------------------------

### Install workflows-mcp via uvx

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Install the workflows-mcp package using uvx for a persistent environment. Requires Python 3.12+.

```bash
uvx workflows-mcp
```

--------------------------------

### HttpCall Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of using the HttpCall executor to make a POST request to a specified URL.

```yaml
- id: make-api-call
  type: HttpCall
  inputs:
    url: "https://api.example.com/data"
    method: POST
    json: {"key": "value"}
```

--------------------------------

### MergeJSONState Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of using the MergeJSONState block to update a state file.

```yaml
- id: update-state
  type: MergeJSONState
  inputs:
    path: "{{tmp}}/state.json"
    updates:
      last_updated: "{{now()}}"
```

--------------------------------

### Start Project Onboarding

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/memory-postgres.md

Initiate a new project onboarding process when no prior checkpoint exists. This operation ingests initial data and sets up the baseline for future syncs.

```json
{
  "scope": {
    "palace": "acme",
    "wing": "workflows",
    "room": "memory-engine",
    "compartment": "contract-r2"
  },
  "ingest": {
    "format": "raw",
    "content": "Initial baseline",
    "memory_tier": "direct"
  },
  "maintain": {"mode": "community_refresh"},
  "max_operations": 1
}
```

--------------------------------

### Install workflows-mcp using pip

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/quickstart.md

Install the `workflows-mcp` package using pip. This is for users who prefer direct command execution.

```bash
pip install workflows-mcp
```

--------------------------------

### Archive Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the `archive` operation, used to archive records.

```APIDOC
### archive

```json
{
  "operation": "archive",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"], "reason": "No longer relevant"}
}
```
```

--------------------------------

### Ingest Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the `ingest` operation, showing how to provide raw content and specify memory tier.

```APIDOC
### ingest

```json
{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory", "compartment": "contract-r2"},
  "record": {"format": "raw", "content": "Current memory contract enabled", "memory_tier": "direct"}
}
```
```

--------------------------------

### MCP Client Configuration with pip install

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/quickstart.md

Configure your MCP client to use `workflows-mcp` installed via pip. This method uses a direct command execution.

```json
{
  "mcpServers": {
    "workflows": {
      "command": "workflows-mcp",
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/absolute/path/to/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

--------------------------------

### MCP Project Onboarding and Sync

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Use `project_onboard` to start memory initialization and `project_sync` to resume from a checkpoint for large operations. `max_operations` limits operations per call.

```json
// project_onboard — start or continue onboarding (max_operations limits per call)
{
  "scope": {"palace": "myproject", "wing": "backend", "room": "setup", "compartment": "v1"},
  "ingest": {
    "format": "raw",
    "content": "Project baseline: microservices architecture with 8 services.",
    "memory_tier": "direct"
  },
  "supersede": {
    "ids": ["old-record-uuid"],
    "superseded_by": "new-record-uuid"
  },
  "maintain": {"mode": "community_refresh"},
  "max_operations": 2
}
// Returns: {"checkpoint": {...}, "completed": [...], "next_index": 2}

// project_sync — resume from checkpoint
{
  "checkpoint": {
    "version": "oss-r2",
    "scope": {"palace": "myproject", "wing": "backend", "room": "setup", "compartment": "v1"},
    "plan": [
      {"operation": "ingest", "payload": {"format": "raw", "content": "...", "memory_tier": "direct"}},
      {"operation": "maintain", "payload": {"mode": "community_refresh"}}
    ],
    "next_index": 1,
    "completed": ["ingest"]
  },
  "max_operations": 3
}
```

--------------------------------

### Example State Tree Visualization

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Illustrates the hierarchical structure of a completed recursive investigation, showing the progression through phases and the nested investigation of related files.

```bash
PR review [task-fa67c4a3] ✓ done (1m45s) (platform: github, files: 19)
├─ Phase: Context Gathering ✓ 9.8s
├─ Phase: Initial Assessment ✓ 22.0s (risk: medium)
├─ Phase: Investigation Loop ✓ 58.3s
│  ├─ Investigate: src/api.py ✓ 12.5s (severity: high, issues: 3)
│  │  ├─ Investigate: src/auth.py ✓ 4.1s (severity: medium, issues: 1)
│  │  └─ Investigate: src/models.py ✓ 3.2s (severity: low, issues: 0)
│  ├─ Investigate: tests/test_api.py ✓ 8.7s (severity: low, issues: 2)
│  └─ Investigate: README.md ✓ 5.3s (severity: info, issues: 0)
├─ Phase: Synthesis ✓ 11.2s
└─ Phase: Action ✓ 3.7s (approve: false)
```

--------------------------------

### Query Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the 'query' operation, specifying scope and query parameters like text, mode, and radius.

```json
{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory", "compartment": "contract-r2"},
  "query": {"text": "scope precedence", "mode": "search", "radius": 1}
}
```

--------------------------------

### LLMCall Block Example

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Interacts with OpenAI-compatible LLMs, supporting schema validation and retries. Configuration can be profile-based or inline.

```yaml
- id: analyze_code
  type: LLMCall
  inputs:
    profile: default          # loads provider/model/api_key from llm-config.yml
    system_instructions: "You are an expert code reviewer."
    prompt: |
      Review this Python code for bugs and style issues:
      ```python
      {{blocks.read_code.outputs.content}}
      ```
    response_schema:
      type: object
      properties:
        severity:
          type: string
          enum: [critical, high, medium, low, info]
        issues:
          type: array
          items:
            type: object
            properties:
              line: {type: integer}
              description: {type: string}
              fix: {type: string}
      required: [severity, issues]
    max_retries: 3
    temperature: 0.2
    timeout: 90

# Access outputs:
# {{blocks.analyze_code.outputs.response.severity}}
# {{blocks.analyze_code.outputs.response.issues}}
# {{blocks.analyze_code.outputs.success}}
# {{blocks.analyze_code.outputs.metadata.usage}}
```

--------------------------------

### Archive Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the 'archive' operation, specifying record IDs and a reason for archiving.

```json
{
  "operation": "archive",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"], "reason": "No longer relevant"}
}
```

--------------------------------

### LLM Call with Profile

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of using the LLMCall executor with a pre-configured profile for model and settings. The prompt is dynamically generated using input variables.

```yaml
- id: summarize
  type: LLMCall
  inputs:
    profile: default
    prompt: "Summarize this text: {{inputs.text}}"
```

--------------------------------

### ReadFiles with Outline Mode

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Example of using the ReadFiles executor to read Python files from a directory and process them in outline mode.

```yaml
- id: read-sources
  type: ReadFiles
  inputs:
    patterns: ["src/**/*.py"]
    mode: outline
```

--------------------------------

### Supersede Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the 'supersede' operation, including record IDs, the ID of the superseding record, and a reason.

```json
{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"],
    "superseded_by": "22222222-2222-2222-2222-222222222222",
    "reason": "Replaced by corrected incident summary"
  }
}
```

--------------------------------

### Ingest Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the 'ingest' operation, including scope and record details such as format, content, and memory tier.

```json
{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory", "compartment": "contract-r2"},
  "record": {"format": "raw", "content": "Current memory contract enabled", "memory_tier": "direct"}
}
```

--------------------------------

### Shell Block Example

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Executes shell commands, allowing environment variables, working directory, and timeouts. Captures stdout, stderr, and exit code.

```yaml
- id: run_tests
  type: Shell
  inputs:
    command: |
      cd {{inputs.workspace}}
      python -m pytest tests/ -v --tb=short 2>&1
      echo "exit_code=$?"
    working_dir: "{{inputs.workspace}}"
    timeout: 300
    env:
      DATABASE_URL: "{{secrets.DATABASE_URL}}"
      CI: "true"
    capture_output: true

# Access outputs:
# {{blocks.run_tests.outputs.stdout}}
# {{blocks.run_tests.outputs.stderr}}
# {{blocks.run_tests.outputs.exit_code}}
# {{blocks.run_tests.succeeded}}   — true if exit_code == 0
```

--------------------------------

### ReadFiles Block Examples

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Reads files using glob patterns, supporting different modes like 'full' or 'outline'. Can specify line ranges and respect .gitignore.

```yaml
# Single file with line range
- id: read_config
  type: ReadFiles
  inputs:
    path: "{{inputs.workspace}}/config.yaml"
    mode: full
    line_start: 1
    line_end: 50

# Multiple files with glob
- id: read_sources
  type: ReadFiles
  inputs:
    patterns: ["src/**/*.py", "!src/**/*test*.py"]
    base_path: "{{inputs.workspace}}"
    mode: outline        # symbol tree with line ranges
    max_files: 30
    max_file_size_kb: 200
    respect_gitignore: true

# Access outputs:
# {{blocks.read_sources.outputs.files}}              — list of {path, content}
```

--------------------------------

### Visualize Recursive Workflow State

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Example of using a Python function to visualize the state of a recursive workflow after execution.

```bash
# After running recursive workflow
execute_workflow(
    workflow="agent-state-visualize",
    inputs={"state": result["state"]}
)
```

--------------------------------

### Track Phase Start

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Marks the beginning of a phase in a workflow using state management. Essential for tracking progress and debugging.

```yaml
# Phase start
- id: track_phase_start
  type: Workflow
  inputs:
    workflow: agent-state-management
    inputs:
      state: "{{ inputs.state }}"
      parent_id: "{{ inputs.parent_task_id }}"
      task: "Phase: {{ inputs.phase_name }}"
      status: "in-progress"
      caller: "my-workflow:{{ inputs.phase_name }}"
```

--------------------------------

### Workflow YAML Structure Example

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Defines a complete workflow with inputs, blocks, and outputs. Uses Jinja2 for variable interpolation and 'depends_on' for DAG definition.

```yaml
version: "1"
name: data-pipeline
description: Fetch, transform, and store data
tags: [etl, data]

inputs:
  source_url:
    type: string
    required: true
    description: "API endpoint to fetch data from"
  output_path:
    type: string
    default: "/tmp/output.json"

blocks:
  - id: fetch_data
    type: HttpCall
    inputs:
      url: "{{inputs.source_url}}"
      method: GET
      headers:
        Authorization: "Bearer {{secrets.API_KEY}}"

  - id: transform
    type: LLMCall
    depends_on: [fetch_data]
    inputs:
      profile: default
      prompt: |
        Transform this JSON into a summary:
        {{blocks.fetch_data.outputs.response_body}}
      response_schema:
        type: object
        properties:
          summary: {type: string}
          item_count: {type: integer}
        required: [summary, item_count]

  - id: save_result
    type: CreateFile
    depends_on: [transform]
    inputs:
      path: "{{inputs.output_path}}"
      content: "{{blocks.transform.outputs.response | tojson}}"

outputs:
  summary:
    type: str
    value: "{{blocks.transform.outputs.response.summary}}"
  item_count:
    type: num
    value: "{{blocks.transform.outputs.response.item_count}}"
  file_path:
    type: str
    value: "{{blocks.save_result.outputs.path}}"
```

--------------------------------

### Future Custom Secret Provider Configuration

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/secrets-management.md

This example shows a future configuration for integrating with HashiCorp Vault as a custom secret provider. Note that this functionality is not yet implemented and will raise a `NotImplementedError`.

```python
from workflows_mcp.engine.secrets import VaultSecretProvider

# Not yet implemented - will raise NotImplementedError
provider = VaultSecretProvider(
    url="https://vault.example.com:8200",
    token="s.xxxxxxxxxxxxxxxxxxxxxxxx",
    mount_point="secret"
)

# Future: Fetch secrets from Vault
secret_value = await provider.get_secret("database/password")
```

--------------------------------

### Execute async workflow and track status

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Example of executing a workflow asynchronously and then tracking its status. Use get_job_status to poll for completion and resume_workflow if the job is paused.

```text
execute_workflow(workflow="python-ci-pipeline", inputs={...}, mode="async")
→ returns job_id
→ get_job_status(job_id="job_...") until completed/failed/paused
→ if paused, resume_workflow(job_id="job_...", response="...")
```

--------------------------------

### Example Audit Entries

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

These JSON objects represent the logical structure of typical audit entries, illustrating task creation and completion events.

```json
[
  {
    "timestamp": "2025-12-12T10:30:00.123Z",
    "task_id": "task-abc123",
    "caller": "pr-review",
    "action": "create_root",
    "description": "Created root task: PR Review"
  },
  {
    "timestamp": "2025-12-12T10:30:01.234Z",
    "task_id": "task-def456",
    "parent_id": "task-abc123",
    "caller": "pr-review:context-gathering",
    "action": "create_subtask",
    "description": "Created sub-task: Phase: Context Gathering"
  },
  {
    "timestamp": "2025-12-12T10:30:11.234Z",
    "task_id": "task-def456",
    "caller": "pr-review:context-gathering",
    "action": "task_completed",
    "description": "Updated: ['status']",
    "changes": {"status": ["in-progress", "done"]}
  }
]
```

--------------------------------

### Example Task Data Structure

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

This JSON object illustrates the logical structure of task data stored within the state management system. It includes fields for task identification, status, parent-child relationships, and custom data.

```json
{
  "task_id": "task-abc123",
  "task": "PR Review",
  "task_type": "pr-review",
  "status": "in-progress",
  "parent_id": null,
  "data": {
    "platform": "github",
    "files_changed": 19
  },
  "created_at": "2025-12-12T10:30:00.123Z",
  "updated_at": "2025-12-12T10:35:45.456Z"
}
```

--------------------------------

### Configure Secrets in Claude Desktop Configuration

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/secrets-management.md

Example of how to define secrets within the Claude Desktop configuration file using a JSON format. Secrets are mapped to environment variables prefixed with 'WORKFLOW_SECRET_'.

```json
{
  "env": {
    "WORKFLOW_SECRET_API_KEY": "actual_api_key_value"
  }
}
```

--------------------------------

### Configure MCP client with pip command

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Add workflows-mcp to your MCP client configuration when installed with pip. Ensure WORKFLOWS_TEMPLATE_PATHS is set to your workflow definitions directory and WORKFLOW_SECRET_API_KEY is configured.

```json
{
  "mcpServers": {
    "workflows": {
      "command": "workflows-mcp",
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/path/to/your/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO",
        "WORKFLOW_SECRET_API_KEY": "your-secret-value"
      }
    }
  }
}
```

--------------------------------

### Query Workflow State with SQLite

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Interact with the SQLite database storing workflow state to query task information, status, and relationships. Examples include listing all tasks, retrieving specific task details, and checking child task statuses.

```bash
# Open database
sqlite3 ~/.workflows/tasks/exec-abc123.db

# List all tasks
SELECT task_id, status, task FROM tasks;

# Get task details
SELECT * FROM tasks WHERE task_id = 'task-abc123';

# Check children status
SELECT task_id, status FROM tasks WHERE parent_id = 'task-abc123';

# Task tree with hierarchy
SELECT t.task_id, t.status, t.task, p.task_id as parent
FROM tasks t
LEFT JOIN tasks p ON t.parent_id = p.task_id;
```

--------------------------------

### Validate Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the 'validate' operation, specifying the record IDs to be validated.

```json
{
  "operation": "validate",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"]}
}
```

--------------------------------

### Project Onboard Configuration

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Use this configuration to onboard a new project into the memory engine. It specifies scope, ingest details, and supersede/archive information.

```json
{
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "ingest": {"format": "raw", "content": "Initial baseline", "memory_tier": "direct"},
  "supersede": {"ids": ["11111111-1111-1111-1111-111111111111"], "superseded_by": "22222222-2222-2222-2222-222222222222"},
  "archive": {"ids": ["33333333-3333-3333-3333-333333333333"]},
  "maintain": {"mode": "community_refresh"},
  "max_operations": 1
}
```

--------------------------------

### Execute and Resume Workflow

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Demonstrates how to execute a workflow and then resume it later using the state from the previous execution.

```python
result1 = execute_workflow(workflow="my-workflow", inputs={"items": [...], "state": ""})

# Resume later with same state
result2 = execute_workflow(workflow="my-workflow", inputs={"items": [...], "state": result1["state"]})
```

--------------------------------

### Supersede Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the `supersede` operation, used to mark a record as superseded by another.

```APIDOC
### supersede

```json
{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"],
    "superseded_by": "22222222-2222-2222-2222-222222222222",
    "reason": "Replaced by corrected incident summary"
  }
}
```
```

--------------------------------

### Validate Operation Example

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example payload for the `validate` operation, used to validate existing records by their IDs.

```APIDOC
### validate

```json
{
  "operation": "validate",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"]}
}
```
```

--------------------------------

### Claude Desktop Configuration with .env File

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/secrets-management.md

Configure Claude Desktop to load secrets from a specified .env file using the `--env-file` argument.

```json
{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": [
        "--env-file",
        "/path/to/your/project/.env",
        "workflows-mcp"
      ]
    }
  }
}
```

--------------------------------

### Get Queue Statistics

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Get metrics about job queue health, capacity, and throughput. Use for monitoring.

```python
stats = get_queue_stats()
# Returns:
# {
#   "job_queue": {
#     "total_jobs": 150, "queued": 2, "running": 3,
#     "completed": 140, "failed": 5, "cancelled": 0,
#     "workers": 3, "max_concurrent": 500
#   },
#   "io_queue": {"pending": 0, "processed": 890}
# }
```

--------------------------------

### Resume Project Sync with Checkpoint

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/memory-postgres.md

Resume an existing project synchronization using a checkpoint. This is used when a checkpoint from a previous `project_onboard` or `project_sync` call is available.

```json
{
  "checkpoint": {
    "version": "oss-r2",
    "scope": {
      "palace": "acme",
      "wing": "workflows",
      "room": "memory-engine",
      "compartment": "contract-r2"
    },
    "plan": [
      {
        "operation": "ingest",
        "payload": {
          "format": "raw",
          "content": "Initial baseline",
          "memory_tier": "direct"
        }
      }
    ],
    "next_index": 0,
    "completed": []
  },
  "max_operations": 3
}
```

--------------------------------

### Project Sync Configuration

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Configure project synchronization with a checkpoint mechanism. This ensures data consistency by tracking completed operations and version information.

```json
{
  "checkpoint": {
    "version": "oss-r2",
    "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
    "plan": [{"operation": "ingest", "payload": {"format": "raw", "content": "Initial baseline", "memory_tier": "direct"}}],
    "next_index": 0,
    "completed": []
  },
  "max_operations": 3
}
```

--------------------------------

### MCP Client Configuration with uvx

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/quickstart.md

Configure your MCP client to use `uvx` for running workflows. This method does not require a persistent environment.

```json
{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/absolute/path/to/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

--------------------------------

### Fetch Benchmark Datasets

Source: https://github.com/qtsone/workflows-mcp/blob/main/benchmarks/README.md

Downloads public benchmark datasets to the specified output directory. Expected output files include `longmemeval_s_cleaned.json` and `locomo10.json`.

```bash
uv run python benchmarks/fetch_benchmark_datasets.py --output-dir benchmarks/data
```

--------------------------------

### Get queue statistics

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Call the get_queue_stats tool to monitor the health and capacity of the job queue.

```python
get_queue_stats()
```

--------------------------------

### Run Quality Checks

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Execute these commands to run quality checks on the project code. This includes testing, linting, and type checking.

```bash
uv run pytest

```

```bash
uv run ruff check src/workflows_mcp/

```

```bash
uv run mypy src/workflows_mcp/

```

--------------------------------

### List registered workflows

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Call the list_workflows tool to get a list of all registered workflows. The format can be specified as JSON.

```python
list_workflows(tags=[], format="json")
```

--------------------------------

### Share State Between Workflows

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Example of passing state from one workflow to another, enabling sequential execution and state persistence.

```yaml
- id: workflow1
  type: Workflow
  inputs:
    workflow: first-workflow
    inputs:
      state: ""

- id: workflow2
  type: Workflow
  depends_on: [workflow1]
  inputs:
    workflow: second-workflow
    inputs:
      state: "{{ blocks.workflow1.outputs.state }}"
```

--------------------------------

### Initialize State Management

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Good practice for recursive workflows: initializes state tracking using an agent-state-management workflow. This provides visibility into progress.

```yaml
- id: init_state
  type: Workflow
  condition: "{{ inputs.state == '' }}"
  inputs:
    workflow: agent-state-management
    inputs:
      task: "{{ inputs.task_name }}"
      caller: "my-workflow"
```

--------------------------------

### Invalid payload: legacy key 'hall'

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example of an invalid payload due to the use of the legacy 'hall' key in the scope.

```json
{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "svc", "room": "comp", "hall": "legacy"},
  "query": {"text": "incident", "mode": "search"}
}
```

--------------------------------

### Configure PostgreSQL Memory Environment Variables

Source: https://github.com/qtsone/workflows-mcp/blob/main/skills/workflows-mcp/docs/memory-postgres.md

Set these environment variables for the MCP server to connect to and utilize a PostgreSQL database for memory persistence. Ensure PostgreSQL is running and accessible.

```json
{
  "MEMORY_DB_HOST": "localhost",
  "MEMORY_DB_PORT": "5432",
  "MEMORY_DB_NAME": "memory_db",
  "MEMORY_DB_USER": "postgres",
  "MEMORY_DB_PASSWORD": "your-password",
  "MEMORY_DB_AUTO_CREATE": "true",
  "MEMORY_DB_ADMIN_DATABASE": "postgres"
}
```

--------------------------------

### Prompt User for Input

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Pauses the workflow to get input from the user via an LLM prompt. The response is captured as a string.

```yaml
- id: ask-user
  type: Prompt
  inputs:
    prompt: "Do you approve this change? (yes/no)"
```

--------------------------------

### Configure MCP Client for Memory

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Add these variables to your MCP client configuration to enable memory features. Ensure correct database credentials and host information are provided.

```json
{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "MEMORY_DB_HOST": "localhost",
        "MEMORY_DB_PORT": "5432",
        "MEMORY_DB_NAME": "memory_db",
        "MEMORY_DB_USER": "postgres",
        "MEMORY_DB_PASSWORD": "your-password"
      }
    }
  }
}
```

--------------------------------

### Get status of an asynchronous job

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Call the get_job_status tool to poll the status of a specific asynchronous job using its job ID.

```python
get_job_status(job_id="job_...")
```

--------------------------------

### Run Multi-Service Memory Workload Benchmark

Source: https://github.com/qtsone/workflows-mcp/blob/main/benchmarks/README.md

Executes a benchmark simulating multi-service memory workloads with configurable parameters for topology, operations, and traffic mix. The script prints a JSON summary and can optionally persist it with `--output`.

```bash
uv run python benchmarks/workflows_memory_multiservice_bench.py \
  --wings 8 \
  --rooms-per-wing 8 \
  --halls-per-room 4 \
  --records-per-hall 3 \
  --operations 300 \
  --ingest-ratio 0.20 \
  --scoped-query-ratio 0.55 \
  --context-query-ratio 0.25
```

--------------------------------

### Get workflow schema

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Call the get_workflow_schema tool to retrieve the full JSON schema for authoring workflows. This is primarily for debugging purposes.

```python
get_workflow_schema()
```

--------------------------------

### Multi-Service Deployment with Credentials

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/secrets-management.md

Deploy an application to Docker and Kubernetes, and notify Slack using different sets of secrets for each service. Includes Docker login, Kubernetes configuration, and Slack webhook URL.

```yaml
name: multi-service-deployment
description: Deploy app to Docker, Kubernetes, and notify Slack

inputs:
  app_version:
    type: str
    required: true

blocks:
  # Build and push Docker image
  - id: docker_build_push
    type: Shell
    inputs:
      command: |
        docker build -t myapp:{{inputs.app_version}} .
        echo "{{secrets.DOCKER_PASSWORD}}" | docker login -u {{secrets.DOCKER_USERNAME}} --password-stdin
        docker push myapp:{{inputs.app_version}}

  # Deploy to Kubernetes
  - id: k8s_deploy
    type: Shell
    inputs:
      command: |
        kubectl set image deployment/myapp myapp=myapp:{{inputs.app_version}}
        kubectl rollout status deployment/myapp
      env:
        KUBECONFIG: "{{secrets.KUBECONFIG_PATH}}"
    depends_on: [docker_build_push]

  # Notify team on Slack
  - id: slack_notification
    type: HttpCall
    inputs:
      url: "{{secrets.SLACK_WEBHOOK_URL}}"
      method: "POST"
      headers:
        Content-Type: "application/json"
      json:
        text: "Deployed myapp:{{inputs.app_version}} to production"
        blocks:
          - type: "section"
            text:
              type: "mrkdwn"
              text: "*Deployment Status*: Success"
    condition: "{{blocks.k8s_deploy.succeeded}}"
    depends_on: [k8s_deploy]

outputs:
  deployment_succeeded:
    type: bool
    value: "{{blocks.k8s_deploy.succeeded}}"
  notification_sent:
    type: bool
    value: "{{blocks.slack_notification.succeeded}}"
```

```json
{
  "env": {
    "WORKFLOW_SECRET_DOCKER_USERNAME": "myuser",
    "WORKFLOW_SECRET_DOCKER_PASSWORD": "docker_password_here",
    "WORKFLOW_SECRET_KUBECONFIG_PATH": "/home/user/.kube/config",
    "WORKFLOW_SECRET_SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
  }
}
```

--------------------------------

### Get workflow information

Source: https://github.com/qtsone/workflows-mcp/blob/main/README.md

Call the get_workflow_info tool to retrieve details about a specific workflow, including its inputs and outputs. The format can be specified as JSON.

```python
get_workflow_info(workflow="name", format="json")
```

--------------------------------

### Create File with Content

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/llm/block-reference.md

Create a new file or overwrite an existing one with specified content. Supports custom encoding, file permissions, and parent directory creation. Useful for generating output files or configuration.

```yaml
- id: write-output
  type: CreateFile
  inputs:
    path: "{{tmp}}/output.txt"
    content: "{{blocks.previous.outputs.result}}"
```

--------------------------------

### Execute Workflow for Visualization

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/recursive-workflows.md

Use the `execute_workflow` function to run the `agent-state-visualize` workflow. This requires specifying the workflow name and its inputs, including the state file path and visualization options.

```python
# Execute visualization
result = await execute_workflow(
    workflow="agent-state-visualize",
    inputs={
        "state": "/Users/user/.workflows/tasks/exec-abc123.db",
        "show_data": True,
        "max_depth": 0  # 0 = unlimited
    }
)

print(result["tree"])
```

--------------------------------

### Configure workflows-mcp with uvx

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Configure the MCP server for workflows-mcp using uvx, specifying template paths and environment variables for secrets and logging.

```json
// claude_desktop_config.json — uvx variant
{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/absolute/path/to/your/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO",
        "WORKFLOW_SECRET_GITHUB_TOKEN": "ghp_xxxx",
        "WORKFLOW_SECRET_OPENAI_API_KEY": "sk-proj-xxxx",
        "WORKFLOWS_JOB_QUEUE_WORKERS": "3",
        "WORKFLOWS_MAX_RECURSION_DEPTH": "50"
      }
    }
  }
}
```

--------------------------------

### Execute a workflow with debug trace

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Execute a workflow and enable debug tracing by setting `debug=True`. The trace will be written to `/tmp/`.

```python
# With debug trace written to /tmp/
result = execute_workflow(
    workflow="deploy-app",
    inputs={"version": "2.1.0"},
    mode="sync",
    debug=True
)
```

--------------------------------

### Invalid payload: ingest with non-direct tier

Source: https://github.com/qtsone/workflows-mcp/blob/main/docs/guides/memory-tools-cheatsheet.md

Example of an invalid ingest operation using a 'derived' memory tier instead of the required 'direct' tier.

```json
{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "svc", "room": "comp", "compartment": "topic"},
  "record": {"format": "raw", "content": "derived sample", "memory_tier": "derived"}
}
```

--------------------------------

### Get Job Status

Source: https://context7.com/qtsone/workflows-mcp/llms.txt

Poll the status and results of an async workflow job. Poll repeatedly until status is `completed` or `failed`. If `paused`, use `resume_workflow`.

```python
status = get_job_status(job_id="job_a1b2c3d4")
# Returns one of:
# {"status": "queued",    "job_id": "job_a1b2c3d4", ...}
# {"status": "running",   "job_id": "job_a1b2c3d4", "started_at": "..."}
# {"status": "paused",    "job_id": "job_a1b2c3d4", "prompt": "Approve? (yes/no)"}
# {"status": "completed", "job_id": "job_a1b2c3d4", "outputs": {...}}
# {"status": "failed",    "job_id": "job_a1b2c3d4", "error": "..."}
```

--------------------------------

### Run LoCoMo Baseline

Source: https://github.com/qtsone/workflows-mcp/blob/main/benchmarks/README.md

Executes the benchmark for the LoCoMo dataset using default embedding models and session granularity. The `--top-k` parameter specifies the number of top results to retrieve.

```bash
uv run python benchmarks/workflows_locomo_bench.py \
  benchmarks/data/locomo10.json \
  --granularity session \
  --embed-model default \
  --top-k 10 \
  --purge-prefix
```