MCP Loyverse

mcp-loyverse

](https://www.npmjs.com/package/mcp-loyverse)  ](https://nodejs.org/) 

本地第一个只读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助手： *“运行健康检查工具”* --它应该返回服务器状态和配置信息。

配置

可用工具

系统

资源（CRUD只读）

分析（高级，自动分页）

示例提示

• *“今天的总销售额是多少？”*
• *“给我看看本周最畅销的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.

看 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. 带标签 vX.Y.Z 匹配 package.json
4. 工作流构建、测试并发布到npm 来源

许可证

阿帕奇-2.0