veyra-bookmarks

A bookmark and link manager MCP tool for AI agents, with tag filtering, categories, and full-text search. Reads are always free. Write operations require Veyra commit mode authorization.

Overview

veyra-bookmarks gives AI agents a persistent link library backed by SQLite. Agents can freely browse and search bookmarks. Saving, updating, and deleting requires Veyra commit mode.

Installation

npm install
npm run build

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

MCP Configuration (Claude Desktop)

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

Tools

| Tool | Input | Class | Price | |------|-------|-------|-------| | list_bookmarks | { tag?, category? } | — | FREE | | get_bookmark | { id } | — | FREE | | search_bookmarks | { query } | — | FREE | | save_bookmark | { url, title?, tags?, category?, veyra_token? } | A | €0.005 | | update_bookmark | { id, tags?, category?, veyra_token? } | A | €0.005 | | delete_bookmark | { id, veyra_token? } | B | €0.02 |

Examples

Read (no token needed)

// List all bookmarks
{ "tool": "list_bookmarks", "arguments": {} }

// Filter by category
{ "tool": "list_bookmarks", "arguments": { "category": "research" } }

// Search by keyword
{ "tool": "search_bookmarks", "arguments": { "query": "typescript" } }

Write (Veyra token required)

// Save a bookmark
{
  "tool": "save_bookmark",
  "arguments": {
    "url": "https://www.typescriptlang.org/docs/",
    "title": "TypeScript Docs",
    "tags": "typescript,docs,reference",
    "category": "development",
    "veyra_token": "vt_..."
  }
}

// Update tags/category
{
  "tool": "update_bookmark",
  "arguments": {
    "id": "1712345678-abc1234",
    "tags": "typescript,docs,pinned",
    "veyra_token": "vt_..."
  }
}

// Delete
{
  "tool": "delete_bookmark",
  "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-bookmarks verifies the token via @veyrahq/sdk-node before executing the action.

See veyra.to for full documentation.

License

MIT