ConsignCloud MCP Server

ConsignCloud MCP服务器

ConsignCloud API的模型上下文协议（MCP）服务器，使人工智能助手能够管理您的托运/零售业务中的库存、销售、账户等。

🚀 快速入门： 这个项目的新手？看 快速启动.md 5分钟后开始跑步！

📚 文档

• 快速启动.md -5分钟后起床跑步
• 测试.md -使用MCP检查员进行测试
• CLAUDE_DESKTOP_SETUP.md -与Claude Desktop集成
• 收货人_API_SUMMARY.md -完整的API参考
• 项目\_ SUMMARY.md -技术概述

特性

此MCP服务器提供以下工具：

库存管理

• 列出、创建、更新和删除项目
• 按价格、类别、帐户、状态、位置筛选项目
• 获取库存统计信息
• 批量编辑项目
• 更新项目状态

销售管理

• 列出并查看销售额
• 无效和退款销售
• 按日期、客户、地点、状态过滤销售
• 获取销售趋势和分析

账户管理

• 管理供应商/发货人账户
• 查看账户余额和统计数据
• 跟踪每个帐户的购买和项目

附加功能

• 管理项目类别
• 管理店铺位置
• 创建和管理批量项目
• 跨实体搜索和建议

安装

1. 克隆此存储库：

git clone 
cd mcp-consigncloud

1. 安装依赖项：

npm install

1. 创建一个 .env 使用您的ConsignCloud API凭证提交：

cp .env.example .env

1. 编辑 .env 并添加您的API密钥：

CONSIGNCLOUD_API_KEY=your_api_key_here
CONSIGNCLOUD_API_BASE_URL=https://api.consigncloud.com/api/v1

获取API密钥

1. 登录您的ConsignCloud帐户
2. 导航至 设置→ Apps
3. 启用 API和Webhooks 应用
4. 点击 添加API密钥
5. 将生成的API密钥复制到 .env 文件

用法

服务器支持两种模式：

1.STDIO模式（适用于克劳德桌面）

这是与Claude Desktop和其他MCP客户端集成的默认模式。

发展：

npm run dev

生产：

npm run build
npm start

2.HTTP/SSE模式（用于使用MCP检查器进行测试）

此模式运行带有服务器发送事件的HTTP服务器，以便于测试。

发展：

npm run dev:http

生产：

npm run build
npm run start:http

使用自定义配置（CLI标志覆盖环境变量）：

node dist/http-server.js --api-key YOUR_KEY --port 3001 --host localhost

使用绝对路径：

/opt/homebrew/bin/node /absolute/path/to/dist/http-server.js --api-key YOUR_KEY

服务器将在上运行 http://localhost:3000 （可通过以下方式配置 .env 或CLI标志）。

MCP检验员测试

看 测试.md 有关MCP检验员测试的详细说明。

快速启动：

# Option 1: HTTP/SSE mode
# Terminal 1: Start the HTTP server
npm run start:http

# Terminal 2: Launch MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/sse

# Option 2: stdio mode (uses .env file)
npx @modelcontextprotocol/inspector node /absolute/path/to/dist/index.js

# Option 3: stdio mode with environment variable
CONSIGNCLOUD_API_KEY=your_key npx @modelcontextprotocol/inspector node dist/index.js

与Claude Desktop一起使用

将此添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

建议：使用.env文件

{
  "mcpServers": {
    "consigncloud": {
      "command": "node",
      "args": ["/Users/administrators/Documents/Workspace/github/mcp-consigncloud/dist/index.js"]
    }
  }
}

替代方案：内联环境变量

{
  "mcpServers": {
    "consigncloud": {
      "command": "node",
      "args": ["/Users/administrators/Documents/Workspace/github/mcp-consigncloud/dist/index.js"],
      "env": {
        "CONSIGNCLOUD_API_KEY": "your_api_key_here"
      }
    }
  }
}

看 CLAUDE_DESKTOP_SETUP.md 有关详细的设置说明。

可用工具

库存工具

• list_items -使用筛选器列出库存项目
• get_item -获取特定商品详细信息
• create_item -创建新库存项目
• update_item -更新现有项目
• delete_item -删除（软删除）项目
• get_item_stats -获取库存统计信息

销售工具

• list_sales -使用筛选器列出销售额
• get_sale -获取具体销售详情
• void_sale -取消销售
• get_sales_trends -获取销售分析

帐户工具

• list_accounts -列出供应商/发货人账户
• get_account -获取特定帐户详细信息
• create_account -创建新帐户
• update_account -更新现有帐户
• get_account_stats -获取帐户统计信息

类别和位置工具

• list_categories -列出项目类别
• create_category -创建新类别
• list_locations -列出店铺位置

批处理工具

• list_batches -列出项目批次
• create_batch -创建新批次
• update_batch_status -更改批次状态

实用工具

• search_suggest -跨实体搜索

示例提示

使用Claude Desktop配置后，您可以使用以下提示：

• “列出50美元以下的所有库存物品”
• “显示上周的销售额”
• “为John Doe创建新的供应商帐户”
• “最畅销的商品是什么？”
• “显示账户ABC123的当前余额”
• “为供应商XYZ创建新批次”

API文档

有关API的详细文档，请参阅 收货人_API_SUMMARY.md

货币格式

所有货币金额均为最小面额（美元为美分）：

• 10美元=1000美分
• 0.50美元=50美分

速率限制

ConsignCloud API使用漏桶算法：

• 桶容量：100个请求
• 泄漏率：10次请求/秒
• 超过限制返回429状态

发展

项目结构

mcp-consigncloud/
├── src/
│   ├── index.ts        # MCP server implementation
│   ├── client.ts       # ConsignCloud API client
│   └── types.ts        # TypeScript type definitions
├── dist/               # Compiled JavaScript (generated)
├── .env.example        # Environment variable template
├── package.json
├── tsconfig.json
└── README.md

建筑

npm run build

观看模式

npm run watch

故障排除

API关键问题

如果您遇到身份验证错误：

1. 在中验证您的API密钥是否正确 .env
2. 检查在ConsignicCloud中API密钥是否未被撤销
3. 确保在您的ConsignicCloud设置中启用API和Webhooks应用程序

连接问题

如果服务器无法启动：

1. 检查你的 .env 文件存在并且包含有效值
2. 验证网络连接到 api.consigncloud.com
3. HTTP服务器在启动时验证API连接，并显示清楚的错误消息

HTTP/SSE服务器功能

HTTP服务器包括：

• ✅ 启动验证 -在接受请求之前测试API连接
• ✅ CLI参数 -用以下命令覆盖env变量 --api-key, --port, --host
• ✅ 详细错误 -包含HTTP状态代码的全面错误消息
• ✅ 会话管理 -正确处理SSE会话
• ✅ 健康终点 - /health 用于监测
• ✅ 屏蔽测井 -API密钥部分隐藏在日志中

许可证

国际学生委员会

支持

对于ConsignCloud API问题，请联系：team@consigncloud.com 对于MCP服务器问题，请打开GitHub问题。