Final POS Flows (direct)

Final MCP 服务：使用 AI 构建自定义 POS 应用

将 Claude、ChatGPT、Gemini、Cursor、Codex 或任何 MCP 客户端连接到 Final：
使用 Flow 构建自定义 POS 应用（结账流程、自助结账 kiosks、支付终端）
并通过一个服务，从 Hub 管理其背后的门店。

https://ai.finalpos.com/mcp

连接 · 功能 · 工具参考 · 常见问题 · finalpos.com

---

Final MCP 服务是 Final 的官方 Model Context Protocol 服务， Final 是一个用于自定义销售点的商务平台。 一个远程端点 https://ai.finalpos.com/mcp，即可让 AI Agent 访问商家允许使用的每款 Final 产品：

• Flow，自定义 POS 应用构建器：描述结账流程后，Agent 会根据经过审核的屏幕蓝图构建应用，并以 Final 版本锁定的 POS API 为依据；随后验证应用、返回实时预览链接，并将其部署到支付终端、平板电脑和 kiosks。适用于柜台 POS、自助结账、餐厅点餐、厨房显示屏和线下支付应用。
• Hub，这些应用背后的后台管理系统：商品和目录、库存和采购订单、订单、客户、销售报告、团队和角色、门店、税费、预订。

使用 Final 账号登录（OAuth 2.1），并选择公司以及允许 Agent 执行的操作。无需在本地安装或运行任何内容。

端点	https://ai.finalpos.com/mcp
传输方式	Streamable HTTP
身份验证	OAuth 2.1 with PKCE（使用 Final 登录），或将 fai_ 连接密钥用作 Authorization: Bearer
注册表名称	com.finalpos/final
操作身份	代表连接服务的用户，在单个公司中，并且仅限其允许的工具包范围内操作
费用	免费连接；Agent 执行的操作遵循你的 Final 方案，就像你在 Final 中亲自操作一样

连接

大多数客户端只需提供 URL。客户端会打开 Final 登录页面，你可以在其中选择公司和工具包，之后即可完成连接。

Claude（claude.ai、Claude Desktop）

Settings → Connectors → Add custom connector，URL 为 https://ai.finalpos.com/mcp。

ChatGPT

Settings → Apps & Connectors → Advanced settings → Developer mode，然后使用 URL https://ai.finalpos.com/mcp 选择 Create。

Claude Code

claude mcp add --transport http final https://ai.finalpos.com/mcp

在 Claude Code 中运行 /mcp，然后选择 Authenticate。也可以安装插件，它会同时添加服务和 Final 操作手册技能。在 Claude Code 中：

/plugin marketplace add Final-Commerce/final-pos-mcp
/plugin install final@final

Gemini CLI

gemini extensions install https://github.com/Final-Commerce/final-pos-mcp

此扩展会添加服务、Final 操作手册和以下命令： /final-pos:stock、/final-pos:sales、/final-pos:new、/final-pos:preview、 /final-pos:validate 和 /final-pos:deploy。在 Gemini CLI 中运行 /mcp auth final，登录一次即可。若只添加服务：

gemini mcp add --transport http final https://ai.finalpos.com/mcp

Cursor

或在 ~/.cursor/mcp.json 中：

{
  "mcpServers": {
    "final": { "url": "https://ai.finalpos.com/mcp" }
  }
}

VS Code（GitHub Copilot）

在 VS Code 中安装，或者：

code --add-mcp '{"name":"final","type":"http","url":"https://ai.finalpos.com/mcp"}'

Codex、脚本和不使用 OAuth 的客户端

在 ai.finalpos.com/connections 创建连接密钥。 该密钥只会显示一次，页面会为每个客户端打印确切的代码片段。对于 Codex，请将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.final]
url = "https://ai.finalpos.com/mcp"
http_headers = { "Authorization" = "Bearer fai_YOUR_KEY" }

其他任何客户端：向 https://ai.finalpos.com/mcp 发送 POST 请求，并附上 Authorization: Bearer fai_YOUR_KEY。

以 sk_（Flow）或 fpm_（Hub）开头的密钥属于这些产品自己的 服务，不可在此使用。请改为创建 fai_ 密钥，或使用 OAuth。

检查是否正常运行

向你的 Agent 提问："Use Final to tell me which company you're connected to and which packs you can use." 它会调用 get_connection 和 list_packs。

你的 Agent 可以做什么

工具分为多个工具包。连接时，你可以选择 Agent 可使用的工具包，这些工具包也对应 OAuth 作用域。为缩小模型的上下文，每次连接只会列出少数几个工具包。核心工具可以访问其余工具包：find_tools 会搜索所有获准使用的工具包，而 call_tool 则可按名称调用任意获准使用的工具。

工具包	产品	涵盖内容	默认列出
catalog	Hub	产品、变体、类别、选项、修饰项、产品照片和媒体库	✓
inventory	Hub	库存水平和历史记录、调拨、供应商、采购订单、补货规则、库存 CSV 导入/导出
orders	Hub	订单、退款和电商订单同步（只读：收银机负责收款）
customers	Hub	客户记录、备注、订单历史和客户导入
reports	Hub	财务摘要、销售和付款明细、员工销售、会话、交易、记录导出
team	Hub	团队成员、角色和权限
store	Hub	门店、工作站、税费和 Hub 扩展
bookings	Hub	可预约服务：规则、资源、可预约时段、预留和确认
build	Flow	构建和部署 Final POS 应用：API 依据、蓝图、流程文件、预览沙盒、验证、部署	✓
build_data	Flow	自定义表（应用数据库）、密钥保管库和 Flow 扩展

工具名称会标明所属产品：hub_get_products、hub_find_low_stock、 flow_create_flow、flow_deploy_flow。TOOLS.md 列出了所有 工具，包括其所属工具包、是否会更改数据及其参数。

核心工具（始终列出）：get_connection、list_packs、find_tools、 call_tool、enable_packs、disable_packs、switch_company。

可以询问的内容

构建自定义 POS 应用（Flow）

• “构建一个咖啡店自助点单终端，包含商品网格、选项、购物车和银行卡支付，然后给我一个预览链接。”
• “在我的柜台应用中添加小费页面，并验证它。”
• “为一家小型杂货店创建自助结账流程，支持条码扫描和收据页面。”
• “发布我的自助结账流程的最新版本。”

应用构建通常会依次运行 flow_get_scaffold → flow_create_flow → flow_lookup_command_frame（依据）→ flow_get_blueprint → flow_write_flow_files → flow_validate_flow → flow_start_preview，并 返回一个实时预览 URL。Agent 构建的所有内容也会显示在 Final builder 中，每次文件写入都会成为可还原的检查点。

运营商店（Hub）

• “Main Street 门店中哪些商品的库存低于补货点？为常用供应商拟一份采购订单。”
• “比较上周和前一周各类别的销售额。”
• “从随附的电子表格中添加这 40 件商品，并附上照片。”
• “本月排名前十的客户是谁？他们买了什么？”
• “将 45 分钟按摩设置为可预约服务，并安排两位按摩师。”

安全与权限

• 你的角色仍然有效。 每次 Hub 调用都以连接者的身份运行，Hub 会在每次调用时检查其当前角色。仅限所有者执行的操作仍仅限所有者执行。
• 工具包决定权限。 Agent 只能调用你允许的工具包中的工具。你可以随时在 ai.finalpos.com/connections 修改工具包或断开连接；断开连接会立即撤销所有令牌。
• 写入操作会标注。 读取工具带有 readOnlyHint，部署和删除操作带有 destructiveHint，因此客户端可以在执行前询问。服务端会要求 Agent 在部署、删除和批量更改前向你确认。
• 资金操作保留在收银台上。 无法通过 MCP 收款、退款或作废订单。
• 机密不会经过模型。 flow_request_secret 会提示你在构建器中输入 API 密钥。
• 所有操作都会记录。 “Connections”页面会实时显示每个已连接的客户端及其进行的每次调用。
• Flow 限制： Flow 每小时允许启动 30 次预览、进行 12 次构建和部署，以及写入 300 个文件。

隐私与支持

• Final 会保留哪些内容。 连接信息（连接者、公司和工具包）、用于访问 Hub 和 Flow 的令牌（加密存储），以及每次工具调用的日志：工具、结果、耗时，以及经过脱敏处理的参数和结果预览。你可以在 Connections 页面查看这些日志。
• Final 不会看到哪些内容。 你的对话。MCP 客户端发送的是工具调用，而不是与之相关的聊天内容。
• 断开连接会删除已存储的令牌，并撤销为该连接签发的所有令牌。
• 隐私政策 · 条款
• 支持： [email protected]。如果本指南或插件有问题，请提交 issue。

Flow 的直接端点

在网关推出前完成的设置可能仍使用 https://flow.finalpos.com/api/mcp 和 Flow sk_ 密钥（注册表名称 com.finalpos.build/final-flows）。该端点仍可使用，但新设置应使用包含 Flow 的 https://ai.finalpos.com/mcp。

常见问题

Final MCP 服务是什么？

它是 Final POS 的官方 MCP 服务。通过一个远程 URL https://ai.finalpos.com/mcp，AI 助手即可读取和管理商家的 Final 后台（Hub），并构建 销售点应用（Flow）。

ChatGPT 或 Claude 能管理我的 Final POS 库存吗？

可以。连接时允许 inventory 工具包。Agent 可以检查库存水平、查找库存不足的商品、建议补货、创建采购订单并记录收货商品。

AI Agent 能在 Final 上构建 POS 应用吗？

可以。使用 build 套件，Agent 会创建一个流程，基于 Final 版本锁定的 API 和经过审核的屏幕蓝图编写应用、验证应用，并返回一个实时预览 URL。你可以从 Final 构建器中启动应用。

我需要 API 密钥吗？

如果你的客户端支持 OAuth（Claude、ChatGPT、Claude Code、Cursor、Gemini CLI、VS Code），则不需要：只需使用 Final 登录。Codex 和脚本需要使用从 ai.finalpos.com/connections 获取的 fai_ 密钥。

它会代表哪家公司执行操作？

你连接时选择的公司。如果你的账户中有多家公司，Agent 可以调用 switch_company。

Agent 能收款或退款吗？

不能。收款、退款和作废操作都在收银机上进行。通过 MCP 读取的订单为只读。

为什么我的 Agent 只能看到少数几个工具？

客户端会将列出的所有工具都放入模型上下文中，列表过长会降低质量。Agent 可以通过 find_tools 查找其他工具，通过 call_tool 调用工具，或通过 enable_packs 列出整个套件。

是否收费？

连接免费。Agent 执行的操作，按你使用 Final 自行完成相同工作时的方式，根据你的 Final 方案计费。

Final POS API 文档在哪里？

在 finalpos.com/docs。Agent 构建应用时无需单独查阅这些文档：build 套件会根据 Final 版本锁定的 API 为每次调用提供依据（flow_lookup_pos_api、flow_lookup_command_frame）。

关于此仓库

此仓库包含公开设置指南、MCP Registry 条目（server.json、legacy/）、Gemini CLI 扩展（gemini-extension.json、GEMINI.md、commands/）、Claude Code 和 Cursor 插件市场（.claude-plugin/、.cursor-plugin/，以及两者共用的 plugins/final/），以及生成的工具参考文档和与之对应的机器可读版本 catalog.json。https://ai.finalpos.com/.well-known/mcp/server-card.json 上的服务卡片也会读取该文件。GEMINI.md 和 Claude 技能使用同一份操作指南，CI 会检查两者是否一致。服务本身由 Final 托管；此仓库中的代码不会在你的机器上运行。

许可证

Apache-2.0 © Final Commerce