StashDog MCP Server

Um servidor que fornece ferramentas de linguagem

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP StashDog

Um servidor Model Context Protocol (MCP) que fornece ferramentas de linguagem natural para gerenciar seu inventário StashDog. Este servidor permite que assistentes de IA interajam com seu inventário StashDog por meio de comandos intuitivos em linguagem natural.

🚀 Recursos

  • Interface de Linguagem Natural: Use inglês simples para gerenciar seu inventário
  • Gerenciamento Abrangente de Itens: Adicione, atualize, pesquise, exclua e organize itens
  • Gerenciamento de Coleções: Crie e gerencie coleções com facilidade
  • Busca Inteligente: Pesquisa inteligente em todo o seu inventário com consultas complexas
  • Gerenciamento de Tags: Crie, renomeie e organize tags
  • Importação por URL: Importe itens diretamente de URLs
  • Autenticação: Autenticação segura com sua conta StashDog
  • Formatação Rica: Respostas bonitas e formatadas com emojis e dados estruturados

🛠️ Instalação

  1. Clone ou baixe este servidor MCP para sua máquina local:

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

  2. Instale as dependências:

    npm install

  3. Compile o servidor:

    npm run build

  4. Configure as variáveis de ambiente:

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

⚙️ Configuração

Variáveis de Ambiente

Crie um arquivo .env no diretório raiz:

# 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 usa apenas tokens de acesso de usuário para requisições. Não forneça uma chave de função de serviço.

Configuração do Cliente MCP

Adicione este servidor à sua configuração de cliente MCP .cursor/mcp.json ou 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"
      }
    }
  }
}

🔧 Ferramentas Disponíveis

1. authenticate

Autentique-se com sua conta StashDog.

Exemplo:

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

2. manage_inventory_items

Adicione, atualize, pesquise, exclua ou gerencie itens de inventário usando linguagem natural.

Exemplos:

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

Crie, atualize, exclua coleções ou gerencie itens dentro de coleções.

Exemplos:

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

Importe itens de URLs (páginas de produtos, imagens, etc.).

Exemplo:

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

5. manage_tags

Crie, pesquise, renomeie ou exclua tags.

Exemplos:

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

6. get_inventory_stats

Obtenha estatísticas sobre seu inventário.

Exemplo:

get_inventory_stats

7. smart_search

Realize buscas inteligentes com consultas em linguagem natural.

Exemplos:

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

8. manage_users

Busque detalhes do usuário.

Exemplo:

manage_users with userId: abc123

9. manage_notifications

Busque notificações do usuário.

Exemplos:

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

10. manage_groups

Busque grupos do usuário.

Exemplo:

manage_groups

11. manage_subscriptions

Gerencie assinaturas, incluindo busca de detalhes e criação de assinaturas.

Exemplos:

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

📝 Exemplos de Uso

Adicionando Itens

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

Pesquisando Itens

Find all items tagged with electronics that are in storage containers

Gerenciando Coleções

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

Operações Complexas

Search for items with tags kitchen, appliances limit 10

🎯 Análise de Linguagem Natural

O servidor inclui análise sofisticada de linguagem natural que entende:

  • Ações: adicionar, criar, atualizar, modificar, excluir, remover, pesquisar, encontrar, favoritar, etc.
  • Tags: Suporta o formato #hashtag e listas separadas por vírgulas
  • IDs de Itens: Detecta automaticamente UUIDs em vários formatos
  • Campos Personalizados: Analisa padrões field_name: value
  • Indicadores de Armazenamento: Reconhece palavras-chave de armazenamento/contêiner
  • Aspas: Lida com nomes e descrições entre aspas
  • Limites e Deslocamentos: Entende palavras-chave de paginação

🔐 Autenticação

O servidor suporta múltiplos métodos de autenticação:

  1. Token de Ambiente: Defina STASHDOG_AUTH_TOKEN no seu ambiente
  2. Autenticação em Tempo de Execução: Use a ferramenta authenticate para fazer login
  3. Login Automático: Configure STASHDOG_EMAIL e STASHDOG_PASSWORD para autenticação automática

📊 Formato de Resposta

Todas as respostas seguem um formato consistente:

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

🐛 Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para cenários comuns:

  • Parâmetros obrigatórios ausentes
  • Falhas de autenticação
  • Problemas de conectividade de rede
  • Erros REST do Supabase
  • Erros de validação

📁 Estrutura do Projeto

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

🚀 Desenvolvimento

Executando em Modo de Desenvolvimento

npm run dev

Compilação

npm run build

Testes

npm test

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes se aplicável
  5. Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Suporte

Se você encontrar algum problema:

  1. Verifique se sua API StashDog está em execução e acessível
  2. Verifique suas credenciais de autenticação
  3. Verifique os logs do servidor para mensagens de erro detalhadas
  4. Certifique-se de que todas as dependências estejam instaladas corretamente

🎉 Exemplos em Ação

Exemplo de Fluxo de Trabalho 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 torna o gerenciamento do seu inventário StashDog tão fácil quanto conversar com um assistente de IA!