veyra-contacts

A contact manager MCP tool for AI agents. Store and query names, emails, phone numbers, and companies. Contact data is business-critical — all write operations are Class B and require Veyra commit mode authorization.

Overview

veyra-contacts gives AI agents a persistent contact database backed by SQLite. Reads are free. All mutations (create, update, delete) are Class B (€0.02) because contact data is business-critical and must be protected against accidental writes.

Installation

npm install
npm run build

Data is stored at ~/.veyra-contacts/data.db, created automatically on first run.

MCP Configuration (Claude Desktop)

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

Tools

| Tool | Input | Class | Price | |------|-------|-------|-------| | list_contacts | { tag?, company? } | — | FREE | | get_contact | { id } | — | FREE | | search_contacts | { query } | — | FREE | | create_contact | { name, email?, phone?, company?, tags?, veyra_token? } | B | €0.02 | | update_contact | { id, name?, email?, veyra_token? } | B | €0.02 | | delete_contact | { id, veyra_token? } | B | €0.02 |

All writes are Class B because contact data is business-critical.

Examples

Read (no token needed)

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

Write (Veyra token required — Class B)

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

// Update a contact
{
  "tool": "update_contact",
  "arguments": {
    "id": "1712345678-abc1234",
    "email": "[email protected]",
    "veyra_token": "vt_..."
  }
}

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

Error response when token is missing

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

How Veyra Works

Veyra is a commit-mode authorization layer for AI agents. When an agent attempts a write:

1. The agent calls the tool without veyra_token → receives VeyraCommitRequired with authorize_endpoint.
2. The agent/user calls the authorize endpoint to obtain a token.
3. The agent retries with veyra_token set.
4. veyra-contacts verifies the token via @veyrahq/sdk-node before executing the action.

See veyra.to for full documentation.

License

MIT