StashDog MCP Server

Un servidor que proporciona herramientas de lenguaje natural para gestionar tu inventario de StashDog.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP StashDog

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas de lenguaje natural para gestionar tu inventario de StashDog. Este servidor permite a los asistentes de IA interactuar con tu inventario de StashDog mediante comandos intuitivos en lenguaje natural.

🚀 Características

  • Interfaz de Lenguaje Natural: Usa inglés sencillo para gestionar tu inventario
  • Gestión Integral de Artículos: Añade, actualiza, busca, elimina y organiza artículos
  • Gestión de Colecciones: Crea y gestiona colecciones con facilidad
  • Búsqueda Inteligente: Búsqueda inteligente en tu inventario con consultas complejas
  • Gestión de Etiquetas: Crea, renombra y organiza etiquetas
  • Importación desde URL: Importa artículos directamente desde URLs
  • Autenticación: Autenticación segura con tu cuenta de StashDog
  • Formato Enriquecido: Respuestas hermosas y formateadas con emojis y datos estructurados

🛠️ Instalación

  1. Clona o descarga este servidor MCP en tu máquina local:

    git clone <repository-url>
cd stashdog-mcp-server

  2. Instala las dependencias:

    npm install

  3. Compila el servidor:

    npm run build

  4. Configura las variables de entorno:

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

⚙️ Configuración

Variables de Entorno

Crea un archivo .env en el directorio raíz:

# 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

Este servidor solo utiliza tokens de acceso de usuario para las solicitudes. No proporciones una clave de rol de servicio.

Configuración del Cliente MCP

Añade este servidor a tu configuración de cliente MCP .cursor/mcp.json o similar:

{
  "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"
      }
    }
  }
}

🔧 Herramientas Disponibles

1. authenticate

Autentícate con tu cuenta de StashDog.

Ejemplo:

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

2. manage_inventory_items

Añade, actualiza, busca, elimina o gestiona artículos del inventario usando lenguaje natural.

Ejemplos:

  • "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

Crea, actualiza, elimina colecciones o gestiona artículos dentro de colecciones.

Ejemplos:

  • "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

Importa artículos desde URLs (páginas de productos, imágenes, etc.).

Ejemplo:

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

5. manage_tags

Crea, busca, renombra o elimina etiquetas.

Ejemplos:

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

6. get_inventory_stats

Obtén estadísticas sobre tu inventario.

Ejemplo:

get_inventory_stats

7. smart_search

Realiza búsquedas inteligentes con consultas en lenguaje natural.

Ejemplos:

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

8. manage_users

Obtén detalles del usuario.

Ejemplo:

manage_users with userId: abc123

9. manage_notifications

Obtén notificaciones del usuario.

Ejemplos:

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

10. manage_groups

Obtén grupos de usuarios.

Ejemplo:

manage_groups

11. manage_subscriptions

Gestiona suscripciones, incluyendo la obtención de detalles y la creación de suscripciones.

Ejemplos:

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

📝 Ejemplos de Uso

Añadir Artículos

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

Buscar Artículos

Find all items tagged with electronics that are in storage containers

Gestionar Colecciones

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

Operaciones Complejas

Search for items with tags kitchen, appliances limit 10

🎯 Análisis de Lenguaje Natural

El servidor incluye un sofisticado análisis de lenguaje natural que comprende:

  • Acciones: añadir, crear, actualizar, modificar, eliminar, quitar, buscar, encontrar, favorito, etc.
  • Etiquetas: Soporta el formato #hashtag y listas separadas por comas
  • IDs de Artículos: Detecta automáticamente UUIDs en varios formatos
  • Campos Personalizados: Analiza patrones field_name: value
  • Indicadores de Almacenamiento: Reconoce palabras clave de almacenamiento/contenedor
  • Comillas: Maneja nombres y descripciones entre comillas
  • Límites y Desplazamientos: Comprende palabras clave de paginación

🔐 Autenticación

El servidor admite múltiples métodos de autenticación:

  1. Token de Entorno: Establece STASHDOG_AUTH_TOKEN en tu entorno
  2. Autenticación en Tiempo de Ejecución: Usa la herramienta authenticate para iniciar sesión
  3. Inicio de Sesión Automático: Configura STASHDOG_EMAIL y STASHDOG_PASSWORD para autenticación automática

📊 Formato de Respuesta

Todas las respuestas siguen un formato consistente:

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

🐛 Manejo de Errores

El servidor proporciona mensajes de error detallados para escenarios comunes:

  • Parámetros requeridos faltantes
  • Fallos de autenticación
  • Problemas de conectividad de red
  • Errores REST de Supabase
  • Errores de validación

📁 Estructura del Proyecto

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

🚀 Desarrollo

Ejecutar en Modo de Desarrollo

npm run dev

Compilación

npm run build

Pruebas

npm test

🤝 Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Añade pruebas si corresponde
  5. Envía una solicitud de extracción

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🆘 Soporte

Si encuentras algún problema:

  1. Verifica que tu API de StashDog esté ejecutándose y sea accesible
  2. Verifica tus credenciales de autenticación
  3. Revisa los registros del servidor para ver mensajes de error detallados
  4. Asegúrate de que todas las dependencias estén instaladas correctamente

🎉 Ejemplos en Acción

Ejemplo de Flujo de Trabajo Completo

# 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

¡Este servidor MCP hace que gestionar tu inventario de StashDog sea tan fácil como tener una conversación con un asistente de IA!