星战科技xingzhan.cloud
返回市场
罗赫利克-MCP

罗赫利克-MCP

作者：kolarova-ops2 星标更新：2025-10-11
安装使用来源：spider==github.com

项目介绍

<img src="https://www.rohlik.cz/favicon/cz/favicon.ico" alt="Rohlik" width="30" height="30"> Rohlik MCP 服务器

增强你的喜爱的大语言模型（LLM），使其具备购买杂货的能力。

[!警告] 此 MCP 服务器仅供学习用途，使用了逆向工程的 Rohlik API。仅限个人使用。

这是一个模型上下文协议（MCP）服务器，它使AI助手能够与Rohlik集团在多个国家的在线杂货配送服务进行交互。此服务器提供了搜索产品、管理购物车以及访问账户信息的工具。

支持的服务：

适用于 Rohlik MCP 的示例 LLM 提示：

🛒 日常购物：

  • 将制作苹果派所需的无麸质且经济实惠的原料添加到购物车中。
  • 实际上，我想要做南瓜派而不是苹果派，请更改原料。
  • 我的购物车里有什么？
  • 将附带购物清单照片中的物品添加到购物车中。
  • 将我在 Rohlik 上标记为收藏的面包添加到我的购物车中。

🤖 智能购物：

  • "添加我通常订购的早餐物品"
  • "给我本周午餐建议"
  • "我通常晚餐买什么？"
  • "我需要零食——推荐我通常订购的"
  • "显示我最常购买的前20项商品"
  • "我可以使用 Rohlik MCP 做什么？"

📅 规划：

  • 明天最便宜的送货时段是什么时候？
  • 我的下一次送货是什么时候？
  • 显示我最近的5个订单

📚 文档

新用户？ 查看我们的 新手完全指南！

使用方法

Claude Desktop 配置

将 MCP 添加到 Claude Desktop 配置中：

  • 在 MacOS 中：~/Library/Application Support/Claude/claude_desktop_config.json
  • 在 Windows 中：%APPDATA%/Claude/claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "rohlik": {
      "command": "npx",
      "args": ["-y", "@tomaspavlin/rohlik-mcp"],
      "env": {
        "ROHLIK_USERNAME": "your-email@example.com",
        "ROHLIK_PASSWORD": "your-password",
        "ROHLIK_BASE_URL": "https://www.rohlik.cz"
      }
    }
  }
}

支持的地区

通过设置环境变量 ROHLIK_BASE_URL，服务器支持多个 Rohlik 地区：

  • 捷克共和国：https://www.rohlik.cz（默认）
  • 德国：https://www.knuspr.de
  • 奥地利：https://www.gurkerl.at
  • 匈牙利：https://www.kifli.hu
  • 罗马尼亚：https://www.sezamo.ro
  • 意大利（计划中）：https://www.sezamo.it
  • 西班牙（计划中）：https://www.sezamo.es

如果未指定 ROHLIK_BASE_URL，则默认为捷克版本。

工具

核心购物

  • search_products - 按名称搜索杂货产品，并带有过滤选项
  • add_to_cart - 将多个产品添加到购物车中
  • get_cart_content - 查看当前购物车内容及总计
  • remove_from_cart - 从购物车中移除项目
  • get_shopping_list - 根据ID检索购物清单

🤖 智能购物

  • get_meal_suggestions - 根据您的订单历史记录获得个性化建议，包括早餐、午餐、晚餐、零食、烘焙、饮料或健康饮食
  • get_frequent_items - 分析订单历史记录以找到最常购买的商品（总体+按类别）
  • get_shopping_scenarios - 互动指南展示您可以使用 MCP 完成的操作

获取信息

  • get_account_data - 获取全面的账户信息，包括送货详情、订单、公告、购物车和高级状态
  • get_order_history - 查看您过去的已交付订单及其详细信息
  • get_order_detail - 获取特定订单的详细信息，包括所有产品
  • get_upcoming_orders - 查看您安排的即将送达的订单
  • get_delivery_info - 获取当前的送货信息及费用
  • get_delivery_slots - 查看您地址可用的送货时间槽
  • get_premium_info - 检查您的 Rohlik 高级订阅状态及福利
  • get_announcements - 查看当前的公告和通知
  • get_reusable_bags_info - 跟踪您的可重复使用袋子及其环保影响

开发

安装

npm install
npm run build

脚本

  • npm run build - 编译 TypeScript 到 JavaScript
  • npm start - 启动生产服务器
  • npm run dev - 启动开发模式并监视
  • npm run inspect - 使用 MCP Inspector 测试
  • npm test - 运行单元测试
  • npm run test:watch - 在监视模式下运行测试
  • npm run test:coverage - 生成测试覆盖率报告

测试

单元测试

该项目包含对智能购物数据转换逻辑的单元测试：

# 运行所有测试
npm test

# 在监视模式下运行测试（开发）
npm run test:watch

# 生成覆盖率报告
npm run test:coverage

测试内容：

  • 频率分析算法（get_frequent_items）
  • 餐食建议筛选和排名（get_meal_suggestions）
  • 价格平均和计算
  • 类别筛选和分组
  • 边缘情况（空数据、缺失字段等）

查看 tests/README.md 以获取详细的测试文档。

使用 Claude Desktop 测试

添加到配置中：

{
  "mcpServers": {
    "rohlik-local": {
      "command": "node",
      "args": ["/path/to/rohlik-mcp/dist/index.js"],
      "env": {
        "ROHLIK_USERNAME": "your-email@example.com",
        "ROHLIK_PASSWORD": "your-password",
        "ROHLIK_BASE_URL": "https://www.rorohlik.cz"
      }
    }
  }
}

调试模式

如果您遇到身份验证问题，请启用调试模式以查看详细日志：

{
  "mcpServers": {
    "rohlik-local": {
      "command": "node",
      "args": ["/path/to/rohlik-mcp/dist/index.js"],
      "env": {
        "ROHLIK_USERNAME": "your-email@example.com",
        "ROHLIK_PASSWORD": "your-password",
        "ROHLIK_BASE_URL": "https://www.rohlik.cz",
        "ROHLIK_DEBUG": "true"
      }
    }
  }
}

调试日志将出现在 ~/Library/Logs/Claude/mcp-server-rohlik-local.log（macOS）或 %APPDATA%/Claude/logs/mcp-server-rohlik-local.log（Windows）。

使用 MCP Inspector 测试

您可以使用官方的 MCP Inspector（https://modelcontextprotocol.io/legacy/tools/inspector）来测试 MCP 服务器：

npm run inspect

在 Inspector 中设置 ROHLIK_USERNAME 和 ROHLIK_PASSWORD 环境变量。

API 验证工具

要验证所有 Rohlik API 端点是否正常工作并诊断身份验证问题：

npm run validate-api

这将：

  • 测试 MCP 服务器使用的全部11个API端点
  • 在控制台中显示详细的HTTP请求/响应日志
  • 生成JSON报告：tests/validation-results.json
  • 生成美观的HTML报告：tests/validation-report.html

验证器会自动加载来自您的 Claude Desktop 配置或环境变量的凭据。在浏览器中打开 HTML 报告，以便轻松阅读所有测试的总结。

故障排除

常见问题

"登录失败" 错误

可能原因：

  1. 配置中的用户名/密码错误
  2. Rohlik API 发生变化或暂时不可用
  3. 网络连接问题

解决方案：

  1. 验证 claude_desktop_config.json 中的凭据
  2. 启用调试模式：在环境部分设置 "ROHLIK_DEBUG": "true"
  3. 检查日志：~/Library/Logs/Claude/mcp-server-rohlik*.log（macOS）或 %APPDATA%\Claude\logs\mcp-server-rohlik*.log（Windows）
  4. 运行 API 验证器：npm run validate-api 来测试所有端点

"没有找到订单历史"

原因： 您的账户没有过去的订单，或者订单无法访问

解决方案： 确保您在使用智能购物功能之前至少有一个已完成的订单（get_meal_suggestions，get_frequent_items）

响应时间慢

原因：

  • 分析过多订单（智能购物功能）
  • 到 Rohlik 服务器的网络延迟
  • API 速率限制

解决方案：

  • 对于智能购物：减少分析的订单数量（尝试10个而不是默认的20个）
  • 减少请求次数或在批量操作之间添加延迟
  • 检查您的网络连接

未找到产品或搜索返回无结果

原因：

  • 产品缺货或已停产
  • Rohlik 系统中产品ID发生变化
  • 搜索查询中的拼写错误

解决方案：

  • 按部分名称搜索，而不是完整的产品名称
  • 尝试替代拼写或更广泛的搜索词
  • 直接在 Rohlik 网站上验证产品是否存在

启用调试模式

在配置中添加 ROHLIK_DEBUG 以查看详细日志：

{
  "mcpServers": {
    "rohlik-local": {
      "command": "node",
      "args": ["/path/to/rohlik-mcp/dist/index.js"],
      "env": {
        "ROHLIK_USERNAME": "your-email@example.com",
        "ROHLIK_PASSWORD": "your-password",
        "ROHLIK_BASE_URL": "https://www.rohlik.cz",
        "ROHLIK_DEBUG": "true"
      }
    }
  }
}

查看日志：

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-rohlik-local.log

# Windows
type %APPDATA%\Claude\logs\mcp-server-rohlik-local.log

使用 API 验证工具

如果您遇到身份验证或 API 问题，请运行验证器：

npm run validate-api

这将：

  • 测试 MCP 使用的所有11个API端点
  • 显示详细的HTTP请求/响应信息
  • 生成 validation-results.json 测试结果
  • 创建 validation-report.html 以便在浏览器中轻松查看
  • 帮助识别哪些特定端点失败

作为 NPM 包发布

  1. 更新 package.json 中的版本
  2. npm publish

许可证

本项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

致谢