@linkforty/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LinkForty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+<div align="center">
+
+# LinkForty MCP Server
+
+**Connect Claude, Cursor, Claude Code, and any MCP-compatible AI tool to your LinkForty deep links and analytics.**
+
+[![npm version](https://img.shields.io/npm/v/@linkforty/mcp-server.svg?style=flat-square&color=26adae)](https://www.npmjs.com/package/@linkforty/mcp-server)
+[![License: MIT](https://img.shields.io/badge/license-MIT-26adae.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/node/v/@linkforty/mcp-server.svg?style=flat-square&color=26adae)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.0-26adae.svg?style=flat-square)](https://modelcontextprotocol.io)
+
+[Quick start](#quick-start) · [Available tools](#available-tools) · [Configuration](#configuration) · [LinkForty](https://linkforty.com)
+
+</div>
+
+---
+
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for [LinkForty](https://linkforty.com). It exposes 20 tools that let an AI assistant manage your deep links, query analytics, configure workspaces, and even generate ready-to-paste SDK integration code for your mobile apps — all using natural language.
+
+## What you can do with it
+
+Once connected, you can ask things like:
+
+- *"Create a LinkForty deep link for my Spring sale on Instagram with UTM source=instagram, medium=social, campaign=spring-sale"*
+- *"Which links drove the most installs last week?"*
+- *"Show me click trends for my top 5 links over the last 30 days"*
+- *"Why is link xyz123 getting clicks but no installs?"*
+- *"Help me add the LinkForty SDK to my React Native app"*
+- *"Create 50 deep links from this CSV"*
+
+The AI calls the appropriate LinkForty API behind the scenes and returns structured results.
+
+## Quick start
+
+### 1. Get your API key
+
+1. Sign in to your [LinkForty dashboard](https://app.linkforty.com)
+2. Go to **Workspace Settings → API Keys**
+3. Click **Create API key**, copy the value (starts with `dl_`)
+
+> **Note:** API keys are scoped to a single workspace. If you manage multiple workspaces, you can run multiple instances of the MCP server with different keys.
+
+### 2. Add to your MCP client
+
+#### Claude Desktop
+
+Edit your `claude_desktop_config.json` (location varies by OS - see [Anthropic's docs](https://docs.anthropic.com/en/docs/build-with-claude/computer-use)):
+
+```json
+{
+  "mcpServers": {
+    "linkforty": {
+      "command": "npx",
+      "args": ["-y", "@linkforty/mcp-server"],
+      "env": {
+        "LINKFORTY_API_KEY": "dl_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The LinkForty tools will appear in the tool picker.
+
+#### Cursor
+
+Add to your Cursor settings under **MCP Servers**:
+
+```json
+{
+  "linkforty": {
+    "command": "npx",
+    "args": ["-y", "@linkforty/mcp-server"],
+    "env": {
+      "LINKFORTY_API_KEY": "dl_your_api_key_here"
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add linkforty -e LINKFORTY_API_KEY=dl_your_api_key_here -- npx -y @linkforty/mcp-server
+```
+
+### 3. (Optional) Self-hosted LinkForty Core
+
+If you're running LinkForty Core on your own infrastructure, set the base URL:
+
+```json
+"env": {
+  "LINKFORTY_API_KEY": "dl_your_api_key_here",
+  "LINKFORTY_BASE_URL": "https://your-linkforty-instance.com/api"
+}
+```
+
+## Available tools
+
+### Links (6)
+
+| Tool                | Description                                                                |
+|---------------------|----------------------------------------------------------------------------|
+| `create_link`       | Create a new deep link with iOS/Android/web URLs, UTM, targeting, and more |
+| `list_links`        | List/filter links by status, source, project, search query, or date range  |
+| `get_link`          | Get a single link by ID or short code                                      |
+| `update_link`       | Update any field on an existing link                                       |
+| `delete_link`       | Permanently delete a link                                                  |
+| `bulk_create_links` | Create up to 100 links in one call                                         |
+
+### Analytics (5)
+
+| Tool                      | Description                                           |
+|---------------------------|-------------------------------------------------------|
+| `get_link_analytics`      | Per-link analytics: clicks, geo, devices, time series |
+| `get_overview_analytics`  | Workspace-wide analytics across all links             |
+| `get_top_links`           | Top performing links ranked by clicks                 |
+| `get_install_attribution` | Install attribution data with fingerprint matching    |
+| `get_funnel`              | Click → install → event conversion funnel             |
+
+### Templates (3)
+
+| Tool                   | Description                                             |
+|------------------------|---------------------------------------------------------|
+| `list_templates`       | List all link templates                                 |
+| `create_template`      | Create a new template with default destinations and UTM |
+| `set_default_template` | Mark a template as the workspace default                |
+
+### Projects (2)
+
+| Tool             | Description                             |
+|------------------|-----------------------------------------|
+| `list_projects`  | List all projects in the workspace      |
+| `create_project` | Create a new project for grouping links |
+
+### Workspace (3)
+
+| Tool                    | Description                                       |
+|-------------------------|---------------------------------------------------|
+| `list_workspaces`       | List workspaces accessible by the API key         |
+| `get_current_workspace` | Get details about the current workspace           |
+| `get_app_config`        | Get iOS/Android bundle IDs, schemes, link domains |
+
+### SDK helper (1)
+
+| Tool                      | Description                                                                                        |
+|---------------------------|----------------------------------------------------------------------------------------------------|
+| `get_sdk_install_snippet` | Generate ready-to-paste SDK init code for any platform (react-native, expo, ios, android, flutter) |
+
+## Configuration
+
+| Environment variable  | Required   | Default                         | Description                                          |
+|-----------------------|------------|---------------------------------|------------------------------------------------------|
+| `LINKFORTY_API_KEY`   | Yes        | -                               | Your LinkForty workspace API key (starts with `dl_`) |
+| `LINKFORTY_BASE_URL`  | No         | `https://app.linkforty.com/api` | Override for self-hosted LinkForty Core instances    |
+
+## Security and privacy
+
+- **Your API key never leaves your machine.** It is only sent in `Authorization: Bearer` headers to the LinkForty API endpoint you configured.
+- **No data is stored or logged by the MCP server itself.** It is a stateless translator between MCP requests and LinkForty's REST API.
+- **API keys inherit your workspace permissions.** The MCP server can only do what your API key has permission to do - there's no privilege escalation.
+- The MCP server runs locally as a subprocess of your AI client and communicates over stdio, not the network.
+
+## Development
+
+```bash
+# Install
+git clone https://github.com/linkforty/mcp-server
+cd mcp-server
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Test against your API key
+LINKFORTY_API_KEY=dl_... node dist/index.js
+```
+
+## License
+
+MIT © LinkForty
+
+## Links
+
+- [LinkForty](https://linkforty.com)
+- [LinkForty Docs](https://docs.linkforty.com)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Report an issue](https://github.com/linkforty/mcp-server/issues)

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Thin HTTP client for the LinkForty Cloud API.
+ * Authenticates via API key (Bearer token).
+ */
+import type { Config } from './config.js';
+export declare class LinkFortyClient {
+    private config;
+    constructor(config: Config);
+    request<T = unknown>(path: string, options?: {
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: unknown;
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<T>;
+    get<T = unknown>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,qBAAa,eAAe;IACd,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,MAAM;IAE5B,OAAO,CAAC,CAAC,GAAG,OAAO,EACvB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;QACrD,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;KAC1D,GACL,OAAO,CAAC,CAAC,CAAC;IAwDb,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAI5F,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAI9C,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAI7C,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;IAI/C,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM;CAGjC"}

package/dist/client.js

@@ -0,0 +1,76 @@
+export class LinkFortyClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async request(path, options = {}) {
+        const { method = 'GET', body, query } = options;
+        let url = `${this.config.baseUrl}${path}`;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null && value !== '') {
+                    params.set(key, String(value));
+                }
+            }
+            const qs = params.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const headers = {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            Accept: 'application/json',
+        };
+        if (body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            let message = `${method} ${path} failed: ${response.status} ${response.statusText}`;
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed.message)
+                    message += ` — ${parsed.message}`;
+                else if (parsed.error)
+                    message += ` — ${parsed.error}`;
+            }
+            catch {
+                if (text)
+                    message += ` — ${text.substring(0, 200)}`;
+            }
+            throw new Error(message);
+        }
+        // Some endpoints return empty bodies (e.g. DELETE)
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    // Convenience methods
+    get(path, query) {
+        return this.request(path, { method: 'GET', query });
+    }
+    post(path, body) {
+        return this.request(path, { method: 'POST', body });
+    }
+    put(path, body) {
+        return this.request(path, { method: 'PUT', body });
+    }
+    patch(path, body) {
+        return this.request(path, { method: 'PATCH', body });
+    }
+    delete(path) {
+        return this.request(path, { method: 'DELETE' });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration loaded from environment variables.
+ */
+export interface Config {
+    apiKey: string;
+    baseUrl: string;
+}
+export declare function loadConfig(): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAanC"}

package/dist/config.js

@@ -0,0 +1,14 @@
+/**
+ * Configuration loaded from environment variables.
+ */
+export function loadConfig() {
+    const apiKey = process.env.LINKFORTY_API_KEY;
+    if (!apiKey) {
+        throw new Error('LINKFORTY_API_KEY environment variable is required. ' +
+            'Get your API key at https://app.linkforty.com/workspace-settings → API Keys.');
+    }
+    const baseUrl = (process.env.LINKFORTY_BASE_URL || 'https://app.linkforty.com/api')
+        .replace(/\/$/, '');
+    return { apiKey, baseUrl };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,sDAAsD;YACtD,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,+BAA+B,CAAC;SAChF,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEtB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * LinkForty MCP server entry point.
+ *
+ * Connects to MCP clients (Claude Desktop, Cursor, Claude Code, etc.) over stdio
+ * and exposes the LinkForty Cloud API as a set of tools.
+ *
+ * Configuration via environment variables:
+ *   - LINKFORTY_API_KEY (required) — your LinkForty workspace API key
+ *   - LINKFORTY_BASE_URL (optional) — defaults to https://app.linkforty.com/api
+ *
+ * Add this to your MCP client config:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "linkforty": {
+ *         "command": "npx",
+ *         "args": ["-y", "@linkforty/mcp-server"],
+ *         "env": {
+ *           "LINKFORTY_API_KEY": "dl_..."
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config.js';
+import { LinkFortyClient } from './client.js';
+import { allTools, findTool } from './tools/index.js';
+import { asText } from './tools/shared.js';
+async function main() {
+    // Load config first so we fail fast with a clear error if the API key is missing
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        process.stderr.write(`[linkforty-mcp] ${err.message}\n`);
+        process.exit(1);
+    }
+    const client = new LinkFortyClient(config);
+    const server = new Server({
+        name: 'linkforty-mcp',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+        instructions: 'LinkForty MCP server. Provides tools for managing deep links, analytics, attribution, ' +
+            'templates, projects, and SDK integration. The active workspace is determined by the API key.',
+    });
+    // List all available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: allTools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        })),
+    }));
+    // Dispatch a tool call
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const tool = findTool(name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await tool.handler(args ?? {}, client);
+            return {
+                content: [{ type: 'text', text: asText(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // The server now runs until the transport closes
+    process.stderr.write(`[linkforty-mcp] Connected. ${allTools.length} tools available. Base URL: ${config.baseUrl}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`[linkforty-mcp] Fatal error: ${err instanceof Error ? err.message : err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/analytics.d.ts

@@ -0,0 +1,7 @@
+export declare const getLinkAnalyticsTool: import("./shared.js").ToolDefinition;
+export declare const getOverviewAnalyticsTool: import("./shared.js").ToolDefinition;
+export declare const getTopLinksTool: import("./shared.js").ToolDefinition;
+export declare const getInstallAttributionTool: import("./shared.js").ToolDefinition;
+export declare const getFunnelTool: import("./shared.js").ToolDefinition;
+export declare const analyticsTools: import("./shared.js").ToolDefinition[];
+//# sourceMappingURL=analytics.d.ts.map

package/dist/tools/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/tools/analytics.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,oBAAoB,sCAW/B,CAAC;AAEH,eAAO,MAAM,wBAAwB,sCAUnC,CAAC;AAEH,eAAO,MAAM,eAAe,sCAe1B,CAAC;AAEH,eAAO,MAAM,yBAAyB,sCAcpC,CAAC;AAEH,eAAO,MAAM,aAAa,sCAcxB,CAAC;AAEH,eAAO,MAAM,cAAc,wCAM1B,CAAC"}

package/dist/tools/analytics.js

@@ -0,0 +1,78 @@
+/**
+ * Analytics tools — clicks, geo, devices, attribution, funnel.
+ */
+import { z } from 'zod';
+import { defineTool } from './shared.js';
+const daysSchema = z.number().int().min(1).max(365).optional();
+export const getLinkAnalyticsTool = defineTool({
+    name: 'get_link_analytics',
+    description: 'Get detailed analytics for a single deep link. Returns total clicks, unique clicks, time series, and breakdowns by country, city, region, timezone, device, and platform. Use the days parameter to control the lookback window (default: 30 days).',
+    schema: z.object({
+        linkId: z.string().uuid().describe('Link UUID'),
+        days: daysSchema.describe('Lookback window in days (default 30)'),
+    }),
+    handler: async (args, client) => {
+        return client.get(`/analytics/links/${args.linkId}`, { days: args.days });
+    },
+});
+export const getOverviewAnalyticsTool = defineTool({
+    name: 'get_overview_analytics',
+    description: 'Get workspace-wide analytics across all links. Returns total clicks, unique clicks, time series, geo breakdown (country/city/region/timezone), device/platform/browser breakdown, hourly distribution, UTM parameter breakdown (source/medium/campaign), referrers, and top performing links. Default lookback is 30 days.',
+    schema: z.object({
+        days: daysSchema.describe('Lookback window in days (default 30)'),
+    }),
+    handler: async (args, client) => {
+        return client.get('/analytics/overview', { days: args.days });
+    },
+});
+export const getTopLinksTool = defineTool({
+    name: 'get_top_links',
+    description: 'Get the top performing links in the workspace ranked by total clicks. Returns each link\'s short code, title, total clicks, and unique clicks. Default lookback is 30 days.',
+    schema: z.object({
+        days: daysSchema.describe('Lookback window in days (default 30)'),
+        limit: z.number().int().min(1).max(50).optional().describe('Max number of links to return (default 10)'),
+    }),
+    handler: async (args, client) => {
+        const overview = await client.get('/analytics/overview', {
+            days: args.days,
+        });
+        const limit = args.limit ?? 10;
+        return (overview.topLinks ?? []).slice(0, limit);
+    },
+});
+export const getInstallAttributionTool = defineTool({
+    name: 'get_install_attribution',
+    description: 'Get install attribution data showing how app installs are linked to clicks via device fingerprinting. Pass a linkId to get installs for a specific link, or omit it for workspace-wide stats. Returns total installs, attributed vs organic split, attribution rate, time series, platform breakdown, and recent installs. Note: requires the analytics:installs permission.',
+    schema: z.object({
+        linkId: z.string().uuid().optional().describe('Optional link UUID. Omit for workspace-wide stats.'),
+        days: daysSchema.describe('Lookback window in days (default 30)'),
+    }),
+    handler: async (args, client) => {
+        if (args.linkId) {
+            return client.get(`/analytics/installs/${args.linkId}`, { days: args.days });
+        }
+        return client.get('/analytics/installs', { days: args.days });
+    },
+});
+export const getFunnelTool = defineTool({
+    name: 'get_funnel',
+    description: 'Get the conversion funnel from clicks → installs → events for the workspace. Returns total clicks, unique clicks, total/attributed installs, click-to-install conversion rate, average/median/p75/p95 time to install, and the top converting links. Useful for understanding overall campaign efficiency. Note: requires the analytics:installs permission.',
+    schema: z.object({
+        days: daysSchema.describe('Lookback window in days (default 30)'),
+        projectId: z.string().uuid().optional().describe('Optional project UUID to filter by'),
+    }),
+    handler: async (args, client) => {
+        return client.get('/analytics/conversion-funnel', {
+            days: args.days,
+            projectId: args.projectId,
+        });
+    },
+});
+export const analyticsTools = [
+    getLinkAnalyticsTool,
+    getOverviewAnalyticsTool,
+    getTopLinksTool,
+    getInstallAttributionTool,
+    getFunnelTool,
+];
+//# sourceMappingURL=analytics.js.map

package/dist/tools/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/tools/analytics.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Aggregates all MCP tool definitions.
+ */
+import type { ToolDefinition } from './shared.js';
+export declare const allTools: ToolDefinition[];
+export declare function findTool(name: string): ToolDefinition | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAQlD,eAAO,MAAM,QAAQ,EAAE,cAAc,EAOpC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE"}

package/dist/tools/index.js

@@ -0,0 +1,18 @@
+import { linkTools } from './links.js';
+import { analyticsTools } from './analytics.js';
+import { templateTools } from './templates.js';
+import { projectTools } from './projects.js';
+import { workspaceTools } from './workspaces.js';
+import { sdkTools } from './sdk.js';
+export const allTools = [
+    ...linkTools,
+    ...analyticsTools,
+    ...templateTools,
+    ...projectTools,
+    ...workspaceTools,
+    ...sdkTools,
+];
+export function findTool(name) {
+    return allTools.find((t) => t.name === name);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC,MAAM,CAAC,MAAM,QAAQ,GAAqB;IACxC,GAAG,SAAS;IACZ,GAAG,cAAc;IACjB,GAAG,aAAa;IAChB,GAAG,YAAY;IACf,GAAG,cAAc;IACjB,GAAG,QAAQ;CACZ,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC/C,CAAC"}

package/dist/tools/links.d.ts

@@ -0,0 +1,8 @@
+export declare const createLinkTool: import("./shared.js").ToolDefinition;
+export declare const listLinksTool: import("./shared.js").ToolDefinition;
+export declare const getLinkTool: import("./shared.js").ToolDefinition;
+export declare const updateLinkTool: import("./shared.js").ToolDefinition;
+export declare const deleteLinkTool: import("./shared.js").ToolDefinition;
+export declare const bulkCreateLinksTool: import("./shared.js").ToolDefinition;
+export declare const linkTools: import("./shared.js").ToolDefinition[];
+//# sourceMappingURL=links.d.ts.map

package/dist/tools/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../src/tools/links.ts"],"names":[],"mappings":"AA0CA,eAAO,MAAM,cAAc,sCAQzB,CAAC;AAEH,eAAO,MAAM,aAAa,sCAiBxB,CAAC;AAEH,eAAO,MAAM,WAAW,sCAatB,CAAC;AAEH,eAAO,MAAM,cAAc,sCAwBzB,CAAC;AAEH,eAAO,MAAM,cAAc,sCAUzB,CAAC;AAEH,eAAO,MAAM,mBAAmB,sCAU9B,CAAC;AAEH,eAAO,MAAM,SAAS,wCAOrB,CAAC"}