partsbox MCP

PartsBox MCP服务器

使用FastMCP的PartsBox API的模型上下文协议（MCP）服务器。该服务器使AI助手能够与您的电子元件PartsBox库存管理系统进行交互。

概述

零件箱 是电子元件的库存管理系统。此MCP服务器提供以下工具：

• 管理零件及其元数据
• 跟踪库存水平和位置
• 处理批次和库存条目
• 管理存储位置
• 处理项目和BOM（物料清单）
• 处理订单并接收库存

需求

• Python 3.10+
• uv包管理器
• PartsBox API密钥（在设置|数据中生成）

设置

1.安装依赖项

uv sync

2.设置环境变量

创建一个 .env 项目根目录中的文件：

PARTSBOX_API_KEY=partsboxapi_your_api_key_here

安全说明： 小心保护API密钥，因为它提供了对PartsBox数据库的完全访问。

环境变量

3.运行服务器

uv run python partsbox_mcp_server.py

API概述

PartsBox API是面向操作的（而非REST），并提供：

零部件管理

• 创建、检索、更新和删除零件
• 管理替代品和元部件
• 处理自定义字段

库存管理

• 添加和删除库存
• 在不同地点之间移动库存
• 更新库存条目
• 按零件或存储位置检索库存

大量

• 获取并更新批次数据
• 跟踪批次信息

存储

• 管理存储位置
• 归档和恢复位置
• 按地点汇总库存

项目

• 创建和管理BOM
• 处理物料清单条目
• 跟踪项目构建

订单

• 创建和管理订单
• 添加订单条目
• 从订单中接收库存
• 管理订单生命周期

可用工具

零件API

API库存

大量API

存储API

API项目

订单API

文件API

MCP资源

资源通过URI模板提供对文件和图像的只读访问：

这 file_id 从零件数据（例如 part/img-id 字段返回 get_part 或 list_parts).

共享资源存储

服务器提供基于资源的文件存储方法(get_image_resource 和 get_file_resource)它允许通过映射的Docker卷与其他MCP服务器共享文件。这对于需要在服务之间传递文件的多容器工作流非常有用。

运作原理

1. 文件从PartsBox下载并存储在共享blob存储目录中
2. 每个文件都有一个唯一的资源标识符（格式： blob://TIMESTAMP-HASH.EXT)
3. 其他MCP服务器可以使用标识符直接从映射的卷访问这些文件
4. 使用SHA256哈希自动对文件进行重复数据消除
5. 文件在可配置的TTL后过期（默认值：24小时）

配置

使用环境变量配置共享存储：

Docker卷设置

要启用MCP服务器之间的资源共享，请装载共享卷：

# docker-compose.yml
version: '3.8'
services:
  partsbox-mcp:
    image: partsbox-mcp:latest
    volumes:
      - blob-storage:/mnt/blob-storage
    environment:
      - PARTSBOX_BLOB_STORAGE_ROOT=/mnt/blob-storage

  other-mcp-server:
    image: other-mcp:latest
    volumes:
      - blob-storage:/mnt/blob-storage

volumes:
  blob-storage:

用法示例

# Store an image in shared storage
response = get_image_resource("img_resistor_10k")
# Returns: ResourceResponse(
#   success=True,
#   resource_id="blob://1733437200-a3f9d8c2b1e4f6a7.png",
#   filename="img_resistor_10k.png",
#   mime_type="image/png",
#   size_bytes=65536,
#   sha256="a3f9d8c2...",
#   expires_at="2024-12-08T12:00:00Z"
# )

# Other MCP servers can now access the file at:
# /mnt/blob-storage/17/33/blob://1733437200-a3f9d8c2b1e4f6a7.png

JMESPath查询支持

所有列表操作都支持用于过滤和投影的JMESPath查询。此服务器通过自定义函数扩展了标准JMESPath，用于安全的null处理和数据转换：

自定义函数

空安全查询

重要： 许多PartsBox字段都可以为空。使用 nvl() 为了防止在筛选这些字段时出错：

# UNSAFE - fails if "part/name" is null
query="[?contains(\"part/name\", 'resistor')]"

# SAFE - handles null values
query="[?contains(nvl(\"part/name\", ''), 'resistor')]"

查询示例

# Search parts by name (null-safe)
query="[?contains(nvl(\"part/name\", ''), 'capacitor')]"

# Filter by manufacturer
query="[?nvl(\"part/manufacturer\", '') == 'Texas Instruments']"

# Combine conditions
query="[?contains(nvl(\"part/name\", ''), 'resistor') && \"stock/total\" > `0`]"

# Sort results
query="sort_by(@, &\"part/name\")"

重要说明

认证

所有API请求都需要在授权标头中传递API密钥：

Authorization: APIKey partsboxapi_[your-key]

时间戳

PartsBox将时间戳存储为64位UNIX UTC时间戳。时区转换是您的责任。

库存计算

PartsBox不存储总库存计数。库存盘点是通过遍历库存历史来计算的。

速率限制

可能会强制执行费率限制。为您的使用计划潜在的速率限制。

API限制

• 无法使用API创建用户界面应用程序（仅限自动化）
• 商业计划用户获得标准支持
• 免费帐户用户不应期望收到电子邮件回复

克劳德集成

此MCP服务器与Claude Desktop和Claude Code（CLI）配合使用。看 使用MCPServer.md 了解详细的配置说明。

相关资源

• PartsBox API文档
• PartsBox网站

开发中

该项目旨在与vscode和devcontainers插件配合使用。我还建议运行claude——在devcontainer中危险地跳过权限一次，以获得最佳结果😁