Activepieces 的 AI 与 MCP 一体化架构：从 MCP 服务器、AI Provider 到 Chat、知识库与 Copilot-酒店常州论坛

Activepieces 的 AI 与 MCP 一体化架构：从 MCP 服务器、AI Provider 到 Chat、知识库与 Copilot

【免费下载链接】activepiecesAI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces

本指南以仓库知识库文档 ai-mcp.md 为骨架，系统讲解 Activepieces 中 AI 与 MCP 各能力面的组织方式与相互关系：项目级 MCP 服务器如何把流程、表格、连接与运行记录暴露给外部 AI 客户端，平台管理员如何配置 LLM 后端并计量用量，平台级 Chat 助手、知识库检索与面向开发者的 Platform Copilot 又是如何在底层共享同一套工具面与模型解析逻辑。读完本文，你将掌握这些功能的实体模型、关键服务与源码位置、版本/部署前提，以及排查常见坑位的切入路径。

说明：文中所有源码路径均以仓库根目录为起点，可直接在仓库中跳转核对；各功能面的更细条目分别收录于 mcp-server.md、ai-providers.md 等姊妹文档。

MCP 服务器：把项目暴露为类型化工具端点

Activepieces 的 MCP 能力面将一个项目暴露为一个 Model Context Protocol 服务器，使 Claude Desktop、Cursor 以及 Agent piece 等 AI 客户端，可以通过类型化工具驱动流程（flows）、表格（tables）、连接（connections）与运行记录（runs）。每个项目对应一个McpServer记录，是"项目即 MCP 端点"的模型。

实体与服务

从实体定义看（mcp-entity.ts），mcp_server表的核心字段为：

projectId：唯一约束（mcp_server_project_id），保证一个项目只有一个 MCP 服务器记录；
token：72 字符的 bearer token，同样带唯一索引idx_mcp_server_token；
disabledTools：JSONB 数组，用于按项目关闭可控工具；
type：区分PROJECT（项目级）与PLATFORM（平台级）两种服务器形态。

服务层（mcp-service.ts）负责"按需构建"：

getByProjectId/getByPlatformId：通过getOrCreate惰性创建记录，save使用apId(72)生成 token，并发插入撞唯一键时回退为读取既有行；
getPopulatedByProjectId：额外加载该项目下所有使用 MCP trigger 的流程（listMcpFlows），形成带flows的完整视图；
rotateToken/rotatePlatformToken：轮换 token（生成新的apId(72)）；
update/updatePlatform：更新disabledTools开关集合；
buildServer：每次请求构建一个 MCP server 实例，交由 mcp-server-builder.ts 实现。

HTTP 端点由 mcp-server-controller.ts 注册：GET /获取项目 MCP 服务器（含流程列表）、POST /更新disabledTools、POST /rotate轮换 token、POST /token签发短期 MCP 访问令牌并返回{ mcpServerUrl, mcpToken }（分别要求READ_MCP/WRITE_MCP权限）。

三类工具：锁定、可控与动态流程工具

构建器将工具划分为三个层级：

锁定工具（locked，只读，始终开启）：list/structure/validate/research 类工具，如ap_list_flows、ap_flow_structure、ap_research_pieces、ap_get_piece_props、ap_list_connections、ap_list_tables、ap_get_run。它们不进入disabledTools管控范围。
可控工具（controllable，可切换的写操作）：创建/构建/发布流程、表格与记录操作、运行管理、测试等写能力，可按项目通过disabledTools逐项关闭。
动态流程工具（dynamic flow-tools）：任何使用了@activepieces/piece-mcptrigger 的流程，都会自动变成一个可调用工具，命名为{toolName}_{flowId[0..4]}（流程 ID 前 5 位），执行时以 webhook 方式触发流程（同步返回或异步）。

mcp-server-builder.ts中内置的MCP_SERVER_INSTRUCTIONS还给出了面向客户端的编排建议：Discover → Schema → Build → Validate → Publish 五步工作流，并特别强调 step 引用须写成{{stepName['output'].field}}（输出嵌套在['output']下）、触发步骤用{{trigger['output'].field}}，修改步骤应使用ap_update_step/ap_update_trigger而不是删除重建（否则丢失 sample data）。这些指令会随服务器元数据一起下发给客户端，是 MCP 工具面可用性的关键一部分。

认证、传输与兼容性要点

认证支持 Bearer token 或?token=查询参数；对需要标准流程的客户端提供OAuth 2.0 PKCE。
主端点为StreamableHTTP（/v1/mcp/:projectId/http）；姊妹文档 mcp-server.md 补充了域名根路径的POST /mcp与平台级POST /mcp/platform两个注册入口。
x-ap-conversation-id请求头允许 EE Chat 将服务器重新绑定到某次对话所属的项目，但作用域以 token 为准，只能收窄、不能扩大访问范围。
未认证请求的401会携带 RFC 9728 的WWW-Authenticate头，供客户端做端点发现。
该能力面在 CE、EE、Cloud所有版本均可用。

AI Providers：LLM 后端配置、加密与用量计量

AI Providers 是平台管理员为 AI pieces 配置 LLM 后端的入口，同时也负责用量计量。当平台开启aiCreditsEnabled时，系统会自动预置一个经由 OpenRouter 驱动的"Activepieces" provider。

实体与服务

AIProvider是平台级（platform-scoped）实体，以(platform, provider)为唯一键；auth字段使用AES-256 加密存储（EncryptedObject），仅在引擎侧解密。核心文档列出 8 个内置 provider：openai、anthropic、google、azure、openrouter、cloudflare-gateway、custom、activepieces；姊妹文档 ai-providers.md 显示清单已扩展至 10 个（新增bedrock、mistral），并支持多 key 下的modelScope/projectScope细粒度路由。各 provider 的认证/配置 schema 定义在 packages/core/shared/src/lib/management/ai-providers/index.ts：多数为{ apiKey }形态，Vertex 使用 service-account JSON，Bedrock 使用accessKeyId+secretAccessKey，OpenAI 兼容的custom额外支持baseUrl、defaultHeaders、apiStyle（chat/responses）等字段。

用量计量与运行时取凭据

积分体系：1000 credits = $1 USD，由 OpenRouter 按 key 计量；主文档描述为月度重置并支持自动充值（自动充值由系统任务触发；姊妹文档进一步说明该充值由 Autumn 计费系统驱动、以 OpenRouter key 的limit_reset作为"月度"机制）。
运行时取凭据：引擎在每次 AI action 执行时调用GET /v1/ai-providers/{provider}/config获取解密后的凭据（以引擎 token 鉴权），而不是缓存复用。
模型列表缓存：模型清单在内存中缓存，每日午夜（cron）清空重建。

兄弟能力：AI Tool Configs

与 AI Providers 同目录但相互独立的是AiToolConfig，它为 Chat 助手提供外部能力：WEB_SEARCH/WEB_SCRAPING/IMAGE_GENERATION分别由 Tavily / Firecrawl / Apify / Fal 的 key 驱动，接口位于/v1/ai-tools，仅 EE/Cloud、仅平台管理员可配置。它的存在使"模型由谁提供"与"助手有哪些外部工具"成为两个正交的配置面。

Chat：平台级 AI 助手与 Worker 执行模型

Chat 是平台级（platform-level）的 AI 助手，通过自然语言管理项目，基于 WebSocket 流式输出，并把项目的 MCP 服务器作为自己的工具面——这正是 AI 与 MCP 两个能力面最直接的耦合点。

执行模型（关键注意点）

Chat 的 LLM 循环运行在 worker 中，而不是 API 进程里：

控制器将任务入队为WorkerJobType.EXECUTE_AGENT_RUN；
worker 侧 execute-agent-run.ts 接手任务；
run-agent-turn.ts 执行streamText()产生流式 chunk；
chunk 通过 RPC 流回 API；
以CHAT_MESSAGE_CHUNK事件推送 WebSocket（按runId过滤，只推给对应会话的客户端）。

agent-conversation-service.ts只负责会话的 CRUD，不参与推理循环。从 execute-agent-run.ts 的常量还可以看到执行边界的细节：单轮硬上限MAX_TURN_WALL_CLOCK_MS = 2h、90s 空闲上报看门狗、15s 心跳保活、审批超时 5 分钟等。

实体与约束

AgentConversation（表agent_conversation）：按 platform+user 维度存储，可带项目作用域，消息为 JSONBModelMessage[]，支持压缩摘要（compaction summary）。
chat_rollout_user：记录云上 beta 队列（上限 200 个曾发送过消息的不同用户），用于灰度放量。

集成注意点

仅 EE/Cloud（需要chatEnabled，或走云上 rollout/grandfather 通道）。
拒绝 PGLite 开发库——必须使用 Postgres + Redis。
工具门控为两阶段（discovery/build）；展示卡片与写操作预览走 Redis pub/sub 审批闸门；MCP 工具已不再经过门控，仅做超时包裹。
连接由服务端托管，LLM 永远看不到凭据的 externalId；Web 搜索复用已配置的 LLM 凭据，无需第二个 BYOK。

Knowledge Base：项目级文档库与向量检索

知识库是项目作用域的文档存储：上传 PDF/DOCX/TXT/CSV → 切分为文本块 → 可选生成 768 维向量 → 供 Agent 做语义检索。

实体与检索

knowledge_base_file+knowledge_base_chunk：chunk 表带vector(768)类型的embedding列，检索使用 cosine 距离运算符<=>，并有 HNSW 索引（idx_kb_chunk_embedding，非 PGlite 环境）加速。
REST 入口为/v1/knowledge-base/files。

pgvector 的自愈式初始化（关键注意点）

vector扩展不通过 migration 创建——直接CREATE EXTENSION会在受管 PostgreSQL（如 RDS）上 crash-loop。取而代之的是自愈 seed：knowledgeBaseSchema.ensure()（见 knowledge-base-schema.ts）在每次启动时运行：先查pg_extension，未安装时查pg_available_extensions，可用则CREATE EXTENSION IF NOT EXISTS "vector"并建表建索引，不可用则静默跳过并记录 warn；之后若运维安装 pgvector，重启即激活 KB。前端以PGVECTOR_AVAILABLEflag 门控该功能入口。

版本范围：所有版本可用；PGLite 内置 pgvector，因此 CE 开箱即用。
分块策略：每块 2000 字符、重叠 200 字符；CSV 文件会在每个 chunk 重复表头。

Platform Copilot：面向开发者的后端 RAG

Platform Copilot 是仅后端的 RAG 对话能力，回答关于 Activepieces 平台本身的问题（代码库 + 文档），面向基于 AP 构建的开发者，而非流程终端用户。

检索与生成

语料实体copilot_code_chunks：同时带vector(768)向量与tsvector全文索引。
混合检索= RRF（Reciprocal Rank Fusion）合并：向量余弦相似度占 70%，Postgres 全文检索占 30%。
read_file与list_directory两个工具在对话时命中代码仓库的 raw 文件/API（对应仓库的 GitHub raw 与 API），实现"按需读取源码"。
生成侧通过 Vercel AI SDK 的 UI message protocol 流式返回，单次对话最多5 个 LLM 步骤。

部署与维护注意点

源码仅以编译后的 JS 形态存在于.../dist/src/app/platform-copilot/，仓库内没有可读的 TS 源。
版本范围：所有版本可用，任意已认证的USER（publicPlatform）即可访问。
索引每周重建（COPILOT_INDEX_REFRESH，默认周日 03:00 UTC），也可通过/index接口手动触发，或启动时发现索引为空自动构建。

各能力面的关系与排查指引

综合 ai-mcp.md 与 index.md 的术语表，五个能力面可概括为一句话：AI Provider 决定"用哪个模型"，AI Credits 决定"用多少额度"，Agent 步骤是"自主循环"，MCP Server 是"对外工具端点"，Chat/Copilot/知识库则是消费它们的应用面。

排查问题时可直接按能力面对号入座：

能力面	主要源码位置	关键前置条件	典型坑位
MCP Server	packages/server/api/src/app/mcp/	所有版本	token 仅用于兼容、认证实为 OAuth；工具开关只影响可控工具
AI Providers	packages/server/api/src/app/ai/	EE/Cloud	`auth`AES-256 加密；引擎每次执行时拉取配置；模型缓存每日午夜刷新
Chat	worker 的 ee/agent/	EE/Cloud + Postgres/Redis	LLM 循环在 worker；拒绝 PGLite
Knowledge Base	packages/server/api/src/app/knowledge-base/	所有版本，需 pgvector	扩展由启动 seed 自愈安装，migration 不负责
Platform Copilot	`dist/src/app/platform-copilot/`（仅编译产物）	所有版本	索引每周重建；最多 5 步 LLM

对计量、多 provider 路由等更深细节，可继续阅读姊妹文档 ai-providers.md 与相关决策记录（如 000016 托管 AI 计量迁移到集中式 worker 执行），它们与本页共同构成 Activepieces AI/MCP 面的完整知识体系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析