关键词

Homebox资产管理智能家居库存管理LLM集成

项目简介

Homebox MCP 服务器是一个基于 Model Context Protocol (MCP) 的后端服务，旨在将开源个人资产管理系统 Homebox 的强大功能以标准化的方式提供给大型语言模型 (LLM) 客户端。通过本服务器，LLM 能够直接与您的 Homebox 实例交互，实现对物品、位置和标签的智能管理、查询及自动化操作。

主要功能点

  • 物品管理: 提供对 Homebox 物品的全面管理能力，包括创建、检索、更新、删除、复制物品，以及批量导入和导出物品数据。还支持按资产ID查询物品、获取物品路径，并管理自定义字段。
  • 位置管理: 允许创建、检索、更新和删除物品的存放位置，帮助用户有效组织和追踪物品的物理位置。
  • 标签管理: 支持创建、检索、更新和删除自定义标签，用于对物品进行分类和快速检索。
  • 维护日志: 为特定物品添加或查询维护记录，帮助用户跟踪物品的保养历史和计划。
  • 系统操作: 提供 Homebox 系统级的维护和优化操作，例如创建缺失的缩略图、确保物品具有资产ID、处理导入引用、设置主照片以及重置物品时间字段。
  • 信息查询: 获取 Homebox 应用程序的实时状态信息和当前使用的货币设置。
  • 群组管理: 支持创建新的群组邀请。
  • 标签打印: 根据资产、物品或位置ID生成并返回 Base64 编码的标签图像，方便用户进行物理标签打印。

安装步骤

  1. 克隆仓库: 首先，使用 Git 克隆 Homebox-mcp 仓库到您的本地机器： 
    git clone https://github.com/LokiMetaSmith/Homebox-mcp.git
cd Homebox-mcp/homebox-mcp-server
  2. 设置环境变量: 在运行服务器之前，您必须设置两个重要的环境变量 'HOMEBOX_URL' 和 'HOMEBOX_TOKEN'。这些变量告诉 MCP 服务器如何连接到您的 Homebox 实例。
    • 'HOMEBOX_URL': 您的 Homebox 实例的 API 基础地址（例如: 'http://localhost:7777' 或 'https://your.homebox.domain').
    • 'HOMEBOX_TOKEN': 用于认证的 Homebox API Token。您通常可以在 Homebox 应用程序的设置或用户配置中生成此 Token。 您可以在启动服务器命令前直接设置这些变量，或者将它们添加到您的 shell 配置文件（如 '.bashrc'、'.zshrc' 或 '.profile'）中，以便永久生效：
    export HOMEBOX_URL="http://your-homebox-instance:7777" # 替换为您的 Homebox API 地址
export HOMEBOX_TOKEN="your-homebox-api-token"         # 替换为您的 Homebox API Token
  3. 构建并运行: 完成环境变量设置后，您可以使用 Go 编译器构建并运行 MCP 服务器： 
    go build -o homebox-mcp-server main.go
./homebox-mcp-server
    服务器将通过标准输入/输出 (Stdio) 运行，并等待 MCP 客户端的连接和请求。

服务器配置

MCP 客户端需要知道如何启动并与此服务器通信。以下是一个典型的 JSON 格式配置示例，您可以在 MCP 客户端中加载此配置：

{
  "name": "homebox-mcp-server",
  "command": "./homebox-mcp-server",
  "args": [],
  "environment": {
    "HOMEBOX_URL": "http://your-homebox-instance:7777", // 替换为您的 Homebox API 地址
    "HOMEBOX_TOKEN": "your-homebox-api-token"           // 替换为您的 Homebox API Token
  },
  "description": "连接到 Homebox 个人资产管理系统的 MCP 服务器，提供物品、位置和标签管理功能。",
  "tools": [
    {"name": "get_items", "description": "Retrieves all items from the Homebox inventory."},
    {"name": "create_item", "description": "Creates a new item in the Homebox inventory."},
    {"name": "get_item", "description": "Retrieves a single item from the Homebox inventory by its ID."},
    {"name": "update_item", "description": "Updates an existing item in the Homebox inventory."},
    {"name": "delete_item", "description": "Deletes an item from the Homebox inventory."},
    {"name": "duplicate_item", "description": "Duplicates an existing item."},
    {"name": "get_item_path", "description": "Retrieves the path of an item."},
    {"name": "export_items", "description": "Exports all items as a CSV string."},
    {"name": "import_items", "description": "Imports items from a CSV file."},
    {"name": "get_item_fields", "description": "Gets all custom field names."},
    {"name": "get_item_field_values", "description": "Gets all custom field values."},
    {"name": "get_item_by_asset_id", "description": "Retrieves an item by its asset ID."},
    {"name": "get_locations", "description": "Retrieves all locations from the Homebox inventory."},
    {"name": "create_location", "description": "Creates a new location in the Homebox inventory."},
    {"name": "get_location", "description": "Retrieves a single location from the Homebox inventory by its ID."},
    {"name": "update_location", "description": "Updates an existing location in the Homebox inventory."},
    {"name": "delete_location", "description": "Deletes a location from the Homebox inventory."},
    {"name": "get_labels", "description": "Retrieves all labels from the Homebox inventory."},
    {"name": "create_label", "description": "Creates a new label in the Homebox inventory."},
    {"name": "get_label", "description": "Retrieve a single label from the Homebox inventory by its ID."},
    {"name": "update_label", "description": "Updates an existing label in the Homebox inventory."},
    {"name": "delete_label", "description": "Deletes a label from the Homebox inventory."},
    {"name": "get_maintenance_log", "description": "Retrieves the maintenance log for a specific item."},
    {"name": "create_maintenance_entry", "description": "Creates a new maintenance entry for an item."},
    {"name": "create_missing_thumbnails", "description": "Creates thumbnails for items that are missing them."},
    {"name": "ensure_asset_ids", "description": "Ensures all items in the database have an asset ID."},
    {"name": "ensure_import_refs", "description": "Ensures all items in the database have an import ref."},
    {"name": "set_primary_photos", "description": "Sets the first photo of each item as the primary photo."},
    {"name": "zero_item_time_fields", "description": "Resets all item date fields to the beginning of the day."},
    {"name": "get_status", "description": "Gets application status information."},
    {"name": "get_currency", "description": "Gets currency information."},
    {"name": "create_group_invitation", "description": "Creates a new group invitation."},
    {"name": "get_asset_label", "description": "Generates a label for an asset."},
    {"name": "get_item_label", "description": "Generates a label for an item."},
    {"name": "get_location_label", "description": "Generates a label for a location."}
  ]
}

基本使用方法

一旦 MCP 客户端配置并成功连接到 Homebox MCP 服务器，它就可以通过调用服务器注册的各种工具来与 Homebox 系统进行交互。LLM 代理可以根据用户的自然语言指令，智能地选择并执行这些工具。

例如：

  • 如果用户询问“我的库存里有什么？”，LLM 客户端可能会调用 'get_items' 工具，服务器将返回 Homebox 物品列表。
  • 如果用户要求“在厨房位置创建一个名为‘咖啡机’的新物品”，LLM 客户端可能会调用 'create_item' 工具，并提供 'name' 为“咖啡机”，'locationId' 为“厨房”的参数。
  • 用户也可以通过指示来生成物品标签，例如“给我打印ID为 XYZ 的物品标签”，LLM 客户端将调用 'get_item_label' 工具，服务器返回 Base64 编码的图像数据。

通过这种方式，LLM 客户端能够实现对 Homebox 资产的智能查询、管理和自动化。

信息

分类

AI与计算

访问项目