为什么需要 MCP？

传统的 AI + 工作流集成方式通常是"硬编码"：把流程 API 包成 Function Calling，每个 LLM 平台单独适配一套。MCP 的出现改变了这一局面——只需实现一次，所有支持 MCP 的 AI 客户端都能自动发现并调用你的工具。

对于 Slickflow 这样的工作流引擎来说，这意味着：

• AI Agent 可以自主发起流程、推进审批、查询状态，无需人工干预
• 知识库与流程联动：Agent 可以先查规则，再决定流程走向
• 平台无关：同一个 MCP Server，Dify / Coze / n8n / Claude 均可接入

---

二、整体架构

┌─────────────────────────────────────────────────────┐
│               AI 编排平台                            │
│   Dify · Coze · n8n · Claude · 自定义 Agent        │
└────────────────────┬────────────────────────────────┘
                     │  MCP Protocol (HTTP Streamable / SSE)
                     ▼
┌─────────────────────────────────────────────────────┐
│              Slickflow MCP Server (:5100)            │
│                                                     │
│  ┌─────────────────────┐  ┌──────────────────────┐  │
│  │   WorkflowTools     │  │  KnowledgeBaseTools  │  │
│  │   (12 个工具)       │  │  (2 个工具)          │  │
│  └──────────┬──────────┘  └──────────┬───────────┘  │
│             │                        │               │
│             ▼                        ▼               │
│   IWorkflowService              KbDocumentService    │
└────────────┬────────────────────────┬───────────────┘
             │                        │
             ▼                        ▼
     Slickflow Engine           向量数据库 (PgVector)
     (PostgreSQL)               text-embedding-v4 / 1536d

Server 基于 ModelContextProtocol.AspNetCore v0.3.0-preview.2，运行在 .NET 8 之上。

---

三、14 个工具详解

3.1 WorkflowTools（12 个）

工具名	功能	典型参数
list_processes	列出所有已发布流程	—
start_process	启动流程实例	processCode, userId, appInstanceId
run_process	推进流程（提交待办）	taskId, userId, approvalStatus
get_process_instance	查询流程实例状态	processInstanceId
get_running_tasks	查询用户待办任务	userId
get_completed_tasks	查询用户已办任务	userId, appInstanceId
get_next_steps	查询下一步节点	taskId, userId
get_process_instances_by_app	按业务单据查流程实例	appInstanceId
get_approval_trace	查审批轨迹（完成顺序）	taskId
withdraw_process	撤回（下一步未办时）	taskId, userId
sendback_process	退回到上一步	taskId, userId
reject_process	驳回到发起人	taskId, userId

3.2 KnowledgeBaseTools（2 个）

工具名	功能	典型参数
search_knowledge_base	语义搜索，返回相关文档片段	query, count=5, threshold=0.7
list_knowledge_documents	列出知识库全部文档摘要	—

---

四、核心实现

4.1 Server 注册（三行代码）

builder.Services.AddMcpServer()
    .WithHttpTransport(options => options.EnableLegacySse = true)
    .WithTools<WorkflowTools>()
    .WithTools<KnowledgeBaseTools>();

// ...
app.MapMcp("/mcp");

EnableLegacySse = true 同时暴露 GET /mcp/sse + POST /mcp/message，兼容 n8n 等尚未实现 Streamable HTTP 的客户端。

4.2 工具声明（Attribute 驱动）

[McpServerToolType]
public class WorkflowTools(IWorkflowService wfService)
{
    [McpServerTool, Description("启动一个流程实例。返回流程实例ID(ProcessInstanceIdStarted)。")]
    public string start_process(
        [Description("流程代码，从 list_processes 获取")] string processCode,
        [Description("发起人用户ID")] string userId,
        // ...
    )
    {
        // 先查流程定义，再创建 WfAppRunner 启动
        var process = wfService.GetProcessByCode(processCode, version);
        var runner = new WfAppRunner { /* ... */ };
        var result = wfService.StartProcess(runner);
        return JsonSerializer.Serialize(new { result.Status, result.ProcessInstanceIdStarted });
    }
}

每个工具方法只是一个普通 C# 方法，[Description] 注解会被框架自动解析为 MCP inputSchema，大模型据此生成正确的参数调用。

4.3 API Key 鉴权

鉴权逻辑通过中间件实现，支持两种 Header 格式：

X-Api-Key: <your-key>
// 或
Authorization: Bearer <your-key>

/health 端点跳过鉴权，供 Docker/K8s 健康探针使用。空 Key 时自动进入开发模式（免鉴权），方便本地调试。

4.4 速率限制

// 每 IP 每分钟最多 100 次请求（可通过配置调整）
RateLimitPartition.GetFixedWindowLimiter(
    ctx.Connection.RemoteIpAddress?.ToString(),
    _ => new FixedWindowRateLimiterOptions { PermitLimit = 100, Window = TimeSpan.FromMinutes(1) }
);

超限返回 HTTP 429，响应头包含 Retry-After。

---

五、与 AI 平台集成

5.1 Dify

在 Dify 工作流中添加"工具"节点，选择 MCP Server，填入：

Transport：Streamable HTTP
URL：http://your-host:5100/mcp
Headers：X-Api-Key: your-api-key

5.2 Coze

Coze 要求额外发送协议版本 Header：

Transport：Streamable HTTP
URL：http://your-host:5100/mcp
Headers：
  X-Api-Key: your-api-key
  MCP-Protocol-Version: 2025-03-26

5.3 n8n

n8n 当前版本（已知 bug）不支持 Streamable HTTP，需走 SSE Transport：

Transport：SSE
SSE URL：http://your-host:5100/mcp/sse
Message URL：http://your-host:5100/mcp/message

Server 端 EnableLegacySse = true 已自动开启此端点。

---

六、内置 MCP Client（Agent 侧）

Slickflow.AI 内置了 McpServerClient，AI Agent 节点可在运行时自动发现并调用 MCP Server 上的所有工具，无需手动注册：

// 自动发现远程 MCP Server 上的全部工具
var client = new McpServerClient("http://your-host:5100");
var tools = await client.DiscoverToolsAsync();

// 注册到 ReAct Agent
AgentToolRegistry.Global.Register("MY_ACTIVITY_ID", tools);

McpClientTool 内部通过 JSON-RPC 2.0 调用远端工具，对 ReAct Agent 来说与本地 Function 完全透明。