@straitlink/mcp 0.1.0 → 0.2.0

package/README.md

@@ -15,12 +15,13 @@ A tap on a Strait link goes straight to the exact screen in your app (Straight),
 claude mcp add strait --env STRAIT_SECRET_KEY=st_live_your_key -- npx -y @straitlink/mcp
 ```
 
-Use Strait from AI tools such as Claude Code, Cursor and Claude Desktop: create deep links, change them, read
-analytics, check App Links / Universal Links files, see where taps on a link go, and search the Strait docs.
+Use Strait from AI tools such as Claude Code, Cursor and Claude Desktop: create deep links, change or turn them off,
+read analytics, usage and referrals, check App Links / Universal Links files, see where taps on a link go, look after
+webhooks (deliveries, test, redeliver) and search the Strait docs.
 
-It is a local stdio server with 10 tools. Three of them write (`create_link`, `batch_create_links`,
-`update_link`); the other seven only read. Eight need your secret key; `check_app_links`, `search_docs` and demo
-`trace_tap` work without one. Other deep-link vendors also ship MCP servers that can create links, so this README
+It is a local stdio server with 16 tools. Six of them write (`create_link`, `batch_create_links`, `update_link`,
+`deactivate_link`, `test_webhook`, `redeliver_webhook_delivery`); the other ten only read. Fourteen need your secret
+key; `check_app_links`, `search_docs` and demo `trace_tap` work without one. Other deep-link vendors also ship MCP servers that can create links, so this README
 makes no "first" or "only" claim; it describes what this server does today.
 
 **iPhone is in beta.** iPhone install matching (deferred deep linking on iOS) is in beta; Android uses the Play
@@ -44,10 +45,19 @@ workspaces. The tools report iPhone results the same way, but treat iPhone insta
 | `check_app_links` | Check a domain's `assetlinks.json` and `apple-app-site-association`, with a fix for each problem | none |
 | `simulate_tap` | Dry-run one tap from one device or app (nothing recorded or billed) | secret |
 | `trace_tap` | Walk a link through WhatsApp, Instagram, Facebook, Chrome, Safari, iPad, computer and preview bots; or read a Live Tap Trace from the website demo | secret (link) / none (demo token) |
+| `get_usage` | This month's taps and new links against the plan, `level` (ok / warn / over) and `new_links_paused` (`GET /v1/usage`) | secret |
+| `get_referrals` | Referral report: taps and referred installs per code (`GET /v1/referrals`, a preview: says "not switched on yet" until it is) | secret |
+| `list_webhook_deliveries` | A webhook's deliveries (status, attempts, last HTTP status, next retry; no payloads). Without `webhookId`: the workspace's webhooks (id, receiver site, events) | secret |
+| `test_webhook` | Send one `ping` to a webhook now and see the receiver's status and time (not stored, not retried) | secret |
+| `redeliver_webhook_delivery` | Send a failed delivery again (same `X-Strait-Delivery` id). **Asks for `confirm: true`** | secret |
+| `deactivate_link` | Turn a link off: taps then get the "link not found" page. **Asks for `confirm: true`**; the API can't turn it back on yet | secret |
 | `search_docs` | Search the Strait docs offline (bundled index) | none |
 
-Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, …). Only `update_link` is destructive.
-`create_link` and `batch_create_links` write new links but never change existing ones. There is no delete tool.
+Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, …) and its description starts with
+"Read-only." or "Write." for the 0.2 tools. `update_link` and `deactivate_link` are destructive; they and
+`redeliver_webhook_delivery` show a preview first and act only with `confirm: true`. `create_link` and
+`batch_create_links` write new links but never change existing ones. There is no delete tool: a deactivated link
+keeps its history.
 
 ## Keys
 
@@ -57,6 +67,8 @@ links, so:
 - Create a separate key for your AI tools, so you can revoke it on its own.
 - Keep it in the MCP client's config or environment, never in app or website code.
 - A publishable key (`st_pub_live_…`) does not work here: it is for the SDKs in your apps.
+- The server sends the key only as an `Authorization: Bearer` header to `STRAIT_API_URL`, never logs it, and
+  replaces anything shaped like a secret key in tool output or errors with `st_…[redacted]`.
 
 Without a key, `check_app_links`, `search_docs` and demo `trace_tap` still work.
 
@@ -109,6 +121,10 @@ In Cursor or Claude Desktop use `"command": "node", "args": ["/absolute/path/to/
 - "My links open the browser instead of the app. Check hilltop.strait.link and shop.hilltop.example."
 - "What happens when someone taps `summer` inside Instagram on an iPhone?"
 - "How do I receive links in Expo Router?"
+- "How much of this month's plan have we used?"
+- "My webhook stopped firing. Show me its last deliveries, send it a test, and resend the failed ones."
+- "Turn off the `spring-sale` link." (you'll see a preview first)
+- "Which referral codes brought the most installs in October?"
 
 Hilltop Shoes (`hilltop.strait.link`, `*.hilltop.example`) is a made-up shop used in examples.
 
@@ -130,8 +146,19 @@ Hilltop Shoes (`hilltop.strait.link`, `*.hilltop.example`) is a made-up shop use
 - `remotes` is left out until `mcp.strait.link` is deployed; add
   `{"type": "streamable-http", "url": "https://mcp.strait.link/mcp"}` then. Add `"repository": {"url": "https://github.com/bazingga08/strait-mcp", "source": "github"}`
   once the GitHub repo exists.
-- Order when the Strait team is ready: create the repo, publish `@straitlink/mcp` to npm, add the TXT record, then
-  `mcp-publisher publish`.
+- Order when the Strait team is ready: create the repo, publish `@straitlink/mcp` to npm (done: 0.1.0 on 15 Oct,
+  `mcpName` matches), add the TXT record, then run the **MCP registry** workflow (`.github/workflows/registry.yml`).
+  Without the `MCP_DNS_PRIVATE_KEY` secret it only validates `server.json` (schema, name, version, npm) and stops.
+
+### Founder steps (about 10 minutes, after the GitHub repo exists)
+
+1. Claude makes a key pair on the Mac (`openssl genpkey -algorithm ed25519`) and shows you only the **public** part.
+2. In the DNS settings for **straitlink.in**, add a **TXT** record on the root (`@`) with the value
+   `v=MCPv1; k=ed25519; p=<public key>`. Save. It can take up to an hour to appear.
+3. In GitHub, repo **strait-mcp → Settings → Secrets → Actions**, add `MCP_DNS_PRIVATE_KEY` with the private key
+   (Claude puts it there if you allow secret writes).
+4. Actions → **MCP registry** → Run workflow. When it's green, search "Strait" on
+   registry.modelcontextprotocol.io: that's how you know it worked.
 
 ## Licence
 

package/dist/client.js

@@ -91,6 +91,38 @@ export class StraitClient {
     checkAppLinks(domain) {
         return this.call('checkAppLinks', 'GET', '/v1/tools/app-links', { query: { domain }, auth: false });
     }
+    getUsage() {
+        return this.call('getUsage', 'GET', '/v1/usage');
+    }
+    /** Referral report (preview): the engine answers 404 until referrals are switched on. */
+    getReferrals(q = {}) {
+        return this.call('getReferrals', 'GET', '/v1/referrals', { query: q });
+    }
+    /** The workspace's webhooks, from the export (configuration only: the engine never exports signing secrets). */
+    listWebhooks() {
+        return this.call('exportData', 'GET', '/v1/export', { query: { part: 'webhooks' } });
+    }
+    listWebhookDeliveries(webhookId, opts = {}) {
+        return this.call('listWebhookDeliveries', 'GET', `/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries`, { query: { limit: opts.limit, cursor: opts.cursor } });
+    }
+    testWebhook(webhookId) {
+        return this.call('testWebhook', 'POST', `/v1/webhooks/${encodeURIComponent(webhookId)}/test`);
+    }
+    redeliverWebhookDelivery(deliveryId) {
+        return this.call('redeliverWebhookDelivery', 'POST', `/v1/webhook-deliveries/${encodeURIComponent(deliveryId)}/redeliver`);
+    }
+    /** DELETE /v1/links/{slug}: 204 deactivated; 404 (empty body) = no active link with that slug. */
+    async deactivateLink(slug) {
+        try {
+            await this.call('deactivateLink', 'DELETE', `/v1/links/${encodeURIComponent(slug)}`);
+        }
+        catch (err) {
+            if (err instanceof StraitApiError && err.status === 404 && !err.body) {
+                throw new StraitApiError(404, { error: `no active link with slug "${slug}" in this workspace` }, 'deactivateLink');
+            }
+            throw err;
+        }
+    }
     /** Live Tap Trace of the website demo (204 = no tap yet → null). */
     getTapTrace(token) {
         return this.call('getTapTrace', 'GET', `/v1/trace/${encodeURIComponent(token)}`, { auth: false }).then((r) => r ?? null);

package/dist/server.js

@@ -6,7 +6,10 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StraitApiError } from './client.js';
 import { SERVER_INSTRUCTIONS, TOOLS } from './tools.js';
 export const SERVER_NAME = 'strait';
-export const SERVER_VERSION = '0.1.0';
+export const SERVER_VERSION = '0.2.0';
+/** Anything shaped like a secret key (st_live_… / st_test_…) never leaves the server in a tool result. */
+const SECRET_KEY_SHAPE = /(?<![A-Za-z0-9])st_(?:live|test)_[A-Za-z0-9_-]+/g;
+export const redactSecrets = (text) => text.replace(SECRET_KEY_SHAPE, 'st_…[redacted]');
 /** Turns a tool's return value (or error) into an MCP tool result. Errors are results, not protocol errors. */
 export async function runTool(t, client, args) {
     try {
@@ -17,7 +20,7 @@ export async function runTool(t, client, args) {
             };
         }
         const out = await t.run(client, args);
-        return { content: [{ type: 'text', text: JSON.stringify(out ?? { ok: true }, null, 2) }] };
+        return { content: [{ type: 'text', text: redactSecrets(JSON.stringify(out ?? { ok: true }, null, 2)) }] };
     }
     catch (err) {
         const text = err instanceof StraitApiError
@@ -25,7 +28,7 @@ export async function runTool(t, client, args) {
             : err instanceof Error
                 ? err.message
                 : String(err);
-        return { isError: true, content: [{ type: 'text', text }] };
+        return { isError: true, content: [{ type: 'text', text: redactSecrets(text) }] };
     }
 }
 export function createStraitServer(client, tools = TOOLS) {

package/dist/tools.js

@@ -3,11 +3,13 @@
  * the stdio server, the remote Worker and the tests all register the same list.
  */
 import { z } from 'zod';
+import { StraitApiError } from './client.js';
 import { searchDocs } from './docs.js';
 const tool = (t) => t;
 // ── shared input pieces ─────────────────────────────────────────────────────
 const slug = z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/, 'letters, digits, - and _ (1–64)').describe("The link's slug: the part after the link domain, e.g. `summer` in https://hilltop.strait.link/summer");
 const httpsUrl = z.string().url().refine((u) => u.startsWith('https://'), 'must be an https URL');
+const uuid = z.string().uuid();
 const when = z.union([z.string(), z.number()]).describe('ISO date-time (2026-12-31T23:59:59Z) or epoch ms');
 const newLinkShape = {
     slug,
@@ -61,6 +63,18 @@ function compactReport(report) {
     }
     return r;
 }
+/** "zapier.com" from a receiver URL: the path, and on some services (Pipedream, ngrok) the subdomain, can be a secret. */
+function hostOf(url) {
+    try {
+        const { hostname } = new URL(url);
+        if (/^[\d.]+$/.test(hostname) || hostname.startsWith('['))
+            return hostname;
+        return hostname.split('.').slice(-2).join('.');
+    }
+    catch {
+        return '(invalid URL)';
+    }
+}
 const UPDATE_FIELDS = ['longUrl', 'title', 'tags', 'expiresAt', 'expiredAction', 'expiredUrl'];
 export const TOOLS = [
     tool({
@@ -208,6 +222,130 @@ export const TOOLS = [
             return { link: url, simulated: true, rows };
         },
     }),
+    tool({
+        name: 'get_usage',
+        description: "Read-only. This calendar month's usage (UTC) against the workspace's plan: billed taps used and included, new links " +
+            'created and included (null = no limit), level (ok, warn from 80 % of included taps, over from 100 %) and new_links_paused. ' +
+            'Going over never stops a redirect; new_links_paused means create_link answers 402 until an upgrade or the month ends.',
+        inputSchema: {},
+        annotations: { title: 'Read this month\'s usage', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        needsKey: true,
+        run: (c) => c.getUsage(),
+    }),
+    tool({
+        name: 'get_referrals',
+        description: 'Read-only. The referral report (a preview): for each referral code in a date range, the taps that carried it and the ' +
+            'referred installs, most conversions first. Days are UTC; at most 92 days per call (default: the last 30 days). ' +
+            'If referrals are not switched on for the workspace yet, says so instead of failing.',
+        inputSchema: {
+            from: z.string().optional().describe('Inclusive start: 2026-10-01, an ISO date-time or epoch ms'),
+            to: z.string().optional().describe('Exclusive end, same formats; default now'),
+        },
+        annotations: { title: 'Read the referral report', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        needsKey: true,
+        run: async (c, a) => {
+            try {
+                return await c.getReferrals(a);
+            }
+            catch (err) {
+                // The engine's unmounted-route answer, not any 404 (e.g. a wrong STRAIT_API_URL serving HTML).
+                if (err instanceof StraitApiError && err.status === 404 && err.body?.error === 'not found') {
+                    return { available: false, note: 'The referral report is a preview and is not switched on for the API yet. Referral codes still travel on links; the report appears here once it is switched on.' };
+                }
+                throw err;
+            }
+        },
+    }),
+    tool({
+        name: 'list_webhook_deliveries',
+        description: "Read-only. A webhook's delivery history, newest first (kept 30 days): each event sent, its status (pending = waiting " +
+            'for a retry, delivered, failed = gave up after 6 attempts), attempts, last HTTP status or error and the next retry time. ' +
+            'A permanent error (e.g. unsafe_target) fails at once. Payloads are never returned. Without webhookId it lists the ' +
+            'workspace\'s webhooks (id, receiver site, events, active) ' +
+            'so you can pick one. Use it when a webhook seems to have stopped.',
+        inputSchema: {
+            webhookId: uuid.optional().describe('The webhook id; omit to list the webhooks first'),
+            limit: z.number().int().min(1).max(100).optional().describe('Page size, default 20'),
+            cursor: z.string().optional().describe('nextCursor from the previous page'),
+        },
+        annotations: { title: 'List webhook deliveries', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        needsKey: true,
+        run: async (c, a) => {
+            if (a.webhookId)
+                return c.listWebhookDeliveries(a.webhookId, a);
+            const { webhooks } = await c.listWebhooks();
+            return {
+                // Receiver URLs are often capability URLs (Zapier, Slack): only the host leaves the engine's answer.
+                webhooks: webhooks.map((w) => ({ id: w.id, site: hostOf(w.url), events: w.events, active: w.active, createdAt: w.createdAt })),
+                next: webhooks.length
+                    ? 'Call list_webhook_deliveries again with webhookId set to one of these ids.'
+                    : 'This workspace has no webhooks. Add one in Dashboard → Settings → Webhooks.',
+            };
+        },
+    }),
+    tool({
+        name: 'test_webhook',
+        description: 'Write. Sends one test event (event: ping) to a webhook right now, even if it is paused, and returns whether the receiver ' +
+            'accepted it, its HTTP status and the time taken (never its response body). The ping is not stored or retried and ' +
+            'changes nothing in Strait. Get the id from list_webhook_deliveries without webhookId.',
+        inputSchema: { webhookId: uuid.describe('The webhook id') },
+        annotations: { title: 'Send a test webhook', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        needsKey: true,
+        run: (c, a) => c.testWebhook(a.webhookId),
+    }),
+    tool({
+        name: 'redeliver_webhook_delivery',
+        description: "Write. Sends one past webhook delivery again, right away, to the webhook's current URL, with the same X-Strait-Delivery id " +
+            '(receivers that de-duplicate on it are safe); its retry schedule starts over. For failed deliveries. This re-sends a real ' +
+            'event into the receiving system, so it needs confirm: true; without it nothing is sent. Refused (409) when already ' +
+            'delivered or being sent right now. A paused webhook must be turned back on first (Dashboard → Settings → Webhooks), ' +
+            'otherwise the redelivery fails at once.',
+        inputSchema: {
+            deliveryId: uuid.describe('The delivery id, from list_webhook_deliveries'),
+            confirm: z.boolean().optional().describe('true to send it; omit or false to preview'),
+        },
+        annotations: { title: 'Redeliver a webhook delivery', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        needsKey: true,
+        run: async (c, a) => {
+            if (a.confirm !== true) {
+                return {
+                    preview: true,
+                    applied: false,
+                    deliveryId: a.deliveryId,
+                    next: 'Nothing has been sent. This re-sends a real event to the webhook receiver. If the user agrees, call redeliver_webhook_delivery again with confirm: true.',
+                };
+            }
+            return { applied: true, delivery: await c.redeliverWebhookDelivery(a.deliveryId) };
+        },
+    }),
+    tool({
+        name: 'deactivate_link',
+        description: 'Write. Turns a link off: afterwards every tap on it gets the "link not found" page instead of the app, store or website. ' +
+            'Its history stays in analytics. The API has no way to turn a link back on yet, so this needs confirm: true; without it ' +
+            'nothing changes and you get a preview of the link to show the user first.',
+        inputSchema: {
+            slug,
+            confirm: z.boolean().optional().describe('true to deactivate; omit or false to preview'),
+        },
+        annotations: { title: 'Deactivate a link', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+        needsKey: true,
+        run: async (c, a) => {
+            if (a.confirm !== true) {
+                const current = await c.getLink(a.slug);
+                return {
+                    preview: true,
+                    applied: false,
+                    slug: a.slug,
+                    shortUrl: current.shortUrl,
+                    longUrl: current.longUrl,
+                    title: current.title ?? null,
+                    next: 'Nothing has changed yet. After deactivation taps get the "link not found" page, and the API cannot turn it back on. If the user agrees, call deactivate_link again with confirm: true.',
+                };
+            }
+            await c.deactivateLink(a.slug);
+            return { applied: true, slug: a.slug, deactivated: true };
+        },
+    }),
     tool({
         name: 'search_docs',
         description: 'Search the Strait documentation (SDK setup for React Native / Expo, Flutter, Android, iOS, Unity, web and Node; App Links and ' +
@@ -238,7 +376,8 @@ export const SERVER_INSTRUCTIONS = [
     'Strait makes links open the right screen in a mobile app (deep links), including after an install (deferred deep links), and reports what happened to each tap.',
     'Keys: the secret key (st_live_…) is for servers and this MCP server only. Never put it in app or website code. Apps and websites use the publishable key (st_pub_live_…) with the Strait SDKs.',
     'Share a link by its shortUrl. Prefer batch_create_links over many create_link calls.',
-    'update_link changes where live links go: call it without confirm first, show the user the preview, and only then call it with confirm: true.',
+    'update_link, deactivate_link and redeliver_webhook_delivery change live behaviour: call them without confirm first, show the user the preview, and only then call them with confirm: true.',
+    'When a webhook seems to have stopped: list_webhook_deliveries (without webhookId to find the id), then test_webhook, then redeliver_webhook_delivery for failed deliveries.',
     'When a link opens the browser instead of the app, run check_app_links on the link domain and the app domain, then trace_tap on the link.',
     'iPhone install matching (deferred deep linking on iOS) is in beta; Android uses the Play Install Referrer. On iPhone the workspace picks the method (device matching, paste handoff, both or neither) in Dashboard → Settings → iPhone installs, read by the SDK at runtime; device matching is off for new workspaces. Use search_docs before answering setup questions.',
 ].join('\n');

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@straitlink/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "mcpName": "in.straitlink/mcp",
-  "description": "Strait MCP server: create and inspect deep links, read analytics, check App Links / Universal Links files and search the docs from AI tools.",
+  "description": "Strait MCP server: create, inspect and deactivate deep links, read analytics, usage and referrals, check and redeliver webhooks, check App Links / Universal Links files and search the docs from AI tools.",
   "keywords": [
     "mcp",
     "model-context-protocol",