Skip to main content
Glama
README.md
# FastPospal

> **银豹 PosPal Python SDK 与 MCP Server**

FastPospal 是一个面向 **银豹 PosPal Web 后台** 的 Python SDK 与 MCP
Server,为开发者和 AI Agent
提供商品、会员、库存、货流、单据等业务能力的统一自动化接口。

<img width="1306" height="1204" alt="ChatGPT Image 2026年7月9日 05_20_57" src="https://github.com/user-attachments/assets/1a1fa057-5130-4451-a2b3-659b64717413" />

> **声明**
>
> -   本项目为社区维护项目,与银豹官方不存在任何关联。
> -   请仅在拥有合法授权的账号和门店中使用。
> -   本项目旨在提高自动化集成效率,不提供任何绕过认证或破解系统的能力。
> -   如官方开放平台能够满足业务需求,建议优先使用官方接口。

------------------------------------------------------------------------

## ✨ 特性

-   Python SDK
-   FastMCP Server(STDIO / HTTP)
-   商品、分类、会员 CRUD
-   库存、货流、单据查询
-   Cursor / Claude Desktop 开箱即用
-   uv 管理依赖
-   Docker、systemd、Nginx 部署支持

------------------------------------------------------------------------

## 为什么选择 FastPospal?

银豹官方开放平台覆盖能力有限,而 Web 后台拥有更丰富的业务接口。

FastPospal 对这些能力进行了统一封装:

-   Python 程序可直接调用
-   AI Agent 可通过 MCP 自动调用
-   后续可扩展 CLI、REST API 等能力

MCP 只是接口形式,Python SDK 才是核心能力。

------------------------------------------------------------------------

## 快速开始

### 安装 uv

``` bash
brew install uv
```

### 安装依赖

``` bash
uv sync
```

### 配置账号

``` bash
cp .env.example .env
```

填写:

``` text
POSPAL_ACCOUNT=your_account
POSPAL_PASSWORD=your_password
```

### 启动 MCP

默认暴露精简工具集(42 个)。需要原始层重叠查询时设置:

``` bash
export POSPAL_MCP_PROFILE=advanced   # 额外暴露 login / business_summary 等
```

STDIO:

``` bash
uv run fastmcp run server.py:mcp
```

HTTP:

``` bash
uv run fastmcp run server.py:mcp --transport http --port 8000
```

------------------------------------------------------------------------

## Python SDK 示例

``` python
from fastpospal.client import PospalClient
from fastpospal.service import PospalService

client = PospalClient(account, password)
client.login()

svc = PospalService(client)

print(svc.product_summary())
```

------------------------------------------------------------------------

## MCP 使用示例

在 Cursor 或 Claude Desktop 中:

> 查询今天商品总数

> 搜索条码 6901234567890

> 创建一个测试商品

Agent 将自动调用对应 MCP 工具。

------------------------------------------------------------------------

## 远程 HTTP 部署(Nginx + Docker)

适用于 OPC Feed、Cursor 等通过 HTTPS 远程连接 MCP。

1.  配置 `.env`:`POSPAL_*`、`MCP_AUTH_TOKEN`,以及公网域名白名单:

    ``` text
    FASTMCP_HTTP_ALLOWED_HOSTS=["your-domain.com"]
    ```

    经 Nginx 反代时 **必须** 设置,否则 Bearer 鉴权通过后 FastMCP 会因 `Host`
    校验返回 **421 Misdirected Request**。

2.  启动容器:`docker compose -f deploy/docker-compose.prod.yml up -d`

3.  Nginx 反代 **不要用尾斜杠**(`/pospal/mcp` 而非 `/pospal/mcp/`),否则 FastMCP
    会 307 到错误路径。萌萌书店示例见
    `deploy/nginx-mmsd-pospal-mcp.conf`。

4.  客户端 MCP URL 与 Nginx location 保持一致,例如
    `https://mmsd.site/pospal/mcp`。

### 发布到生产(GitHub Actions)

主路径:push 到 `main` 后,在 **haqyd self-hosted runner** 上自动 **patch bump** → 构建镜像 → SSH `docker load` → **覆盖服务器 `.env`** → compose 重启(避免 GitHub 托管 runner 跨国传镜像过慢)。

首次或密钥变更时,在本机同步 Secrets(需已 `gh auth login`):

```bash
# .env 中需有 POSPAL_*、MCP_AUTH_TOKEN、DEPLOY_HOST(及可选 DEPLOY_USER)
# SSH 私钥默认读 ~/.ssh/id_rsa,可用 DEPLOY_SSH_KEY_FILE 覆盖
bash scripts/sync-gh-secrets.sh
```

之后:

```bash
git push origin main
```

在仓库 Actions 查看 `Deploy` workflow。手动补跑:Actions → Deploy → Run workflow。

紧急本机发布(不走 CI):`bash deploy/push-image.sh`(本机脚本**不会**覆盖服务器 `.env`)。

------------------------------------------------------------------------

## 架构

``` text
AI Agent
(Cursor / Claude)

        │

        ▼

 FastPospal MCP

        │

 FastPospal SDK

        │

 PosPal Web
```

------------------------------------------------------------------------

## Roadmap

-   [x] 登录与会话管理
-   [x] 商品管理
-   [x] 分类管理
-   [x] 会员管理
-   [x] 库存查询
-   [x] HTTP MCP
-   [ ] CLI
-   [ ] PyPI 发布
-   [ ] 自动化测试
-   [ ] 官方 OpenAPI 适配

------------------------------------------------------------------------

## 参与贡献

- [贡献指南](CONTRIBUTING.md) — 开发环境、测试与 PR 流程
- [安全政策](SECURITY.md) — 漏洞私下报告方式

提交 Issue 时可选择 **Bug 报告** 或 **功能建议** 模板。

------------------------------------------------------------------------

<img width="1672" height="941" alt="ChatGPT Image 2026年7月9日 05_22_19" src="https://github.com/user-attachments/assets/41b0929b-6b4c-488c-9ae9-38d0a21c95d4" />

## License

MIT

TDQS

B3.2/5.0

Scored across 28 tools

Disambiguation5/5

Each tool targets a distinct entity and action (e.g., create vs. list vs. delete for categories, customers, products). There is no overlap in functionality; even search tools are differentiated by query parameters (barcode vs. customer number).

Naming Consistency4/5

Most tools follow the pospal_verb_noun pattern (e.g., pospal_create_category, pospal_list_products), but a few deviate (pospal_login, pospal_openapi_status, pospal_session_info) breaking the pattern slightly.

Tool Count5/5

28 tools cover a wide range of POS operations (categories, customers, products, stock, orders, tickets, suppliers) without being excessive. Each tool serves a clear purpose and the count is appropriate for the domain.

Completeness4/5

The tool set provides CRUD for core entities (categories, customers, products) and read-only access for orders, purchases, stock, and tickets. Missing create operations for some entities (e.g., suppliers, purchase orders) are minor gaps that agents can work around.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues