{"_id":"@davazmysel/mcp","_rev":"2-280de5fb4886cf4477e2cb4d2b6215b4","name":"@davazmysel/mcp","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@davazmysel/mcp","version":"1.0.0","_id":"@davazmysel/mcp@1.0.0","maintainers":[{"name":"tuanwdd","email":"tuan.n@whododo.com"}],"bin":{"dava-mcp":"dist/index.js"},"dist":{"shasum":"5b3c193bd29fa76382c0aefa4dc66c7667e2b23b","tarball":"https://registry.npmjs.org/@davazmysel/mcp/-/mcp-1.0.0.tgz","fileCount":6,"integrity":"sha512-Eer36N7VtUCgEOgawl/Pv2lJ8TDUMX3Jy+EpAFY8DU+pEzRqUHG2vv8OCxiS1hXBCaRZ5Jk6JjmRAFDaIJme/g==","signatures":[{"sig":"MEUCIQCotkqailvZxOZphwe0ETzz7/J/xsnl30hddW5wO0fhhgIgIGoZkumpjvVqI49+XOVwLdax0zNwWVyo1sMGtZbBhfY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":16810},"type":"module","engines":{"node":">=18"},"gitHead":"6008cea953a1b57b3403d1656058e088d54dfd46","private":false,"scripts":{"lint":"biome check --write .","test":"vitest run","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"tuanwdd","email":"tuan.n@whododo.com"},"_npmVersion":"11.5.1","description":"An MCP (Model Context Protocol) server that lets AI assistants create and look up tracked marketing links through the Dáva platform.","directories":{},"_nodeVersion":"24.5.0","dependencies":{"zod":"4.3.6","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.6","typescript":"5.9.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1788452775189_0.38035582912357135","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@davazmysel/mcp","version":"1.0.1","private":false,"type":"module","bin":{"dava-mcp":"dist/index.js"},"engines":{"node":">=18"},"scripts":{"start":"node dist/index.js","build":"tsc","typecheck":"tsc --noEmit","lint":"biome check --write .","test":"vitest run"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","zod":"4.3.6"},"devDependencies":{"@types/node":"^22.0.0","typescript":"5.9.3","vitest":"^3.2.6"},"gitHead":"4ce9be506673a3b8b4048a26cebc820058aac308","_id":"@davazmysel/mcp@1.0.1","description":"An MCP (Model Context Protocol) server that lets AI assistants create and look up tracked marketing links through the Dáva platform.","_nodeVersion":"24.20.0","_npmVersion":"11.19.0","dist":{"integrity":"sha512-4BYizL4GZjxtG2stT3n8khXLu5KlMNJZdhTPuW4QcrBnrY6JADQRi+0Wa2BgTOYOsnT1xuE5jbP0BHo3Fl09lw==","shasum":"da2a5de4cc81a9d3c493e8198286c073163e095d","tarball":"https://registry.npmjs.org/@davazmysel/mcp/-/mcp-1.0.1.tgz","fileCount":7,"unpackedSize":17810,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD59v+4zG5tpcTchWflEpOILvc71b4cORE4j7dStSoxKgIgAWgJWDVoRXWecCdTOwIRsDYrIeUMSnMMgdDDhEMfM3A="}]},"_npmUser":{"name":"tuanwdd","email":"tuan.n@whododo.com"},"directories":{},"maintainers":[{"name":"tuanwdd","email":"tuan.n@whododo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_1.0.1_1789094046032_0.14098245459739522"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T16:26:14.925Z","modified":"2026-09-11T02:34:06.332Z","1.0.0":"2026-09-03T16:26:15.353Z","1.0.1":"2026-09-11T02:34:06.170Z"},"description":"An MCP (Model Context Protocol) server that lets AI assistants create and look up tracked marketing links through the Dáva platform.","maintainers":[{"name":"tuanwdd","email":"tuan.n@whododo.com"}],"readme":"# Dáva MCP Server\n\nAn MCP (Model Context Protocol) server that lets AI assistants create and look up\ntracked marketing links through the Dáva platform.\n\n## What it does\n\nThe Dáva MCP server exposes two tools:\n\n- **`create_link`** — mints a governed marketing link by sending the same interview\n  inputs the Dáva dashboard UI accepts. Always attaches an `external_id` so retries\n  are idempotent (a second call with the same key returns the same link, not a\n  duplicate).\n- **`find_link`** — retrieves an existing link by its `external_id`. Returns\n  `found: false` (never throws) when no link matches.\n\n`list_presets` is intentionally not included: link type data is only accessible\nvia the Dáva dashboard using a Supabase session token, not an API key.\n\n---\n\n## Prerequisites\n\n- Node.js 18 or later\n- A Dáva account with at least one domain configured\n- A Dáva API key with **`links`** scope (see [API key provisioning](#api-key-provisioning) below)\n\n---\n\n## Installation\n\nInstall the package into your local MCP server directory:\n\n```bash\nnpm install @davazmysel/mcp\n# or if you use pnpm\npnpm add @davazmysel/mcp\n```\n\nOr run directly with `npx`/`pnpm dlx`:\n\n```bash\nnpx @davazmysel/mcp\n```\n\n---\n\n## Configuration\n\nThe server reads two environment variables at startup:\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `DAVA_API_KEY` | Yes | — | A Dáva API key with `links` scope |\n| `DAVA_API_URL` | No | `https://api-v2.davazmysel.com` | Override for self-hosted or staging |\n\nIf `DAVA_API_KEY` is not set the server exits immediately with an error message.\n\n---\n\n## Claude Desktop setup\n\nAdd the server to your Claude Desktop configuration file\n(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,\n`%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"dava-links\": {\n      \"command\": \"npx\",\n      \"args\": [\"@davazmysel/mcp\"],\n      \"env\": {\n        \"DAVA_API_URL\": \"https://api-v2.davazmysel.com\",\n        \"DAVA_API_KEY\": \"dava_sk_live_<your-key-here>\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving the file. The tools appear automatically\nwhen Claude starts a conversation.\n\n---\n\n## API key provisioning\n\nTo use the MCP server you need a Dáva API key that has the **`links`** scope.\n\n**Steps:**\n\n1. Log in to the Dáva dashboard at [davazmysel.com](https://davazmysel.com).\n2. Navigate to **Settings → API Keys**.\n3. Click **Create API Key**, give it a name (e.g. `Claude MCP – Links`), and\n   choose the environment (`live` for production, `test` for development).\n4. Copy the plaintext key shown on screen — it is displayed **once only**.\n5. Contact the Dáva team to enable the `links` scope on the newly created key.\n   (A self-service scope selector is on the product roadmap; until then, reach\n   out via your account manager or support channel.)\n6. Set the plaintext key as `DAVA_API_KEY` in your Claude Desktop config (see above).\n\nKeys with only the `events` scope (the default) will be rejected with HTTP 403\nwhen calling `create_link` or `find_link`.\n\n---\n\n## Recommended workflow: Dáva first, then Meta\n\nThe MCP server is designed so that **Dáva is the starting point**, not an\nafterthought.\n\n**Correct order:**\n\n1. **Create the link in Dáva first** — call `create_link` with your campaign\n   details and a destination URL. Dáva applies your governance rules and returns\n   an `issued_url` (the tracked link on your customer CNAME).\n2. **Paste the `issued_url` as the ad destination in Meta** — go to Meta Ads\n   Manager, create your ad, and enter the `issued_url` as the destination URL.\n\nThis order ensures that:\n- Every Meta click is tracked through Dáva from day one.\n- Attribution is captured end-to-end (UTM parameters are part of the issued URL).\n- Retries (network errors, agent restarts) use the same `external_id` and never\n  mint a duplicate link.\n\n**Do not start by creating the ad in Meta and then trying to retrofit a Dáva\nlink** — that breaks the attribution chain and requires manually updating the\nad's destination URL.\n\n---\n\n## Usage examples\n\n### Create a link\n\n```\nUse the create_link tool with:\n- link_type_id: \"d5b3c8a1-...\"   (the UUID of the link type / governance recipe)\n- campaign: \"Spring Sale 2025\"\n- destination: \"https://petsy.com.au/spring-sale\"\n- source: \"Meta\"\n- medium: \"Paid Social\"\n- platform: \"Meta Ads\"\n- stamp_utms: true   (optional — default true; set false to mint a link with no query string)\n```\n\nThe tool returns:\n\n```json\n{\n  \"issued_url\": \"https://lp.petsy.com.au/spring-sale?utm_source=Meta&utm_medium=Paid+Social&...\",\n  \"mapping_id\": \"uuid-of-the-url-mapping\",\n  \"idempotent\": false,\n  \"warning\": null\n}\n```\n\nCopy `issued_url` and paste it as the destination URL in your Meta campaign.\n\n### Retry without duplicating\n\nIf the tool call is interrupted, call it again with the **same `external_id`**:\n\n```\nUse the create_link tool with:\n- external_id: \"my-spring-sale-2025-meta-v1\"   (your idempotency key)\n- ...same other fields...\n```\n\nThe response comes back with `\"idempotent\": true`, and the same `issued_url`\nis returned — no duplicate mapping is created.\n\n### Look up an existing link\n\n```\nUse the find_link tool with:\n- external_id: \"my-spring-sale-2025-meta-v1\"\n```\n\nReturns `{ \"found\": true, \"issued_url\": \"...\", \"mapping_id\": \"...\" }` if the\nlink exists, or `{ \"found\": false }` if it does not.\n\n### Governance block\n\nIf your destination URL is not in the account's allowlist, or if the link type\nhas a fixed field that conflicts with your input, `create_link` returns a\nstructured error rather than throwing:\n\n```json\n{\n  \"error\": \"destination not in account allowlist\",\n  \"violations\": [...]\n}\n```\n\nThe tool does not crash — the error is displayed to the user so they can adjust\nthe inputs and try again.\n\n---\n\n## Environment reference\n\n| Env var | Example value | Notes |\n|---|---|---|\n| `DAVA_API_KEY` | `dava_sk_live_abc123...` | Required. Links-scoped Dáva API key. |\n| `DAVA_API_URL` | `https://api-v2.davazmysel.com` | Optional. Override for staging or local dev. |\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Server exits at startup with \"DAVA_API_KEY environment variable is not set\" | `DAVA_API_KEY` missing from env | Add it to the `env` block in Claude Desktop config |\n| `create_link` returns HTTP 401 | API key is invalid or revoked | Rotate the key in the Dáva dashboard |\n| `create_link` returns HTTP 403 | Key lacks `links` scope | Contact the Dáva team to enable `links` scope |\n| `create_link` returns a governance error | Destination not in allowlist or fixed field conflict | Adjust the destination URL or contact your account manager |\n| `find_link` returns `found: false` | Wrong `external_id` or link was not yet created | Double-check the key; call `create_link` first |\n","readmeFilename":"README.md"}