工作流自动化工具

MCP工作流程

将YAML工作流作为MCP工具运行，以便代理可以在一台服务器上自动化实际任务。

为什么这个项目

workflows-mcp 为MCP客户端提供了一个可重用的自动化层：

• 在YAML中定义一次任务，并从任何兼容MCP的客户端运行它们。
• 通过依赖感知执行来协调多步骤工作。
• 支持交互式跑步(Prompt 块）与暂停/恢复。
• 通过以下方式在服务器端保密 WORKFLOW_SECRET_* 带有编辑后的输出。
• 运行具有队列可见性和取消功能的同步或异步作业。

快速入门（5分钟）

1） 安装

需要Python 3.12以上。

uv pip install workflows-mcp

或者：

pip install workflows-mcp

2） 添加到您的MCP客户端

示例(claude_desktop_config.json):

{
  "mcpServers": {
    "workflows": {
      "command": "uvx",
      "args": ["workflows-mcp"],
      "env": {
        "WORKFLOWS_TEMPLATE_PATHS": "/path/to/your/workflows",
        "WORKFLOWS_LOG_LEVEL": "INFO",
        "WORKFLOW_SECRET_API_KEY": "your-secret-value"
      }
    }
  }
}

如果安装了 pip:

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

3） 重新启动MCP客户端并运行第一个调用

1. list_workflows
2. get_workflow_info
3. execute_workflow

LLM代理人须知

使用此调用顺序可获得可靠的结果：

1. 发现：呼叫 list_workflows.
2. 检查：呼叫 get_workflow_info 对于所需的输入。
3. 执行：呼叫 execute_workflow.
4. 跟踪异步运行 （如果 mode="async")：呼叫 get_job_status （或 list_jobs).
5. 恢复交互式工作流：呼叫 resume_workflow 仅供 paused 工作（通常来自 Prompt 块）。
6. YAML编辑后重新加载定义：呼叫 reload_workflows.

编写工作流时，请先验证：

• validate_workflow_yaml 之前 execute_inline_workflow.
• 使用 get_workflow_schema 有关当前模式的详细信息。
• 使用块引用获取确切的字段名称和所需的输入： docs/llm/block-reference.md.

异步小流示例：

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="...")

可用的MCP工具（目录+调用模式）

工作流发现和执行

创作和验证

异步、队列和交互式控制

内存（条件）

重要提示： memory 仅当启动时内存数据库设置可用且有效时，该工具才会注册（请参阅 在......下面)

内存合约强调：

• 统一信封： operation +可选 scope/query/record/graph/maintenance/response.
• 当前内存分类： scope 仅接受 palace, wing, room, compartment.
• 上下文激活和范围默认：
  • 分辨率优先级为 scope → scope_token → context_id （每个字段合并）。
  • scope_token 从执行上下文解析 memory_scope_tokens; context_id 决议从 memory_context_scopes.
  • 回应包括 resolved_scope 和 scope_source 如果可用。
  • 按操作要求的范围：
    • query：所有四个字段都必须解析。
    • ingest：所有四个字段都必须解析（包括 compartment).
    • graph_upsert 随着 graph.kind="place"：所有四个字段都必须解析。
    • validate|supersede|archive|maintain|graph_delete|graph_upsert(kind="link")：范围是可选的。
• 时态查询语义：
  • operation="query" 支持以下任一选项 query.as_of OR间隔 query.from/query.to （相互排斥）。
  • query.mode="graph" 支持 query.as_of 只有； query.from/query.to 被拒绝。
  • operation="ingest" 随着 record.format="raw" 支持 record.valid_from 和 record.valid_to 通过订购验证(valid_from <= valid_to).
• 严格验证：拒绝未知/额外字段。
• 直接边界与衍生边界：
  • operation="ingest" 只是直接的(record.memory_tier 必须 direct).
  • 摄取的类别治理是明确的：
    • 未知 record.categories 决定性地失败 MEM_UNKNOWN_CATEGORY 当 record.allow_create_categories=false （默认行为）。
    • 设置 record.allow_create_categories=true 选择创建类别，并允许在类别有效时继续摄取。
  • 衍生/社区工件由维护流程产生（例如 maintenance.mode="community_refresh").
  • query.mode="communities" 使用专用社区战略。
• 生命周期语义：
  • 默认查询行为排除已存档的记录。
  • operation="supersede" 需要 record.superseded_by.
  • operation="archive" 地图忘记语义；对已存档的记录重复存档是安全的/幂等的。
• 图形语义：
  • operation="graph_upsert" 随着 graph.kind="link" 是幂等的。
  • operation="graph_delete" 返回紧凑型删除计数器(deleted_places 为了 kind="place", deleted_links 为了 kind="link")；可选的调试输出添加诊断元数据。

验证说明：此摄入类别行为(MEM_UNKNOWN_CATEGORY 禁用create，成功摄取 allow_create_categories=true)2026年4月21日，通过直接MCP等生产方式进行了现场验证 memory 电话。

直接调用JSON示例：

query:

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {"mode": "search", "text": "schema epoch", "as_of": "2026-04-20T00:00:00Z", "radius": 1}
}

ingest:

{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "record": {"format": "raw", "content": "Memory active", "memory_tier": "direct"}
}

validate:

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

supersede:

{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"],
    "superseded_by": "22222222-2222-2222-2222-222222222222"
  }
}

archive:

{
  "operation": "archive",
  "record": {"ids": ["11111111-1111-1111-1111-111111111111"]}
}

maintain:

{
  "operation": "maintain",
  "maintenance": {"mode": "community_refresh"}
}

graph_upsert (kind=place):

{
  "operation": "graph_upsert",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "graph": {"kind": "place", "place_name": "Memory API (current)", "place_type": "feature"}
}

graph_upsert (kind=link):

{
  "operation": "graph_upsert",
  "graph": {
    "kind": "link",
    "from": "11111111-1111-1111-1111-111111111111",
    "to": "22222222-2222-2222-2222-222222222222",
    "link_type": "depends_on"
  }
}

graph_delete:

{
  "operation": "graph_delete",
  "graph": {"kind": "place", "ids": ["33333333-3333-3333-3333-333333333333"]}
}

project_onboard:

{
  "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
}

project_sync:

{
  "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
}

无效（互斥时间筛选器）：

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {
    "mode": "search",
    "text": "maintenance",
    "as_of": "2026-04-20T00:00:00Z",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-20T00:00:00Z"
  }
}

无效（图形查询拒绝间隔筛选器）：

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "workflows", "room": "memory-engine", "compartment": "contract-r2"},
  "query": {
    "mode": "graph",
    "text": "service graph",
    "from": "2026-04-01T00:00:00Z",
    "to": "2026-04-20T00:00:00Z"
  }
}

无效（旧分类键）：

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "svc", "room": "component", "hall": "legacy"},
  "query": {"text": "find this", "mode": "search"}
}

无效（替换缺失的必填项 superseded_by):

{
  "operation": "supersede",
  "record": {
    "ids": ["11111111-1111-1111-1111-111111111111"]
  }
}

配置

工作流加载和执行

• WORKFLOWS_TEMPLATE_PATHS：要加载的逗号分隔的工作流目录。
• WORKFLOWS_MAX_RECURSION_DEPTH：最大工作流组合深度（默认值： 50).
• WORKFLOWS_LOG_LEVEL：日志记录级别(DEBUG, INFO, WARNING, ERROR, CRITICAL；默认值： INFO).

队列和异步设置

• WORKFLOWS_IO_QUEUE_ENABLED：启用序列化I/O队列（默认值： true).
• WORKFLOWS_JOB_QUEUE_ENABLED：启用异步作业队列（默认值： true).
• WORKFLOWS_JOB_QUEUE_WORKERS：队列工作者（默认值： 3).
• WORKFLOWS_MAX_CONCURRENT_JOBS：最大活动+排队作业数（默认值： 500).
• WORKFLOWS_JOB_TIMEOUT：默认异步超时（秒）（默认值： 3600).
• WORKFLOWS_JOB_HISTORY_MAX：最大保留作业记录数（默认值： 1000).
• WORKFLOWS_JOB_HISTORY_TTL：作业保留TTL（秒）（默认值： 86400).

秘密和LLM配置

• WORKFLOW_SECRET_<NAME>：秘密值暴露为 {{secrets.NAME}}.
• WORKFLOWS_LLM_CONFIG：LLM配置的可选路径覆盖。

记忆

内存是一种可选的持久存储功能，允许代理和工作流跨会话记录、检索和组织信息。它由PostgreSQL支持，为每个代理提供了一个结构化、有范围和时间感知的知识库。

记忆提供了什么

• memory MCP工具 --LLM代理的直接调用接口，用于存储和查询信息，而无需编写工作流YAML。
• project_onboard / project_sync MCP工具 --用于检查点入职/同步序列的当前内存合约助手。
• Memory 工作流块 --在YAML工作流内部使用，作为更大管道的一部分，自动化内存操作。
• 内存拓扑范围 (palace → wing → room → compartment)--当前内存作用域键是严格键和遗留键（例如 hall)被拒绝。范围可以直接提供和/或从上下文中解析(scope_token, context_id)使用确定性优先级。
• 时间跟踪 --记录携带 valid_from / valid_to 支持时间点和间隔查询的时间戳。
• 知识图谱 --将记忆链接到地点、实体或概念，并查询结果图。
• 生命周期管理 --归档或替换记录，不得删除；默认查询中不包括存档记录。

检索策略

当前内存行为暴露了内部映射到检索策略的查询模式：

每 query 调用仍然需要完全解析的当前内存作用域(palace/wing/room/compartment)从请求和/或上下文源解析。

作用域调用形状（带上下文激活）

作用域字段可以直接传递和/或从解析 scope_token / context_id:

{
  "operation": "query",
  "scope": {"palace": "acme", "wing": "my-service"},
  "scope_token": "st_auth",
  "context_id": "ctx_default",
  "query": {"text": "refresh token lifetime", "mode": "context"}
}

分辨率优先级为 scope → scope_token → context_id 对于每个领域。

先决条件

• PostgreSQL 13或更高版本，可从服务器进程访问网络。
• 数据库用户 CREATE DATABASE 管理员数据库的权限（通常 postgres)如果启用了自动创建， 或 用户可以连接到的预先存在的数据库。

配置

启用内存

将以下变量添加到MCP客户端配置中：

{
  "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"
      }
    }
  }
}

首次开机时 MEMORY_DB_AUTO_CREATE=true （默认），服务器创建目标数据库并自动应用模式。添加变量后重新启动MCP客户端。

验证内存是否处于活动状态

1. 重新启动MCP客户端。
2. 呼叫 list_workflows --确认服务器已启动，客户端日志中没有错误。
3. 检查一下 memory 工具出现在可用工具列表中。
4. 运行测试摄取：

{
  "operation": "ingest",
  "scope": {"palace": "acme", "wing": "test", "room": "setup", "compartment": "smoke"},
  "record": {"format": "raw", "content": "Memory is working.", "memory_tier": "direct"}
}

如果该工具不存在，请检查服务器日志 MEMORY_DB_* 启动错误——最常见的原因是无法访问的主机、不正确的凭据或模式纪元不匹配。

架构兼容性

内存模式版本按纪元跟踪。如果数据库中的纪元与服务器版本不匹配：

• 启动失败，出现显式错误。
• 应用记录的迁移并重新启动。
• 不执行自动破坏性重置。集 MEMORY_SCHEMA_RESET_MODE 只有当您打算对非生产实例进行一次性破坏性重置时。

用户工作流程

使用注册的工作流进行可重复的自动化，使用内联工作流进行实验。

• 已注册工作流：最适合共享、可重用的操作。
• 内联工作流：最适合快速测试和原型制作。

具有精确块输入名称的作者工作流YAML来自：

• docs/llm/block-reference.md

示例块族包括 Shell, ReadFiles, HttpCall, LLMCall, Sql, Workflow, Prompt，以及 Memory.

文档地图

• README.md：安装、用法和工具目录。
• docs/guides/memory-tools-cheatsheet.md：当前内存合约快速参考、详细指南和示例。
• docs/llm/block-reference.md：用于工作流创作的精确块输入/输出。
• docs/TESTING.md：测试策略和测试命令。
• ARCHITECTURE.md：架构概述。
• docs/adr/：设计决策和基本原理。
• CHANGELOG.md：发布历史记录。

贡献

1. 分叉存储库并创建一个焦点分支。
2. 使用您的更改添加或更新测试。
3. 在打开PR之前进行质量检查：

uv run pytest
uv run ruff check src/workflows_mcp/
uv run mypy src/workflows_mcp/

4. 在PR中清楚地描述行为变化和配置影响。

支持和社区

• 问题和错误报告：https://github.com/qtsone/workflows-mcp/issues
• 项目存储库：https://github.com/qtsone/workflows-mcp

许可证

AGPL-3.0或更高版本。看 许可证.