Rohlik MCP Server

Rohlik MCP服务器

增强您最喜欢的LLM购买杂货的能力。

\[！警告\] 此MCP服务器是使用逆向工程Rohlik API进行研究的。它仅供个人使用。

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

支持的服务：

• 🇨🇿 Rohlik.cn -捷克共和国
• 🇩🇪 Knuspr.de -德国
• 🇦🇹 Gurkerl.at -奥地利
• 🇭🇺 Kifli.hu -匈牙利
• 🇷🇴 塞萨莫.ro -罗马尼亚
• 🇮🇹 芝麻.it -意大利（计划中）
• 🇪🇸 塞萨莫.es -西班牙（计划中）

示例LLM提示与Rohlik MCP配合得很好：

🛒 定期购物：

• *将苹果派的配料加入购物车。只有无麸质和预算友好。*
• *或者实际上，我想做南瓜派，而不是苹果派。更换配料。*
• *我的购物车里有什么商品？*
• *将所附购物清单照片中的商品添加到购物车中。*
• *将我在Rohlik中标记为最喜欢的面包添加到我的购物车中。*

🤖 智能购物：

• *“添加我通常订购的早餐项目”*
• *“给我看本周的午餐建议”*
• *“我晚饭通常买什么？”*
• *“我需要零食——建议我通常点什么”*
• *“显示我购买最多的20件商品”*
• *“我可以用Rohlik MCP做什么？”*

📅 规划：

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

📚 文档

刚接触罗利克MCP？ 查看我们的 新手完整指南!

用法

Claude桌面配置

将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区域 ROHLIK_BASE_URL 环境变量：

• 捷克共和国: 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 Premium订阅状态和福利
• 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检查员进行测试
• npm test -运行单元测试
• npm run test:watch -在监视模式下运行测试
• npm run test:coverage -生成测试覆盖率报告

测试

单元测试

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

# Run all tests
npm test

# Run tests in watch mode (development)
npm run test:watch

# Generate coverage report
npm run test:coverage

测试内容：

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

看 测试/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.rohlik.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检验员测试

您可以使用官方的MCP检查器测试MCP服务器(https://modelcontextprotocol.io/legacy/tools/inspector):

npm run inspect

在检查器中，设置ROHLIK_USENAME和ROHLIKPASSWORD envs。

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" 在env部分
3. 检查日志： ~/Library/Logs/Claude/mcp-server-rohlik*.log （macOS）或 %APPDATA%\Claude\logs\mcp-server-rohlik*.log （Windows）
4. 运行API验证程序： npm run validate-api 测试所有端点

“未找到订单历史记录”

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

解决方案： 在使用智能购物功能之前，确保您在Rohlik上至少有一个已完成的订单(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许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• https://github.com/dvejsada/HA-RohlikCZ用于逆向工程的Rohlik.cz API