veyra-contacts

Ein MCP-Tool zur Kontaktverwaltung für KI-Agenten. Speichern und abfragen von Namen, E-Mails, Telefonnummern und Unternehmen. Kontaktdaten sind geschäftskritisch – alle Schreibvorgänge sind Klasse B und erfordern eine Autorisierung über den Veyra Commit-Modus.

Übersicht

veyra-contacts stellt KI-Agenten eine persistente Kontaktdatenbank auf Basis von SQLite zur Verfügung. Lesezugriffe sind kostenlos. Alle Änderungen (Erstellen, Aktualisieren, Löschen) sind Klasse B (€0,02), da Kontaktdaten geschäftskritisch sind und vor versehentlichen Schreibvorgängen geschützt werden müssen.

Installation

npm install
npm run build

Die Daten werden unter ~/.veyra-contacts/data.db gespeichert und beim ersten Start automatisch erstellt.

MCP-Konfiguration (Claude Desktop)

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

Tools

Alle Schreibvorgänge sind Klasse B, da Kontaktdaten geschäftskritisch sind.

Beispiele

Lesen (kein Token erforderlich)

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

Schreiben (Veyra-Token erforderlich – Klasse 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_..." }
}

Fehlerantwort bei fehlendem 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"
}

Funktionsweise von Veyra

Veyra ist eine Autorisierungsschicht für den Commit-Modus bei KI-Agenten. Wenn ein Agent einen Schreibvorgang versucht:

1. Der Agent ruft das Tool ohne veyra_token auf → erhält VeyraCommitRequired mit authorize_endpoint.

2. Der Agent/Benutzer ruft den Autorisierungs-Endpunkt auf, um ein Token zu erhalten.

3. Der Agent wiederholt den Vorgang mit gesetztem veyra_token.

4. veyra-contacts verifiziert das Token über @veyrahq/sdk-node, bevor die Aktion ausgeführt wird.

Siehe veyra.to für die vollständige Dokumentation.

Lizenz

MIT