@straitlink/mcp 0.2.0 → 0.2.1

package/README.md

@@ -39,8 +39,8 @@ workspaces. The tools report iPhone results the same way, but treat iPhone insta
 | `create_link` | Create one link and get its `shortUrl` | secret |
 | `batch_create_links` | Create up to 500 links in one call (safe to re-run: existing slugs are per-item 409s) | secret |
 | `get_link` | Read one link by slug | secret |
-| `list_links` | List links, one page at a time | secret |
-| `update_link` | Change destination, title, tags or expiry. **Asks for `confirm: true`**: without it you get a preview and nothing changes | secret |
+| `list_links` | List links, one page at a time. `status: "paused"` lists turned-off links (0.2.1) | secret |
+| `update_link` | Change destination, title, tags or expiry, or `isActive` on its own (false pauses, true turns a paused link back on; 0.2.1). **Asks for `confirm: true`**: without it you get a preview and nothing changes | secret |
 | `get_analytics` | Taps, app opens, installs, conversions and revenue, by day / channel / link / platform (`GET /v1/analytics`). iPhone installs come from beta install matching | secret |
 | `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 |
@@ -50,7 +50,7 @@ workspaces. The tools report iPhone results the same way, but treat iPhone insta
 | `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 |
+| `deactivate_link` | Turn a link off: taps then get the "link not found" page. **Asks for `confirm: true`**; turn it back on with `update_link` `isActive: true` | secret |
 | `search_docs` | Search the Strait docs offline (bundled index) | none |
 
 Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, …) and its description starts with

package/dist/client.js

@@ -77,7 +77,7 @@ export class StraitClient {
         return this.call('getLink', 'GET', `/v1/links/${encodeURIComponent(slug)}`);
     }
     listLinks(opts = {}) {
-        return this.call('listLinks', 'GET', '/v1/links', { query: { limit: opts.limit ?? 50, cursor: opts.cursor } });
+        return this.call('listLinks', 'GET', '/v1/links', { query: { limit: opts.limit ?? 50, cursor: opts.cursor, status: opts.status } });
     }
     updateLink(slug, patch) {
         return this.call('updateLink', 'PATCH', `/v1/links/${encodeURIComponent(slug)}`, { body: patch });

package/dist/server.js

@@ -6,7 +6,7 @@ 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.2.0';
+export const SERVER_VERSION = '0.2.1';
 /** 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]');

package/dist/tools.js

@@ -76,6 +76,42 @@ function hostOf(url) {
     }
 }
 const UPDATE_FIELDS = ['longUrl', 'title', 'tags', 'expiresAt', 'expiredAction', 'expiredUrl'];
+/** Paused pages a turn-back-on preview reads to find the link (100 each). */
+const PAUSED_PREVIEW_PAGES = 5;
+/** update_link with isActive (engine ADR 0041: PATCH { isActive } sent alone). */
+async function setActive(c, slug, isActive, confirm, otherFields) {
+    if (otherFields)
+        throw new Error('send isActive on its own, then other fields in a second update_link call');
+    if (confirm)
+        return { applied: true, link: await c.updateLink(slug, { isActive }) };
+    const next = `Nothing has changed yet. Show this to the user; if they agree, call update_link again with slug "${slug}", isActive: ${isActive} and confirm: true.`;
+    const live = await c.getLink(slug).catch((err) => {
+        if (err instanceof StraitApiError && err.status === 404)
+            return null;
+        throw err;
+    });
+    if (!isActive) {
+        if (!live)
+            throw new StraitApiError(404, { error: `no active link with slug "${slug}" in this workspace` }, 'updateLink');
+        return { preview: true, applied: false, slug, shortUrl: live.shortUrl, current: { isActive: true, longUrl: live.longUrl }, proposed: { isActive: false }, next };
+    }
+    if (live)
+        return { preview: true, applied: false, alreadyOn: true, slug, shortUrl: live.shortUrl, longUrl: live.longUrl, next: 'This link is already on. Nothing to do.' };
+    let cursor;
+    for (let page = 0; page < PAUSED_PREVIEW_PAGES; page++) {
+        const r = await c.listLinks({ status: 'paused', limit: 100, cursor });
+        const hit = r.links.find((l) => l.slug === slug);
+        if (hit)
+            return { preview: true, applied: false, slug, shortUrl: hit.shortUrl, current: { isActive: false, longUrl: hit.longUrl, title: hit.title ?? null }, proposed: { isActive: true }, next };
+        if (!r.nextCursor)
+            break;
+        cursor = r.nextCursor;
+    }
+    return {
+        preview: true, applied: false, found: false, slug,
+        next: `No paused link "${slug}" in the newest ${PAUSED_PREVIEW_PAGES * 100} paused links (list_links status: paused shows them). Confirming answers 404 if there is none.`,
+    };
+}
 export const TOOLS = [
     tool({
         name: 'create_link',
@@ -106,10 +142,12 @@ export const TOOLS = [
     }),
     tool({
         name: 'list_links',
-        description: 'List active links, newest first, one page at a time. Pass nextCursor back as cursor until it is null.',
+        description: 'List links, newest first, one page at a time. Pass nextCursor back as cursor until it is null. ' +
+            'status: active (default) or paused (turned off, and can be turned back on with update_link isActive: true; links disabled for abuse are not listed).',
         inputSchema: {
             limit: z.number().int().min(1).max(100).optional().describe('Page size, default 50'),
             cursor: z.string().optional().describe('nextCursor from the previous page'),
+            status: z.enum(['active', 'paused']).optional().describe('active (default) or paused'),
         },
         annotations: { title: 'List links', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         needsKey: true,
@@ -117,9 +155,11 @@ export const TOOLS = [
     }),
     tool({
         name: 'update_link',
-        description: 'Change a live link: its destination, title, tags or expiry. People who tap the link afterwards go to the new destination, ' +
+        description: 'Change a link: its destination, title, tags or expiry, or turn it off or back on with isActive. People who tap the link afterwards get the change, ' +
             'so this needs confirm: true. Without it nothing changes: you get a preview of the current and proposed values to show the user first. ' +
-            'null clears expiresAt / expiredAction / expiredUrl.',
+            'null clears expiresAt / expiredAction / expiredUrl. isActive is sent on its own: false pauses the link (taps get the "link not found" page), ' +
+            'true turns a paused link back on (taps follow within about 30 seconds). A link disabled for breaking the acceptable use policy cannot be turned back on, ' +
+            'and if another active link now uses the slug, pause or rename that one first.',
         inputSchema: {
             slug,
             longUrl: httpsUrl.optional(),
@@ -128,11 +168,14 @@ export const TOOLS = [
             expiresAt: when.nullable().optional(),
             expiredAction: z.enum(['page', 'store', 'url']).nullable().optional(),
             expiredUrl: httpsUrl.nullable().optional(),
+            isActive: z.boolean().optional().describe('Alone: false pauses the link, true turns a paused link back on'),
             confirm: z.boolean().optional().describe('true to apply the change; omit or false to preview it'),
         },
         annotations: { title: 'Update a link', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
         needsKey: true,
         run: async (c, a) => {
+            if (a.isActive !== undefined)
+                return setActive(c, a.slug, a.isActive, a.confirm === true, UPDATE_FIELDS.some((f) => a[f] !== undefined));
             const patch = {};
             for (const f of UPDATE_FIELDS)
                 if (a[f] !== undefined)
@@ -321,7 +364,7 @@ export const TOOLS = [
     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 ' +
+            'Its history stays in analytics, and it can be turned back on with update_link with isActive: true. This needs confirm: true; without it ' +
             'nothing changes and you get a preview of the link to show the user first.',
         inputSchema: {
             slug,
@@ -339,7 +382,7 @@ export const TOOLS = [
                     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.',
+                    next: 'Nothing has changed yet. After deactivation taps get the "link not found" page until it is turned back on (update_link isActive: true). If the user agrees, call deactivate_link again with confirm: true.',
                 };
             }
             await c.deactivateLink(a.slug);
@@ -377,6 +420,7 @@ export const SERVER_INSTRUCTIONS = [
     '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, 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.',
+    'To turn a paused link back on: list_links with status: paused to find it, then update_link with isActive: true (preview, then 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.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@straitlink/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "mcpName": "in.straitlink/mcp",
   "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": [
@@ -55,7 +55,7 @@
     "@types/node": "^22.20.5",
     "tsx": "^4.23.15",
     "typescript": "5.9",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.12"
   },
   "publishConfig": {
     "access": "public",