StashDog MCP Server

StashDog MCP服务器

一个模型上下文协议（MCP）服务器，提供用于管理StashDog库存的自然语言工具。该服务器使AI助手能够通过直观的自然语言命令与您的StashDog库存进行交互。

🚀 特性

• 自然语言接口：用简单的英语管理你的库存
• 综合项目管理：添加、更新、搜索、删除和组织项目
• 收集管理：轻松创建和管理收藏
• 智能搜索：通过复杂查询在库存中进行智能搜索
• 标签管理：创建、重命名和组织标记
• URL导入：直接从URL导入项目
• 认证：使用您的StashDog帐户进行安全身份验证
• 丰富的格式：带有表情符号和结构化数据的漂亮、格式化的回复

🛠️ 安装

1. 克隆或下载 将此MCP服务器连接到您的本地计算机：

   git clone 
   cd stashdog-mcp-server

1. 安装依赖项:

   npm install

1. 构建服务器:

   npm run build

1. 配置环境变量:

   cp .env.example .env
   # Edit .env with your StashDog API configuration

⚙️ 配置

环境变量

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

# StashDog Supabase Configuration
STASHDOG_SUPABASE_URL=http://localhost:54321
STASHDOG_SUPABASE_ANON_KEY=your_anon_key_here
STASHDOG_AUTH_TOKEN=your_auth_token_here

# Optional: Pre-configured credentials
STASHDOG_EMAIL=your_email@example.com
STASHDOG_PASSWORD=your_password

此服务器仅对请求使用用户访问令牌。不提供服务角色密钥。

MCP客户端配置

将此服务器添加到您的 .cursor/mcp.json 或类似的MCP客户端配置：

{
  "mcpServers": {
    "stashdog": {
      "command": "node",
      "args": ["/path/to/stashdog-mcp-server/dist/index.js"],
      "env": {
        "STASHDOG_SUPABASE_URL": "http://localhost:54321",
        "STASHDOG_SUPABASE_ANON_KEY": "your_anon_key_here",
        "STASHDOG_AUTH_TOKEN": "your_token_here"
      }
    }
  }
}

🔧 可用工具

1. authenticate

使用您的StashDog帐户进行身份验证。

例子：

authenticate with email: user@example.com and password: mypassword

2. manage_inventory_items

使用自然语言添加、更新、搜索、删除或管理库存项目。

示例：

• "Add a new MacBook Pro with tags electronics, work, expensive"
• "Search for items tagged with kitchen"
• "Update item abc123 to add note about warranty expiring soon"
• "Delete item xyz789"
• "Find all storage containers"
• "Add item called 'Wireless Mouse' with notes 'Logitech MX Master 3' and tags office, electronics"

3. manage_collections

创建、更新、删除集合或管理集合中的项目。

示例：

• "Create a new collection called 'Kitchen Appliances'"
• "Add items abc123, def456 to collection xyz789"
• "Delete collection old-stuff"
• "Update collection xyz789 to change name to 'Home Office'"

4. import_from_url

从URL（产品页面、图像等）导入项目。

例子：

import_from_url: https://example.com/product/laptop

5. manage_tags

创建、搜索、重命名或删除标签。

示例：

• "Create tag electronics"
• "Search for tags containing kitchen"
• "Rename tag old-name to new-name"
• "Delete tag unused-tag"

6. get_inventory_stats

获取您的库存统计数据。

例子：

get_inventory_stats

7. smart_search

使用自然语言查询执行智能搜索。

示例：

• "Show me all electronics in the office"
• "Find kitchen items that are favorited"
• "List storage containers with more than 5 items"

8. manage_users

获取用户详细信息。

例子：

manage_users with userId: abc123

9. manage_notifications

获取用户通知。

示例：

• "Fetch all unread notifications"
• "Get notifications with a limit of 10"

10. manage_groups

获取用户组。

例子：

manage_groups

11. manage_subscriptions

管理订阅，包括获取详细信息和创建订阅。

示例：

• "Get subscription details for US in USD"
• "Create a subscription with tier PREMIUM"

📝 使用示例

添加项目

Add a new item called "Gaming Keyboard" with notes "Mechanical switches, RGB lighting" and tags gaming, electronics, desk-setup

搜索项目

Find all items tagged with electronics that are in storage containers

管理收藏

Create a new collection called "Home Office Setup" with description "Everything needed for working from home"

复杂操作

Search for items with tags kitchen, appliances limit 10

🎯 自然语言解析

该服务器包括复杂的自然语言解析，可以理解：

• 行动：添加、创建、更新、修改、删除、删除、搜索、查找、收藏等。
• 标签：支持 #hashtag 格式和逗号分隔列表
• 项目ID：自动检测各种格式的UUID
• 自定义字段：解析 field_name: value 模式
• 存储指示器：识别存储/容器关键字
• 语录：处理引用的名称和描述
• 限制和偏移：了解分页关键字

🔐 认证

服务器支持多种身份验证方法：

1. 环境令牌：设置 STASHDOG_AUTH_TOKEN 在您的环境中
2. 运行时身份验证：使用 authenticate 登录工具
3. 自动登录：配置 STASHDOG_EMAIL 和 STASHDOG_PASSWORD 用于自动身份验证

📊 响应格式

所有回复均遵循一致的格式：

{
  "success": true,
  "message": "✅ Successfully added item 'Gaming Keyboard' with ID: abc123",
  "data": {
    "id": "abc123",
    "name": "Gaming Keyboard",
    "tags": ["gaming", "electronics", "desk-setup"]
  }
}

🐛 错误处理

服务器为常见场景提供详细的错误消息：

• 缺少必要参数
• 身份验证失败
• 网络连接问题
• 掩盖REST错误
• 验证错误

📁 项目结构

stashdog-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── client.ts             # Supabase REST client wrapper
│   ├── types.ts              # TypeScript types
│   ├── nlp-utils.ts          # Natural language processing
│   └── graphql/
│       └── operations.ts     # Legacy GraphQL queries (unused)
├── dist/                     # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🚀 发展

以开发模式运行

npm run dev

建筑

npm run build

测试

npm test

🤝 贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🆘 支持

如果您遇到任何问题：

1. 检查StashDog API是否正在运行并可访问
2. 验证您的身份验证凭据
3. 检查服务器日志以获取详细的错误消息
4. 确保所有依赖项都已正确安装

🎉 实例在行动

完整工作流示例

# Authenticate
authenticate with email: user@example.com and password: mypassword

# Add some items
Add a new MacBook Pro with tags electronics, work, laptop and notes "16-inch, M2 chip, 32GB RAM"

# Create a collection
Create a new collection called "Work Equipment" with description "All items for remote work"

# Search for items
Find all items tagged with electronics

# Get stats
get_inventory_stats

# Import from URL
import_from_url: https://example.com/product/wireless-mouse

# Smart search
Show me all work-related items that are favorited

此MCP服务器使管理您的StashDog库存变得像与AI助手对话一样简单！