framework360-mcp-server

cp-server [](LICENSE) []() [](https://protocol.io) [](end) 用于 [Framework360www.framework360.it)（CRM/CMS）的 REST API 的MCP** 和 **。它提供了 141 个 API 端点作为现成的工具/命令，既可以在 MCP 客户端（例如 Claude Code）中使用，也可以在命令行/脚本中使用。 > 相关项目framework360-skill](https://github.com/VadaLinux/framework) — 一个 Claude Code 技能，演示如何在 Claude Code中直接使用此存储库的## 目录 -](#是什么) - [需求](#需求) - [安装](#- [配置](#配置) - [用作 MCP 服务器](#用作服务器) - [用作 CLIcli) - [主要主要命令) -的选项](#传递参数) - [示例](#示例) - [退出代码](#退出代码) - [完整的端点参考](#完整的端点参考 [项目结构](#项目结构) - [测试](#测试 [故障排除](#故障排除) - [安全](#安全) - [贡献](#贡献) - [许可证](#许可证) ## 是什么 Framework360 通过头部（`X-Fw360-Key`）暴露了一个经过身份验证的 REST API，用于管理客户，用户，订单，聊天，营销，内容，报告和 CMS 插件（日历，管道，票证，会员资格，博客）。该存储库提供了两种等效的方法来使用它，而无需手动编写 HTTP 代码： - **MCP 服务器**（`src/index.mjs` 在 stdio 上实现 [Model Context Protocol](https://model)。每个 API 端成为一个 MCP 工具，可以从兼容的客户端 Claude Code，Claude Desktop 或任何 MCP 主机） **CLI**（`bin/cli.mjs`）-点集，可以从自动化脚本中调用，无客户端。 两者共享： 相同的配置（`.env API 密钥和基本 URL 的单一真实来源； - 相同的端点定义（`.json`）- 141，包含 HTTP 方法标题，描述和，均来自官方 API 文档。 ## 需求 - Node.js 或更高版本（使用全局 `fetch`，无需运行时外部 HTTP 依赖） - Framework360 API 密钥（头部 `X-Fw360-Key`）和已启用 API 模块的站点的基本 URL ## 安装 ```bash git clone https://github.com/VadaLinux/framework360-mcp-server.git cd framework360-mcp-server npm install cp .env.example .env ``` ## 配置 所有配置都存储在一个名为 `.env` 的项目根目录文件中： ```env FRAMEWORK360_API_KEY=您的-api-key FRAMEWORK360_BASE_URL=https://您的网站.example.com ``` | 变量 | 必需 | 描述 | |---|---|---| | `FRAMEWORK360_API_KEY` | 是 | 站点的 API 密钥，在每个请求中通过头部 `X-Fw360-Key` 发送 | | `FRAMEWORK360_BASE_URL` | 否（默认为 `https://crigamo3.com`） | Framework360 站点的基本 URL，不带尾部斜杠 | `.env` 是 **单一真实来源**：MCP 服务器和 CLI 都在启动时自动加载它（通过 [`dotenv`](https://www.npmjs.com/package/dotenv)），其他地方设置变量在 MCP 客户端配置中如果将来要更改密钥或域，只需修改此文件。 ## 用作 将服务器添加到您的客户端配置（例如 Claude Code）中，指向 `src/index.mjs` 的绝对路径： ```json { "mcpServers": { "framework360": { "type": "stdio", "command": "node", "args":绝对路径/framework360-mcp-server/src/index.mjs"] } } } ``` 无需在配置中传递 `env`：时自动从项目根目录加载 `.env`。 点都作为 MCP 工具公开：工具名称与（例如 `/m/api/customers/get`），并接受一个 `args` 参数，即调用参数的 JSON 字符串（例如 `{"id": 101}`）。GET/DELETE 请求将参数作为查询字符串传递，其他请求作为 JSON 正文传递。 > 注意：如果在 MCP 服务器已连接到会话时修改 `.env`，则需要重启连接（或客户端会话），以便进程重新读取环境 - 它只在启动时读取 用作bash node binjs <命令> [选项] ``` 或者，在 ` 后，命令可全局使用 `framework360`（package.json` 中的 `bin` 字段）。 ### 主要命令 | 命令 | 描述 | |---|---| | `list [文本]` | 列出可用的端点，可按路径、标题或描述 | | `资源 操作...>` | 显示命令的 HTTP 方法、完整路径、描述和预期参数 | | `<资源> <操作...> [选项]` | 调用 `/m/api/<资源>/<操作...>` 的快捷方式（例如 `customers get` → `/m/api/customers/get`） | | `call <路径> [选项]` | 按确切路径调用端点，如果路径不符合两字模式，则调用此命令 | | `check` | 调用 `/m/api/check` 的快捷方式 -，无参数，无副作用 | | `help`，`-h`，`--help` | 显示帮助 | ### 传递参数的选项 | 选项 | 描述 | |---|---| | `-p, --param 键=值` | 参数（可重复）。如果可能，值被解释为 JSON （`id=101` → 数字，`active=true` → 布尔值）。键会生成数组（customer_ids`，`` 等| `-d, --data '<json>'` | 完整的 JSON 有效载荷，优先级高于 `-p`（覆盖）- 适用于嵌套有效载荷 | | --file <路径>` | 从 JSON 文件中读取荷，与 `--data` 合并 | | `--dry-run将发送的 URL、方法和正文 **而不 | | `--raw` | 打印响应正文将其格式化为 JSON | | `-o, --output < | 将响应正文保存到文件而不是打印 | | <路径>` | 使用env` 文件而不是项目 示例 ```bash # 验证连接 node bin/cli check # 发现可用命令 node bin/cli.mjs list customers node.mjs describe customers get # 读取数据 node bin/cli.mjs customers get -p id=101 node bin/cli.mjs customers list -p query=Mario -p limit=15 数组参数（重复键） node bin/cli.mjs customers labels assign -p customer_ids=1 -p customer_ids=2 -p label_ids=5 # 复杂 JSON 有效载荷 node bin/cli.mjs report export -d '{"reportName":"sales_summary","format":"csv","dateFrom":"2023-01dateTo":"2023-01-31"}' # 在实际执行请求之前测试调用（建议用于 create/update/delete） node bin/cli.m -p id=42 --dry-run #到文件 node.mjs report data -=2024-01-01 -p end_date-03-o report.json ``` 退出代码 CLI 在退出代码 `0` 在正文中返回应用错误，例如 `{"statuserror":"..."}` - 这仍然是一个有效的 HTTP 响应 CLI 自身出现错误时退出代码 `1` 参数，未知的，缺少 `.env` 或没有 API 密钥，文件不可读等。 ## 完整端点参考 141个端点在[`endpoints.json`](./endpoints.json)中定义，并按资源分组。每个端点都标有HTTP方法、REST路径和等效的CLI命令。 <details> <summary><strong>聊天</strong> (11个端点)</summary> - `GET` `/m/api/chat/list` — 聊天列表 (`聊天列表`) - `GET` `/m/api/chat/messages` — 聊天消息 (`聊天消息`) - `GET` `/m/api/chat/get` — 获取聊天 (`获取聊天`) - `POST` `/m/api/chat/reply` — 回复聊天 (`回复聊天`) - `POST` `/m/api/chat/deleteMessage` — 删除聊天消息 (`删除聊天消息`) - `GET` `/m/api/chat/types` — 聊天消息类型 (`聊天消息类型`) - `GET` `/m/api/chat/templates` — 聊天模板列表 (`聊天模板列表`) - `POST` `/m/api/chat/create` — 创建对话 (`创建对话`) - `POST` `/m/api/chat/updateStatus` — 更新聊天状态 (`更新聊天状态`) - `POST` `/m/api/chat/markAs` — 标记聊天 (`标记聊天`) - `POST` `/m/api/chat/assign` — 分配聊天 (`分配聊天`) </details> <details> <summary><strong>检查</strong> (1个端点)</summary> - `GET` `/m/api/check` — 连接检查 (`连接检查`) </details> <details> <summary><strong>结账</strong> (1个端点)</summary> - `GET` `/m/api/checkouts/get` — 结账详情 (`结账详情`) </details> <details> <summary><strong>内容</strong> (1个端点)</summary> - `GET` `/m/api/content/sliders/get` — 滑块详情 (`滑块详情`) </details> <details> <summary><strong>客户</strong> (20个端点)</summary> - `GET` `/m/api/customers/profile` — 客户资料 (`客户资料`) - `GET` `/m/api/customers/get` — 获取客户 (`获取客户`) - `GET` `/m/api/customers/list` — 客户列表 (`客户列表`) - `GET` `/m/api/customers/search` — 搜索客户 (`搜索客户`) - `POST` `/m/api/customers/delete` — 删除客户 (`删除客户`) - `POST` `/m/api/customers/login` — 客户登录 (`客户登录`) - `POST` `/m/api/customers/registration` — 客户注册 (`客户注册`) - `POST` `/m/api/customers/update` — 更新客户 (`更新客户`) - `GET` `/m/api/customers/sources` — 客户来源 (`客户来源`) - `GET` `/m/api/customers/labels/list` — 客户标签列表 (`客户标签列表`) - `POST` `/m/api/customers/labels/assign` — 分配客户标签 (`分配客户标签`) - `POST` `/m/api/customers/labels/remove` — 删除客户标签 (`删除客户标签`) - `GET` `/m/api/customers/history/list` — 客户历史列表 (`客户历史列表`) - `POST` `/m/api/customers/history/create` — 创建客户历史 (`创建客户历史`) - `POST` `/m/api/customers/history/update` — 更新客户历史 (`更新客户历史`) - `GET` `/m/api/customers/notifications/status` — 客户通知状态 (`客户通知状态`) - `GET` `/m/api/customers/notifications/list` — 客户通知列表 (`客户通知列表`) - `POST` `/m/api/customers/notifications/mark` — 标记通知为已读 (`标记通知为已读`) - `POST` `/m/api/customers/notifications/register` — 注册通知设备 (`注册通知设备`) - `POST` `/m/api/customers/notifications/unregister` — 注销通知设备 (`注销通知设备`) </details> <details> <summary><strong>仪表盘</strong> (1个端点)</summary> - `GET` `/m/api/dashboard/get` — 仪表盘数据 (`仪表盘数据`) </details> <details> <summary><strong>数据表</strong> (1个端点)</summary> - `GET` `/m/api/datatables/get` — 数据表数据 (`数据表数据`) </details> <details> <summary><strong>表单</strong> (1个端点)</summary> - `POST` `/m/api/forms/submit` — 提交表单 (`提交表单`) </details> <details> <summary><strong>潜在客户流程</strong> (7个端点)</summary> - `GET` `/m/api/leadflow/settings` — 潜在客户流程设置 (`潜在客户流程设置`) - `GET` `/m/api/leadflow/history` — 潜在客户流程历史 (`潜在客户流程历史`) - `GET` `/m/api/leadflow/schedule/list` — 潜在客户流程调度列表 (`潜在客户流程调度列表`) - `POST` `/m/api/leadflow/schedule/save` — 保存潜在客户流程调度 (`保存潜在客户流程调度`) - `GET` `/m/api/leadflow/flow/get_contact` — 获取潜在客户流程联系人 (`获取潜在客户流程联系人`) - `POST` `/m/api/leadflow/flow/save` — 保存潜在客户流程联系人 (`保存潜在客户流程联系人`) - `POST` `/m/api/leadflow/flow/owner` — 分配潜在客户流程所有者 (`分配潜在客户流程所有者`) </details> <details> <summary><strong>营销</strong> (8个端点)</summary> - `GET` `/m/api/marketing/tags` — 营销标签列表 (`营销标签列表`) - `GET` `/m/api/marketing/campaigns/flow` — 营销活动流程 (`营销活动流程`) - `GET` `/m/api/marketing/campaigns/contacts` — 营销活动联系人 (`营销活动联系人`) - `POST` `/m/api/marketing/campaigns/updateStatus` — 更新营销活动状态 (`更新营销活动状态`) - `GET` `/m/api/marketing/campaigns/action/summary` — 营销活动行动总结 (`营销活动行动总结`) - `GET` `/m/api/marketing/campaigns/action/stats` — 营销活动行动统计 (`营销活动行动统计`) - `GET` `/m/api/marketing/campaigns/statuses` — 营销活动状态 (`营销活动状态`) - `GET` `/m/api/marketing/campaigns/types` — 营销活动类型 (`营销活动类型`) </details> <details> <summary><strong>媒体</strong> (6个端点)</summary> - `GET` `/m/api/media/list` — 媒体列表 (`媒体列表`) - `GET` `/m/api/media/directories` — 媒体目录列表 (`媒体目录列表`) - `POST` `/m/api/media/delete` — 删除媒体 (`删除媒体`) - `POST` `/m/api/media/add` — 添加媒体 (`添加媒体`) - `POST` `/m/api/media/update` — 更新媒体 (`更新媒体`) - `POST` `/m/api/media/format` — 格式化媒体 (`格式化媒体`) </details> <details> <summary><strong>订单</strong> (15个端点)</summary> - `POST` `/m/api/orders/create` — 创建订单 (`创建订单`) - `POST` `/m/api/orders/import` — 导入订单 (`导入订单`) - `GET` `/m/api/orders/list` — 订单列表 (`订单列表`) - `GET` `/m/api/orders/get` — 获取订单 (`获取订单`) - `POST` `/m/api/orders/updateStatus` — 更新订单状态 (`更新订单状态`) - `POST` `/m/api/orders/resendNotifications` — 重新发送订单通知 (`重新发送订单通知`) - `POST` `/m/api/orders/cancel` — 取消订单 (`取消订单`) - `POST` `/m/api/orders/delete` — 删除订单 (`删除订单`) - `POST` `/m/api/orders/repeat` — 重复订单 (`重复订单`) - `POST` `/m/api/orders/prepareCart` — 准备购物车 (`准备购物车`) - `POST` `/m/api/orders/shippings` — 获取可用运输方式 (`获取可用运输方式`) - `POST` `/m/api/orders/applyCoupon` — 应用优惠券 (`应用优惠券`) - `GET` `/m/api/orders/statuses` — 订单状态列表 (`订单状态列表`) - `GET` `/m/api/orders/coupons` — 优惠券列表 (`优惠券列表`) - `GET` `/m/api/orders/labels` — 订单标签详情 (`订单标签详情`) </details> <details> <summary><strong>支付</strong> (2个端点)</summary> - `GET` `/m/api/payments/list` — 支付方式列表 (`支付方式列表`) - `GET` `/m/api/payments/taxes` — 税费列表 (`税费列表`) </details> <details> <summary><strong>插件</strong> (38个端点)</summary> - `POST` `/m/api/plugins/install` — 安装插件 (`安装插件`) - `GET` `/m/api/plugins/settings` — 插件设置 (`插件设置`) - `GET` `/m/api/plugins/calendar/forms/list` — 日历表单列表 (`日历表单列表`) - `GET` `/m/api/plugins/calendar/forms/select` — 获取日历表单 (`获取日历表单`) - `GET` `/m/api/plugins/calendar/forms/getAvailability` — 获取日历表单可用性 (`获取日历表单可用性`) - `GET` `/m/api/plugins/calendar/forms/getLockedDays` — 获取日历表单锁定日期 (`获取日历表单锁定日期`) - `POST` `/m/api/plugins/calendar/create` — 创建日历事件 (`创建日历事件`) - `POST` `/m/api/plugins/calendar/cancel` — 取消日历事件 (`取消日历事件`) - `POST` `/m/api/plugins/calendar/update` — 更新日历事件 (`更新日历事件`) - `GET` `/m/api/plugins/pipeline/pipelines/list` — 流水线列表 (`流水线列表`) - `GET` `/m/api/plugins/pipeline/pipelines/get` — 获取流水线 (`获取流水线`) - `GET` `/m/api/plugins/pipeline/items/list` — 流水线项目列表 (`流水线项目列表`) - `POST` `/m/api/plugins/pipeline/items/add` — 添加流水线项目 (`添加流水线项目`) - `POST` `/m/api/plugins/pipeline/items/move` — 移动流水线项目 (`移动流水线项目`) - `POST` `/m/api/plugins/pipeline/items/delete` — 删除流水线项目 (`删除流水线项目`) - `GET` `/m/api/plugins/pipeline/groups/list` — 流水线分组列表 (`流水线分组列表`) - `GET` `/m/api/plugins/pipeline/groups/get` — 获取流水线分组 (`获取流水线分组`) - `POST` `/m/api/plugins/pipeline/groups/create` — 创建流水线分组 (`创建流水线分组`) - `POST` `/m/api/plugins/pipeline/groups/update` — 更新流水线分组 (`更新流水线分组`) - `POST` `/m/api/plugins/pipeline/groups/delete` — 删除流水线分组 (`删除流水线分组`) - `POST` `/m/api/plugins/pipeline/groups/sort` — 排序流水线分组 (`排序流水线分组`) - `POST` `/m/api/plugins/pipeline/groups/truncate` — 清空流水线分组 (`清空流水线分组`) - `GET` `/m/api/plugins/tickets/list` — 工单列表 (`工单列表`) - `GET` `/m/api/plugins/tickets/departments` — 工单部门列表 (`工单部门列表`) - `POST` `/m/api/plugins/tickets/create` — 创建工单 (`创建工单`) - `GET` `/m/api/plugins/tickets/detail` — 获取工单详情 (`获取工单详情`) - `POST` `/m/api/plugins/tickets/reply` — 回复工单 (`回复工单`) - `POST` `/m/api/plugins/tickets/close` — 关闭工单 (`关闭工单`) - `GET` `/m/api/plugins/membership/getPlans` — 会员计划列表 (`会员计划列表`) - `GET` `/m/api/plugins/membership/getSubscriptionStatus` — 获取会员订阅状态 (`获取会员订阅状态`) - `GET` `/m/api/plugins/protectedContent/list` — 保护内容列表 (`保护内容列表`) - `GET` `/m/api/plugins/blog/posts/list` — 博客帖子列表 (`博客帖子列表`) - `GET` `/m/api/plugins/blog/posts/get` — 获取博客帖子 (`获取博客帖子`) - `POST` `/m/api/plugins/blog/posts/trackView` — 跟踪博客帖子浏览 (`跟踪博客帖子浏览`) - `POST` `/m/api/plugins/blog/posts/add` — 添加博客帖子 (`添加博客帖子`) - `POST` `/m/api/plugins/blog/posts/delete` — 删除博客帖子 (`删除博客帖子`) - `GET` `/m/api/plugins/blog/categories/list` — 博客分类列表 (`博客分类列表`) - `GET` `/m/api/plugins/blog/categories/get` — 获取博客分类 (`获取博客分类`) </details> <details> <summary><strong>报告</strong> (4个端点)</summary> - `GET` `/m/api/report/lists` — 报告列表 (`报告列表`) - `GET` `/m/api/report/data` — 报告数据 (`报告数据`) - `GET` `/m/api/report/dashboard` — 报告仪表盘 (`报告仪表盘`) - `POST` `/m/api/report/export` — 导出报告 (`导出报告`) </details> <details> <summary><strong>报表</strong> (2个端点)</summary> - `POST` `/m/api/reports/get` — 获取报表 (`获取报表`) - `GET` `/m/api/reports/categories` — 报表分类列表 (`报表分类列表`) </details> <details> <summary><strong>搜索</strong> (1个端点)</summary> - `GET` `/m/api/search/list` — 搜索数据 (`搜索数据`) </details> <details> <summary><strong>站点</strong> (5个端点)</summary> - `GET` `/m/api/site/data` — 站点数据 (`站点数据`) - `GET` `/m/api/site/assets` — 站点资源 (`站点资源`) - `GET` `/m/api/site/settings` — 站点设置 (`站点设置`) - `GET` `/m/api/site/plugins` — 站点插件 (`站点插件`) - `GET` `/m/api/site/theme` — 站点主题 (`站点主题`) </details> <details> <summary><strong>Slug</strong> (1个端点)</summary> - `GET` `/m/api/slug/check` — 检查Slug (`检查Slug`) </details> <details> <summary><strong>订阅</strong> (2个端点)</summary> - `GET` `/m/api/subscriptions/getSubscriptionStatus` — 获取订阅状态 (`获取订阅状态`) - `POST` `/m/api/subscriptions/addSubscription` — 添加订阅 (`添加订阅`) </details> <details> <summary><strong>用户</strong> (10个端点)</summary> - `GET` `/m/api/users/get` — 获取用户 (`获取用户`) - `POST` `/m/api/users/update` — 更新用户 (`更新用户`) - `GET` `/m/api/users/profile` — 用户资料 (`用户资料`) - `GET` `/m/api/users/list` — 用户列表 (`用户列表`) - `POST` `/m/api/users/delete` — 删除用户 (`删除用户`) - `POST` `/m/api/users/login` — 用户登录 (`用户登录`) - `POST` `/m/api/users/reset` — 重置密码 (`重置密码`) - `POST` `/m/api/users/registration` — 用户注册 (`用户注册`) - `POST` `/m/api/users/notifications/register` — 注册通知 (`注册通知`) - `POST` `/m/api/users/notifications/unregister` — 注销通知 (`注销通知`) </details> <details> <summary><strong>Webhook</strong> (3个端点)</summary> - `POST` `/m/api/webhooks/create` — 创建Webhook (`创建Webhook`) - `POST` `/m/api/webhooks/delete` — 删除Webhook (`删除Webhook`) - `GET` `/m/api/webhooks/test` — 测试Webhook (`测试Webhook`) </details> 要获取每个端点的详细标题、描述和参数，请使用`node bin/cli.mjs describe <资源操作...>`，或直接查看`endpoints.json`。 ## 项目结构 ``` bin/cli.mjs CLI入口点（可执行shebang） src/index.mjs MCP服务器（stdio） src/cli.mjs CLI命令逻辑（参数解析，列表/描述/调用） src/lib.mjs 共享逻辑：.env加载，认证头，payload标准化，HTTP调用执行 endpoints.json 141个端点定义（方法，路径，标题，描述，参数） tests/verify.mjs 项目结构验证 verify.py 141个端点的定义（方法，路径，标题，描述，参数） .env.example 配置模板 ``` ## 测试 ```bash npm test ``` 执行`tests/verify.mjs`，验证`endpoints.json`的结构，MCP服务器所需的组件是否存在，以及`.env.example`中是否存在预期的密钥。 ## 故障排除 **`Missing FRAMEWORK360_API_KEY （请在项目 `.env` 文件中设置）`** `.env`文件不存在或不包含`FRAMEWORK360_API_KEY`。复制`.env.example`到`.env`并填写。 **CLI响应`HTTP 200`但返回带有"Sites not found" HTML的页面** `FRAMEWORK360_BASE_URL`中的域名与活动Framework360站点不匹配。请在站点管理面板中验证基准URL。 **一个命令返回`{"status":0,"error":"..."}`和HTTP 200** 这是API的有效响应，指示应用程序错误（例如，资源未找到，参数缺失），而不是CLI/MCP错误。请使用`describe <command>`检查预期参数。 **命令/路径不识别** 使用`node bin/cli.mjs list <keyword>`搜索正确的命令：CLI还会建议最接近的匹配项，如果命令不存在。 **更改`.env`但MCP服务器仍使用旧值** MCP进程在启动时仅读取一次环境变量：在修改`.env`后，请重启MCP客户端会话。 ## 安全 - `.env`包含实际凭证，**绝不能提交**：已排除在`.gitignore`中。请使用`.env.example`作为参考。 - 在执行修改数据的命令（`create`，`update`，`delete`，`registration`，`assign`/`remove`标签等）之前，建议使用`--dry-run`检查将发送的请求。 - API密钥仅在`X-Fw360-Key`标头中发送到`FRAMEWORK360_BASE_URL`；不会将任何数据发送到其他地方。 ## 贡献 欢迎提交请求和错误报告。要添加新端点，请将其添加到`endpoints.json`（方法，路径，标题，描述，参数）- MCP服务器和CLI将自动公开，无需其他代码更改。 ## 许可 ISC - 请参见[`package.json`](./package.json)中的许可字段。