AI导哈

POS数据查询服务器

一个本地优先的只读MCP服务器，用于通过Loyverse POS API查询收据、商品、员工、客户、店铺和销售分析数据，专为AI助手设计。

  • by Novigante
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Novigante/mcp-loyverse

使用说明

mcp-loyverse

本地第一个只读MCP服务器 Loyverse POS API 它允许人工智能助手查询收据、物品、员工、客户、商店和销售分析，这些数据是为使用个人访问令牌在本地安全使用而构建的。

什么和为什么

mcp-loyverse 桥梁 模型上下文协议（MCP） 和Loyverse POS API，这样像Claude这样的人工智能助手就可以直接回答有关销售点数据的商业问题：

  • “今天的总销售额是多少？” --在一次工具调用中回答
  • “本周最畅销的商品是什么？” --自动聚合
  • “按销售额显示本月的顶尖员工” --名称解析

高级分析工具在内部处理分页、过滤和聚合，返回标记高效的简明摘要，而不是人工智能进行数十次分页API调用。

特性

  • 15个MCP工具 （1个系统+11个资源+3个分析）
  • 自动分页 用于分析——无需手动光标处理
  • 日期预设 — today, yesterday, this_week, this_month, last_7_days, last_30_days
  • 时区感知 日期分辨率（可配置，默认为UTC）
  • 只读 --只有GET请求，没有数据修改
  • 安全 --令牌从不出现在日志或错误消息中
  • 结构化日志记录 到具有可配置日志级别的stderr
  • 重试逻辑 --429上的指数回退（速率限制），5xx上的单次重试
  • 安全限制 --每次分析查询最多10000个收据，最大日期范围为90天

需求

  • Node.js 20+
  • Loyverse帐户 带着一个 个人访问令牌 （设置>个人访问令牌）

快速开始

无需克隆或构建，只需将服务器添加到MCP客户端即可：

克劳德代码（CLI）

claude mcp add loyverse \
  -e LOYVERSE_API_TOKEN=your_personal_access_token_here \
  -e DEFAULT_TIMEZONE=America/Mexico_City \
  -- npx mcp-loyverse

克劳德桌面版

添加到您的配置文件中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "loyverse": {
      "command": "npx",
      "args": ["mcp-loyverse"],
      "env": {
        "LOYVERSE_API_TOKEN": "your_personal_access_token_here",
        "DEFAULT_TIMEZONE": "America/Mexico_City"
      }
    }
  }
}

其他MCP客户端

任何支持stdio传输的MCP兼容客户端都可以连接。使用命令 npx mcp-loyverse 其中列出了环境变量 配置.

从源代码安装

如果您更喜欢从本地克隆运行：

git clone https://github.com/novigante/mcp-loyverse.git
cd mcp-loyverse
npm install
npm run build

然后使用 node /path/to/mcp-loyverse/dist/index.js 而不是 npx mcp-loyverse 在上述示例中。

验证

问你的AI助手： “运行健康检查工具” --它应该返回服务器状态和配置信息。

配置

变量 必填 默认 描述
LOYVERSE_API_TOKEN 是 -- Loyverse个人访问令牌
LOYVERSE_BASE_URL 没有 https://api.loyverse.com/v1.0 API基本URL
DEFAULT_TIMEZONE 没有 UTC 日期预设的时区（例如。 America/Mexico_City)
LOG_LEVEL 没有 info 日志冗长： debug, info, warn, error
MCP_READ_ONLY 没有 true 只读模式（在v0.1中始终为真）

可用工具

系统

工具 说明
healthcheck 服务器状态、版本和配置检查

资源（CRUD只读）

工具 描述 关键输入
list_receipts 按日期、商店或收据编号搜索收据 period, from/to, store_id, receipt_numbers
get_receipt 获取完整的收据详细信息 receipt_number
list_items 列出目录项 items_ids, limit, cursor
get_item 按ID获取商品详细信息 item_id
list_employees 列出员工（员工、服务员、收银员） employee_ids, limit, cursor
get_employee 按ID获取员工详细信息 employee_id
list_customers 列出客户，可选择按电子邮件筛选 customer_ids, email, limit, cursor
get_customer 按ID获取客户详细信息 customer_id
list_stores 列出所有商店 store_ids, show_deleted
get_store 按ID获取店铺详细信息 store_id
get_merchant 获取商家资料和货币设置 （无）

分析（高级，自动分页）

工具 描述 关键输入
sales_summary 收入、收据计数、平均门票、税费、小费 period, from/to, store_id
top_selling_items 按数量或销售额排名的前几项 period, metric, limit
top_employees_by_sales 按销售额或收货数量排名靠前的员工（解析姓名） period, metric, limit

示例提示

  • “今天的总销售额是多少？”
  • “给我看看本周最畅销的5件商品”
  • “本月哪位员工的销售额最高？”
  • “列出昨天的所有收据”
  • “获取收据编号R-1234的详细信息”
  • “本周的平均门票金额是多少？”
  • “商家使用什么货币？”

建筑

src/
  config/         Configuration (env validation, secrets, logger)
  loyverse/       HTTP client, API error handling, resource clients
  domain/         Analytics: pure aggregation functions, receipt collector
  tools/          MCP tool definitions and handlers
    _shared/      Date range helpers, pagination, result builders
  mcp/            MCP server setup and tool registry
  index.ts        Entry point (stdio transport)

每个工具导出 { definition, handler }The toolRegistry.ts 将定义连接到MCP服务器。分析工具将收据收集器（自动分页）与纯聚合功能组合在一起。

安全

  • 只读 -仅向Loyverse API发送HTTP GET请求
  • 令牌保护 -API令牌从不出现在日志、错误消息或工具响应中
  • 秘密编辑 --结构化日志数据会自动进行清理
  • 本地优先 --通过stdio传输在您的机器上运行；无外部服务器或网络暴露

限制（v0.1）

  • 只读 --不创建、更新或删除资源
  • 仅限PAT --没有OAuth流；需要个人访问令牌
  • 仅限stdio --无HTTP/SSE传输（专为本地MCP客户端设计）
  • 无缓存 -每个工具调用都从API获取新数据
  • 分析限制 --每次查询最多10000张收据；最大90天日期范围

路线图

  • [x] 发布到npm(npx mcp-loyverse)
  • []编写工具（创建/更新项目、客户）
  • []OAuth 2.0身份验证流程
  • []用于远程部署的HTTP/SSE传输
  • []使用TTL进行响应缓存
  • []Webhook支持实时更新
  • []库存和库存水平工具

测试

单元测试

npm test                   # 194 tests (Vitest)
npm run test:watch         # Watch mode
npx vitest run tests/tools/salesSummary.test.ts  # Single file

集成测试

端到端测试，通过MCP协议（stdio传输）针对现场Loyverse API使用所有15种工具。验证连接、资源读取、分析、跨数据一致性、错误处理和分页。

先决条件： 一 .env 文件具有有效 LOYVERSE_API_TOKEN.

cp .env.example .env
# Edit .env — set your real LOYVERSE_API_TOKEN
npm run build
node tests/integration/run-integration.mjs

该脚本作为MCP客户端连接，运行 6个阶段的40次测试，并将原始结果写入 tests/integration/results.json.

阶段 测试 它验证了什么
1.连接 2 健康检查、商家身份验证
2.资源 13 列出/获取所有6个实体，筛选器
3.分析 7 销售摘要、主要项目、主要员工
4.交叉验证 5 工具之间的数据一致性
5.错误处理 9 ID无效、缺少参数、服务器稳定性
6.分页 4 每个资源基于光标的分页

看 docs/integration-test-plan.md 了解详细的验证标准。

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/my-feature)
  3. 先写测试（TDD）-- npm test
  4. 实施您的更改
  5. 在本地运行集成测试（需要您自己的 LOYVERSE_API_TOKEN)
  6. 验证： npm run build && npm test && npm run lint
  7. 提交拉取请求——合并前必须通过CI

释放

发布通过GitHub Actions自动发布到npm。只有存储库维护人员可以创建版本。

  1. 将所有所需更改合并到 main 通过PR
  2. 更新中的版本 package.json (npm version patch|minor|major)并通过PR合并
  3. 创建GitHub版本 带标签 vX.Y.Z 匹配 package.json
  4. 工作流构建、测试并发布到npm 来源

许可证

阿帕奇-2.0

相关 MCP