activepieces 给自己的定位是开源的 Zapier 替代。它真正的卖点不是又一个工作流平台,而是一套 type-safe 的 pieces 框架:你用 TypeScript 写一个集成,它就能当 MCP server 接给 Claude Desktop、Cursor、Windsurf。这篇记我怎么装的,卡在哪,最后写了什么跑通。
先给判断。要不要学 activepieces,看你要不要"自己写一个集成给 LLM 用"。要,这套框架很顺。只是想搭几条自动化,直接用现成模板就够了。别为这个碰代码。
docker 起不来,就单独装框架
我一开始想按 README 走 docker compose 起整套平台。结果 docker info 直接回了一句 failed to connect to the docker API,本机 daemon 没起。整套平台起不来。这算第一个坑,但它不是框架的问题,是我这台机器没开 Docker。我查了 1 遍,docker 客户端是 29.4.0,daemon 没起来而已。
换条路。pieces 框架本身是个 npm 包,不依赖 Docker,我单独装它。包名 @activepieces/pieces-framework,装出来 0.32.0。这一步就够我验证"写一个 piece"这条链。装包不重,几秒就完。
npm install @activepieces/pieces-framework@0.32.0
框架的核心:createPiece 加 createAction
我先说这个框架的核心思路。一个 piece 对应一个外部服务,一个 action 对应这个服务的一个操作。它用 TypeScript 的类型系统把输入参数、鉴权、输出都约束起来,这就是它自称 type-safe 的地方。
我写了最小 piece 验证。核心是两个 API:createPiece 定义集成,createAction 定义一个操作,操作里一个 run 函数返回结果。
import { createPiece, createAction } from '@activepieces/pieces-framework';
const fetchPrice = createAction({
name: 'fetch_price',
displayName: 'Fetch Price',
description: 'Return a price for demo',
props: {},
async run() {
return { symbol: 'BTC', price: 97251.3, source: 'demo' };
},
});
const demoPiece = createPiece({
displayName: 'Demo Piece',
logoUrl: 'https://example.com/logo.png',
authors: ['小W'],
auth: undefined,
minimumSupportedRelease: '0.20.0',
actions: [fetchPrice],
triggers: [],
});
我在本机跑这段,demoPiece.actions() 列出 fetch_price,action.run({}) 返回 {"symbol":"BTC","price":97251.3,"source":"demo"}。装包、定义、运行三条链都通了。这是真实输出,不是我想象它该输出什么。
type-safe 到底安全在哪
我说它 type-safe,不是嘴上说说。我把框架的类型定义打开核了 1 遍,props 字段是个 InputPropertyMap,每个输入属性要写 type、displayName、required,类型里还有 PropertyType.SHORT_TEXT、LONG_TEXT、MARKDOWN 这一串枚举。鉴权走 PieceAuth,一个 piece 可以声明要 OAuth2 还是 API key。输出还能挂 outputSchema,让平台和 LLM 都知道这个 action 会吐什么结构。
这套类型约束的价值在哪,我给了个判断。它把"一个集成长什么样"从文档里搬进了编译期。你写错一个字段名,tsc 当场报错,不用等到运行时在 builder 里点半天才发现。对要维护几十个集成的团队,这个值很大。
piece 怎么变成 MCP,答案在元数据
接下来是关键问题:piece 怎么变成 MCP server。答案藏在一个字段里。我把框架的类型定义打开核了 1 遍,每个 action 有两个元数据字段,aiMetadata 是 { description, idempotent },audience 是 human、ai、both 三选一。这俩就是 piece 向 LLM 描述自己的方式。你把 audience 设成 ai、aiMetadata.description 写清楚"这个操作干什么",平台就能把它推给 LLM 当工具调。
const action = createAction({
name: 'send_notification',
displayName: 'Send Notification',
description: 'Send a notification to a channel',
props: {},
audience: 'ai',
aiMetadata: { description: 'notify a channel', idempotent: true },
async run() { return {}; },
});
所以 activepieces 说的"280 多个 pieces 全都能当 MCP",本质是每个 piece 已经带上了给 LLM 看的元数据,平台再把它们包装成 MCP 工具暴露出去。你贡献一个 piece,它自动就变成别人能接的 MCP。这是它跟"自己手写一个 MCP server"最大的区别。前者一次写、处处可接,后者每次对接都要重写一遍协议层。
值不值得上
我查了它的量。README 标的 pieces 有 280 多个,60% 是社区贡献的,它自称 largest open source MCP toolkit。注意编排里写的"约 400 个 MCP"跟 README 的 280 多对不上,我以 README 为准。
值不值得用,我给个判断。你要在一个组织里让非技术人员拼自动化、技术人员写 piece,activepieces 这套分工很清晰,值得上。你只是自己接几个工具给 Agent 用,直接写个 MCP server 更轻。别为它拉一整套平台加 Docker。我这次全程在本机 macOS arm64、Node 22.22.2 上跑,只动了 npm,没碰系统配置。
还有个点我想说清楚。这次我没跑通整套平台,只跑了框架这条链。整套平台的编排能力、版本化的 flow、人工审批这些,我没亲测,不下结论。但我单独跑的这段已经够回答核心问题:写一个 piece 到被 LLM 调,中间的关键就是 aiMetadata 和 audience 这两个字段。机制是通的,剩下的平台能力是另一回事。
一句话。activepieces 的可复用点在 pieces 框架:写一次集成,既能进它的无代码 builder,又能当 MCP 接给 LLM。平台起不起来,不影响你单独用框架。