veyra-contacts

Una herramienta MCP de gestión de contactos para agentes de IA. Almacena y consulta nombres, correos electrónicos, números de teléfono y empresas. Los datos de contacto son críticos para el negocio: todas las operaciones de escritura son de Clase B y requieren autorización del modo de confirmación de Veyra.

Descripción general

veyra-contacts proporciona a los agentes de IA una base de datos de contactos persistente respaldada por SQLite. Las lecturas son gratuitas. Todas las mutaciones (crear, actualizar, eliminar) son de Clase B (0,02 €) porque los datos de contacto son críticos para el negocio y deben protegerse contra escrituras accidentales.

Instalación

npm install
npm run build

Los datos se almacenan en ~/.veyra-contacts/data.db, que se crea automáticamente en la primera ejecución.

Configuración de MCP (Claude Desktop)

{
  "mcpServers": {
    "veyra-contacts": {
      "command": "node",
      "args": ["/absolute/path/to/veyra-contacts/dist/index.js"]
    }
  }
}

Herramientas

Todas las escrituras son de Clase B porque los datos de contacto son críticos para el negocio.

Ejemplos

Lectura (no se necesita token)

// List all contacts
{ "tool": "list_contacts", "arguments": {} }

// Filter by company
{ "tool": "list_contacts", "arguments": { "company": "Acme Corp" } }

// Search across name, email, company, tags
{ "tool": "search_contacts", "arguments": { "query": "alice" } }

// Get a specific contact
{ "tool": "get_contact", "arguments": { "id": "1712345678-abc1234" } }

Escritura (se requiere token de Veyra: Clase B)

// Create a contact
{
  "tool": "create_contact",
  "arguments": {
    "name": "Alice Müller",
    "email": "alice@example.com",
    "phone": "+49 123 456789",
    "company": "Acme Corp",
    "tags": "customer,vip",
    "veyra_token": "vt_..."
  }
}

// Update a contact
{
  "tool": "update_contact",
  "arguments": {
    "id": "1712345678-abc1234",
    "email": "alice.new@example.com",
    "veyra_token": "vt_..."
  }
}

// Delete a contact
{
  "tool": "delete_contact",
  "arguments": { "id": "1712345678-abc1234", "veyra_token": "vt_..." }
}

Respuesta de error cuando falta el token

{
  "error": "VeyraCommitRequired",
  "message": "Write operations require Veyra commit mode.",
  "currentMode": "open",
  "requiredMode": "commit",
  "authorize_endpoint": "https://api.veyra.to/v1/authorize-action",
  "docs_url": "https://veyra.to"
}

Cómo funciona Veyra

Veyra es una capa de autorización en modo de confirmación para agentes de IA. Cuando un agente intenta una escritura:

1. El agente llama a la herramienta sin veyra_token → recibe VeyraCommitRequired con authorize_endpoint.

2. El agente/usuario llama al punto final de autorización para obtener un token.

3. El agente vuelve a intentarlo con veyra_token configurado.

4. veyra-contacts verifica el token a través de @veyrahq/sdk-node antes de ejecutar la acción.

Consulta veyra.to para obtener la documentación completa.

Licencia

MIT