关键词

库存管理AI代理集成Homebox物品追踪智能自动化

项目简介

Homebox MCP 是一个基于Model Context Protocol (MCP) 的服务器实现，旨在作为AI代理与您的自托管Homebox库存管理系统之间的适配层。它将Homebox的功能以标准化的MCP形式暴露给AI客户端，使得AI能够通过统一的接口读取库存上下文（资源）、执行预定义的工作流（提示）并执行操作（工具），从而高效地管理您的物品清单。

主要功能点

  • 资源提供: 发布Homebox中的数据作为只读上下文，供AI代理浏览和引用。例如，您可以查询所有地点列表（'homebox://locations'）、特定地点的物品清单（'homebox://items?location={id}'）或单个物品的详细信息（'homebox://item/{id}'）。这有助于AI代理获取真实世界的上下文信息，提高决策准确性。
  • 提示模板: 提供预设的、参数化的工作流模板，指导AI代理执行复杂的库存操作。例如，“入库物品”（'inventory-intake'）提示会引导AI完成物品的创建或更新流程，“移动物品”（'move-item'）提示用于将物品从一个地点移动到另一个地点。这些提示确保了AI交互的一致性和低摩擦。
  • 工具调用: 暴露简洁、AI友好的操作接口，允许AI代理执行实际的库存修改。例如，'search_items' 用于查找物品，'upsert_item' 用于创建或合并物品，'update_item' 用于修改物品字段，'move_item' 用于重新定位物品，'resolve_location' 用于将文本地点映射到ID。
  • 可靠性: 结合JSON Schema和行为说明，旨在提高LLM调用的可靠性，减少AI代理的“幻觉”现象，确保操作的准确性。

安装步骤

本仓库提供了Homebox MCP服务器的实现，您可以按照以下通用步骤进行安装和运行：

  1. 准备Python环境: 确保您的系统上已安装Python 3。

  2. 获取项目代码: 从GitHub克隆 'homebox-mcp' 仓库到您的本地机器。

    git clone https://github.com/findusl/homebox-mcp.git
cd homebox-mcp

  3. 安装依赖: 进入项目目录后，通常需要安装项目所需的Python库。请查找项目中的 'requirements.txt' 文件并执行安装：

    pip install -r requirements.txt

  4. 配置Homebox连接: 在启动MCP服务器之前，您需要配置它如何连接到您的自托管Homebox实例。通常通过设置环境变量来完成：

    • 'HOMEBOX_BASE_URL': 您的Homebox实例的完整基础URL（例如：'http://localhost:8080' 或 'https://your-homebox.com'）。
    • 'HOMEBOX_API_TOKEN': 用于认证的Homebox API令牌。您可以在Homebox设置中生成此令牌。

    例如（在Linux/macOS上）：

    export HOMEBOX_BASE_URL="http://localhost:8080"
export HOMEBOX_API_TOKEN="YOUR_API_TOKEN_HERE"

  5. 启动MCP服务器: 服务器启动命令取决于具体的实现。一个常见的Python项目启动方式是：

    python -m homebox_mcp.server # 这是一个示例命令，具体请查阅项目文档

    服务器启动后，它将监听来自MCP客户端的连接。

服务器配置

MCP客户端需要配置此服务器以建立连接。以下是一个示例JSON配置，您需要根据实际部署情况替换 'command' 和 'args'。

{
  "server_name": "HomeboxInventory",
  "command": ["python", "-m", "homebox_mcp.server"],
  "args": [],
  "description": "连接到自托管Homebox的MCP服务器，用于智能管理物品库存。",
  "capabilities": {
    "resources": [
      "homebox://locations",
      "homebox://items?location={id}",
      "homebox://item/{id}"
    ],
    "prompts": [
      "inventory-intake",
      "move-item",
      "quantity-adjust"
    ],
    "tools": [
      "search_items",
      "upsert_item",
      "update_item",
      "move_item",
      "resolve_location"
    ]
  }
}

配置说明:

  • 'server_name': 服务器在MCP客户端中显示的友好名称，方便用户识别。
  • 'command': 一个字符串数组，定义了MCP客户端如何启动此MCP服务器进程的命令。例如 '["python", "-m", "homebox_mcp.server"]'。请根据您实际的服务器启动脚本和路径进行调整。
  • 'args': 一个字符串数组，包含传递给 'command' 的额外命令行参数。通常可以留空，或用于指定日志级别等。
  • 'description': 服务器功能的简要描述，帮助用户了解其用途。
  • 'capabilities': 服务器提供的MCP能力清单，包括可用的资源URI模板、提示名称和工具名称。MCP客户端会利用这些信息向用户展示服务器的功能。

基本使用方法

一旦Homebox MCP服务器成功运行并被您的MCP客户端（例如Claude Desktop或您自定义的AI代理）连接后，AI代理就可以开始与Homebox进行交互：

  1. 浏览库存上下文: AI代理可以读取 'homebox://locations' 资源来获取所有存储地点，或查询 'homebox://items?location={id}' 获取特定地点的物品清单。这些上下文信息可用于辅助AI做出更明智的决策。
  2. 执行预定义工作流: AI代理可以调用如 'inventory-intake'、'move-item' 或 'quantity-adjust' 等提示。例如，当您想添加新物品时，可以触发 'inventory-intake' 提示，AI将通过一系列步骤引导您完成物品的入库或更新过程。
  3. 执行精确操作: AI代理可以通过调用 'upsert_item'、'move_item' 等工具来执行具体的库存修改操作。这些工具提供了对Homebox功能的直接访问。

通过这种方式，AI代理能够以结构化、可靠的方式与您的Homebox系统交互，从而实现库存管理的自动化和智能化。

信息

分类

商业系统

访问项目