内容
# 工具列表
即用型 **Telegram 机器人模板** 和 **MCP 服务器** — 从 Claude Code、Codex、Cursor 或任何支持 MCP 的 AI 代理构建、编辑和部署 Telegram 机器人。无需 SDK 样板代码：描述机器人，您的代理将组装流程。
[FlowCastle](https://flowcastle.ai) 是一个用于 Telegram 机器人和网页聊天的可视化工作流构建器：流程、触发器、条件、AI 步骤、支付（Stripe / YooKassa / Telegram Stars）、广播、滴灌序列和集成（Gmail、Google Sheets、Notion、OpenAI、…）— 带有 REST API 和 MCP 服务器，因此机器人开发可以直接从您的 AI 编码代理进行。代理通过 MCP 创建的每个块都是您可以在可视化界面中拖拽、连接和编辑的相同块。
此仓库适用于开发者。它包含：
| 路径 | 内容 |
|------|-----------|
| [`templates/`](templates/) | 23 个生产级机器人模板（JSON 格式）— 与 [模板画廊](https://flowcastle.ai/templates) 和 MCP `get_flow_example` 工具相同的源代码 |
| [`mcp/`](mcp/) | MCP 服务器参考：端点、身份验证、所有 16 种工具以及 `apply_actions` 使用的流程操作模式快照 |
## 从 AI 代理（MCP）构建机器人
FlowCastle 通过 **可流式 HTTP** 公开 MCP 服务器：
```
POST https://api.flowcastle.ai/api/mcp
Authorization: Bearer <您的应用 API 密钥> # 以 app_ 开头
```
获取密钥：[注册](https://dashboard.flowcastle.ai/register) → 创建应用 → **API** 页面 → **MCP** 标签。
**Claude Code**
```bash
export FLOWCASTLE_MCP_TOKEN='<您的应用 API 密钥>'
claude mcp add --transport http flowcastle https://api.flowcastle.ai/api/mcp \
--header "Authorization: Bearer $FLOWCASTLE_MCP_TOKEN"
```
**Codex**
```bash
codex mcp add flowcastle \
--url https://api.flowcastle.ai/api/mcp \
--bearer-token-env-var FLOWCASTLE_MCP_TOKEN
```
**Cursor / 任意 MCP 客户端（JSON 配置)**
```json
{
"mcpServers": {
"flowcastle": {
"type": "http",
"url": "https://api.flowcastle.ai/api/mcp",
"headers": {
"Authorization": "Bearer <您的应用 API 密钥>"
}
}
}
}
```
然后，您可以向代理提出以下请求：
> *"查看我的 FlowCastle 工作区并添加一个潜在客户资格流程：在 /start 时问候，询问三个按钮问题，将答案保存到联系人变量，并通知我。"*
代理使用 `get_workspace_summary` / `get_flow_context` 读取您的工作区，起草一批流程构建器操作，使用 `validate_actions` 进行检查，并使用 `apply_actions` 应用它们。有关完整的工具参考，请参见 [`mcp/README.md`](mcp/README.md)。
## 模板
[`templates/`](templates/) 中的每个 JSON 文件都是一个完整的机器人：元数据（标题、摘要、用例、建议的变量、所需的模块）加上 `schemaExample.actions` 数组 — 一个有序的 `create_flow` / `create_block` / `create_link` / `create_variable` 操作批处理，格式与 `apply_actions` 接受的格式完全相同。
使用模板的三种方式：
1. **一键安装** 从画廊：[flowcastle.ai/templates](https://flowcastle.ai/templates)
2. **通过 MCP** — 请求您的代理 `search_flow_examples` / `get_flow_example` 并将一个（可选自定义）模板应用到您的工作区
3. **作为参考** — 研究真实流程如何连接触发器、条件、等待回复步骤、支付和 AI 模块
完整索引和格式描述：[`templates/README.md`](templates/README.md)。
## REST 公共 API
用于联系人、联系人变量、目标事件、流程发送和广播的应用范围 REST API：
- 基础 URL：`https://api.flowcastle.ai/api/public/v1`
- 交互式文档（Swagger）：https://api.flowcastle.ai/api/public/docs
- OpenAPI 规范：https://api.flowcastle.ai/api/public/openapi.json
身份验证使用相同的 `app_…` 应用密钥（`Authorization: Bearer` 或 `X-API-Key`）。
## 指南
[FlowCastle 博客](https://flowcastle.ai/blog) 上的逐步构建：
- [在 10 分钟内构建 Telegram 中的潜在客户机器人](https://flowcastle.ai/blog/lead-bot-in-telegram)
- [为 Telegram 构建 AI 支持机器人](https://flowcastle.ai/blog/ai-support-bot)
- [我用一个 Telegram 机器人替换了我的晨间应用](https://flowcastle.ai/blog/morning-digest-bot)
## 链接
- 产品：https://flowcastle.ai
- 仪表盘：https://dashboard.flowcastle.ai
- 模板画廊：https://flowcastle.ai/templates
- API 文档：https://api.flowcastle.ai/api/public/docs
## 贡献
在模板中发现了错误或构建了一个值得分享的流程？打开问题或 PR — 模板是纯 JSON 文件，`validate_actions`（通过 MCP）将告诉您批处理是否格式正确。
## 许可证
此仓库的内容根据 [MIT 许可证](LICENSE) 授权。
