# Pocket Invoice MCP 使用手册

## 1. 连接 Codex

在 Codex 的 MCP 设置中新增服务：名称 `Pocket Invoice`，类型 `Streamable HTTP`，地址 `https://api.freedominvoice.com/mcp`。

点击授权，在 Pocket Invoice 登录页面使用现有账号登录，选择一家公司和权限，点击 Allow access，然后回到 Codex。每个连接只属于一家公司。

安装了 Codex CLI 的用户可以执行：

```sh
codex mcp add pocket-invoice --url https://api.freedominvoice.com/mcp
codex mcp login pocket-invoice
codex mcp list
```

`codex mcp --help` 查看连接管理命令。Codex 终端界面的 `/mcp` 查看当前连接。无需安装 Pocket Invoice 的 npm 服务包，业务运行在 Pocket Invoice 后台。

## 2. 在聊天框里直接提出需求

例如：“使用 Pocket Invoice 给 Joe 创建 invoice，桌子 3 张，单价 10；椅子 5 个，单价 20，生成 PDF。”

AI 读取公司货币、付款期限和模板，后台计算金额、分配编号并保存到你的账号。示例合计为 130，使用所选公司的货币。没有指定到期日时，使用公司付款期限。

结果中会显示“查看发票”和“下载 PDF”链接。查看发票打开 Web 列表中这张单据的 Preview；未登录时先登录，再回到原单据。跨公司链接会切换 Web 当前公司。PDF 下载链接默认有效 1 小时，到期后可以重新生成。创建单据或 PDF 不会发送邮件。

## 3. 功能说明

| 功能 | 示例指令 |
|---|---|
| Invoice、estimate、purchase order | 给 Acme 创建报价，咨询 10 小时，每小时 80；还可查询、修改、复制、转换单据 |
| PDF、附件 | 生成 invoice 1042 的 PDF；添加已上传附件 |
| 邮件 | 准备将 invoice 1042 发给客户，给我确认收件人和内容；确认后再发送并查询状态 |
| 客户 | 查找 Acme；创建、修改客户；管理标签和提醒；查询对账单和账龄 |
| 商品、库存 | 查看椅子的库存；创建、修改商品；调整库存并查询记录 |
| 付款、订金 | 为 invoice 1042 记录今天收到的 250；这里只登记付款，不扣款、不转账 |
| 支出 | 记录今天交通支出 40；管理支出和分类，生成支出 PDF |
| 报表 | 查看本月销售、未付款、税务、支出、利润和客户报表 |
| 导入、导出 | 导出 invoice CSV；预览客户或商品 CSV 后导入 |
| 公司和设置 | 查看或修改公司信息、编号、PDF 模板、文字和税务设置；上传文件、将通知标为已读 |
| 账号 | 查看会员信息；打开账号设置和订阅网页 |

删除、团队、项目、预约、日程及周期任务目前不开放 MCP 调用。打印、设备锁和系统分享不属于 MCP 功能。

创建单据时，后台按名称模糊查找当前公司可访问的客户和商品。查到一条就关联，即使名称不完全相同；查到多条时，AI 会展示候选并询问你；没查到则新增。你明确表示不是查到的客户时，AI 可以按你指定的信息新增客户。新增客户、商品需要对应的管理权限。已有资料不会被覆盖，编辑单据中的客户和商品不会修改资料库。创建来源记录到 MCP 和可识别的 AI 应用；客户端自报名称不代表已验证身份。

## 4. 查询帮助

直接说：“Pocket Invoice help，告诉我现在能用哪些功能。”

AI 调用 `get_help`，按当前连接的授权列出仍开放的工具、说明和手册地址。公司团队权限仍在调用每个业务动作时检查。

## 5. 权限与撤销

读取权限只有一个“Read account data”。创建修改单据、客户、商品库存、付款、支出、公司设置各有写入权限。上传和账号偏好合并到公司设置权限。

默认勾选所有显示的权限，发送 document 除外。可在批准前取消不需要的权限。发送需要单独授权，并在聊天中确认每次发送的预览。增加权限或更换公司需要重新授权。

在 `https://app.freedominvoice.com/mcp/connections` 查看并撤销连接，撤销后停止访问。

## 6. Skill 安装

MCP 是实际业务工具，skill 是使用步骤说明。仅连接 MCP 就可以开单，skill 可选。

下载 `https://www.freedominvoice.com/mcp/downloads/pocket-invoice-workflow.zip`，解压后将 `pocket-invoice-workflow` 文件夹放到 `~/.agents/skills/`。在 Codex 中输入 `$pocket-invoice-workflow` 或直接提出开单需求，并保持 MCP 连接已授权。

安装了 Node.js 后，也可以使用命令安装：

```sh
npx skills add https://www.freedominvoice.com/mcp/downloads/pocket-invoice-workflow.zip --agent codex --global
```

这里的 `skills` 是 Vercel 发布到 npm 的安装工具，下载的是 Pocket Invoice 的 skill 文件；不需要另外发布 Pocket Invoice npm 包，也不需要本地运行服务器。skill 说明开单步骤，MCP 负责连接账号并执行操作，安装 skill 后仍需按第 1 节连接 MCP 并授权。

skill 也可以放到公开 GitHub 仓库，使用 `npx skills add GitHub账号/仓库名 --skill pocket-invoice-workflow --agent codex --global` 安装。官网 ZIP 与 GitHub 是两种发布文件的方式。官方插件目录仍需发布审核，不能当作已经上架。

## 7. 常见问题

- 看不到工具：检查服务已启用、地址正确、授权成功，在加载了该连接的聊天中使用。
- 授权过期或刷新令牌被拒绝：重新连接账号；不要重复使用失效令牌。
- 缺少权限：重新授权所需权限，并确认连接公司和团队权限。
- 单据已创建但 PDF 失败：用原单据 ID 重新生成 PDF，不要再开一张。
- PDF 链接到期：为原单据重新生成下载链接。
- Web Preview 无法打开：登录单据所属账号，确认有该公司的访问权限。
- 发送结果不确定：先查询发送状态。邮件服务商接受不代表已进入收件箱，不要自动重复发送。

英文网页手册：`https://www.freedominvoice.com/mcp/guide/`。