xs-shlink-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# XS Shlink MCP Changelog
+
+All notable changes to this project will be documented here.
+
+## 0.1.0 - Unreleased
+
+- Add a local `stdio` MCP server for Shlink.
+- Add 23 tools covering short URLs, analytics, visits, tags, domains, redirect
+  rules, QR-code URLs, health, and Mercure information.
+- Guard destructive tools with server opt-in and per-call confirmation.
+- Add mocked API tests and an end-to-end MCP discovery test.

package/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,159 @@
+# XS Shlink MCP
+
+An MCP server for managing and analyzing a
+[Shlink](https://shlink.io/) URL-shortener instance.
+
+It runs locally over `stdio`, keeps the Shlink API key on the machine running
+the MCP client, and does not require Docker.
+
+## Features
+
+- 23 tools for short URLs, visits, tags, domains, redirect rules, QR codes, and
+  Mercure integration information
+- Typed and validated tool inputs
+- Structured Shlink API errors with request IDs
+- Bounded pagination and request timeouts
+- Destructive operations disabled by default
+- Windows, macOS, and Linux support through Node.js
+
+## Requirements
+
+- Node.js 20 or newer
+- A reachable Shlink instance
+- A Shlink API key
+
+## Run from a local checkout
+
+```shell
+npm install
+npm run build
+```
+
+Add the server to an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "shlink": {
+      "command": "node",
+      "args": ["/absolute/path/to/shlink-mcp/dist/index.js"],
+      "env": {
+        "SHLINK_BASE_URL": "https://s.example.com",
+        "SHLINK_API_KEY": "replace-me",
+        "SHLINK_API_VERSION": "3",
+        "SHLINK_ALLOW_DESTRUCTIVE": "false"
+      }
+    }
+  }
+}
+```
+
+On Windows, use a fully escaped absolute path:
+
+```json
+"args": ["C:\\path\\to\\shlink-mcp\\dist\\index.js"]
+```
+
+## Run the published package
+
+After the package is published to npm, an MCP client can launch it with:
+
+```json
+{
+  "mcpServers": {
+    "shlink": {
+      "command": "npx",
+      "args": ["-y", "xs-shlink-mcp"],
+      "env": {
+        "SHLINK_BASE_URL": "https://s.example.com",
+        "SHLINK_API_KEY": "replace-me"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|---|---:|---:|---|
+| `SHLINK_BASE_URL` | Yes | — | Shlink origin without `/rest`, such as `https://s.example.com` |
+| `SHLINK_API_KEY` | Yes | — | Shlink API key |
+| `SHLINK_API_VERSION` | No | `3` | REST API major version |
+| `SHLINK_TIMEOUT_MS` | No | `10000` | Per-request timeout in milliseconds |
+| `SHLINK_ALLOW_DESTRUCTIVE` | No | `false` | Enables deletion tools when set to `true` |
+
+Never commit an API key. Tool results and errors do not include it.
+
+## Tools
+
+### Short URLs
+
+- `list_short_urls`
+- `get_short_url`
+- `create_short_url`
+- `edit_short_url`
+- `delete_short_url`
+- `get_qr_code_url`
+
+### Analytics and visits
+
+- `get_visit_stats`
+- `get_short_url_visits`
+- `get_tag_visits`
+- `get_domain_visits`
+- `list_orphan_visits`
+- `list_non_orphan_visits`
+- `delete_short_url_visits`
+- `delete_orphan_visits`
+
+### Redirect rules, tags, and domains
+
+- `get_redirect_rules`
+- `set_redirect_rules`
+- `list_tags`
+- `rename_tag`
+- `delete_tags`
+- `list_domains`
+- `set_domain_redirects`
+
+### Monitoring and integrations
+
+- `shlink_health`
+- `get_mercure_info`
+
+All deletion tools require both `SHLINK_ALLOW_DESTRUCTIVE=true` and an explicit
+`confirm: true` tool argument.
+
+## Test with MCP Inspector
+
+Build first, then pass the server environment explicitly:
+
+```shell
+npx -y @modelcontextprotocol/inspector \
+  -e SHLINK_BASE_URL=https://s.example.com \
+  -e SHLINK_API_KEY=replace-me \
+  -- node /absolute/path/to/shlink-mcp/dist/index.js
+```
+
+Start with `shlink_health`, followed by `list_short_urls`.
+
+## Development
+
+```shell
+npm run check
+npm test
+npm run validate
+```
+
+The automated tests use mocked Shlink responses. They do not require or modify
+a live Shlink instance.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for reporting security issues and guidance for
+deploying API keys safely.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Do not open a public issue containing exploit details, API keys, or private
+Shlink data. Contact the repository owner privately through the security
+reporting channel configured on the GitHub repository.
+
+## Deployment guidance
+
+- Store `SHLINK_API_KEY` in the MCP client's environment or secret store.
+- Use the narrowest Shlink API-key roles that satisfy the intended workflows.
+- Leave `SHLINK_ALLOW_DESTRUCTIVE` set to `false` unless deletion is required.
+- Do not expose a local MCP Inspector proxy to untrusted networks.
+- Use HTTPS for the Shlink base URL.
+- Rotate an API key immediately if it appears in logs, screenshots, commits, or
+  shell history.

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export type Config = {
+    baseUrl: string;
+    apiKey: string;
+    apiVersion: number;
+    timeoutMs: number;
+    allowDestructive: boolean;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+const envSchema = z.object({
+    SHLINK_BASE_URL: z.string().url(),
+    SHLINK_API_KEY: z.string().min(1),
+    SHLINK_API_VERSION: z.coerce.number().int().positive().default(3),
+    SHLINK_TIMEOUT_MS: z.coerce.number().int().positive().default(10_000),
+    SHLINK_ALLOW_DESTRUCTIVE: z
+        .enum(["true", "false"])
+        .default("false")
+        .transform((value) => value === "true"),
+});
+export function loadConfig(env = process.env) {
+    const parsed = envSchema.parse(env);
+    return {
+        baseUrl: parsed.SHLINK_BASE_URL.replace(/\/+$/, ""),
+        apiKey: parsed.SHLINK_API_KEY,
+        apiVersion: parsed.SHLINK_API_VERSION,
+        timeoutMs: parsed.SHLINK_TIMEOUT_MS,
+        allowDestructive: parsed.SHLINK_ALLOW_DESTRUCTIVE,
+    };
+}
+//# 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,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACjC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,kBAAkB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACjE,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC;IACrE,wBAAwB,EAAE,CAAC;SACxB,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACvB,OAAO,CAAC,OAAO,CAAC;SAChB,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC;CAC1C,CAAC,CAAC;AAUH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACnD,MAAM,EAAE,MAAM,CAAC,cAAc;QAC7B,UAAU,EAAE,MAAM,CAAC,kBAAkB;QACrC,SAAS,EAAE,MAAM,CAAC,iBAAiB;QACnC,gBAAgB,EAAE,MAAM,CAAC,wBAAwB;KAClD,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ZodError } from "zod";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+async function main() {
+    const config = loadConfig();
+    const server = createServer(config);
+    const transport = new StdioServerTransport();
+    const shutdown = async () => {
+        await server.close();
+        process.exit(0);
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    await server.connect(transport);
+}
+main().catch((error) => {
+    if (error instanceof ZodError) {
+        console.error("Invalid configuration:", error.issues.map((issue) => issue.message).join("; "));
+    }
+    else {
+        console.error(error instanceof Error ? error.message : String(error));
+    }
+    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":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAElC,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACjG,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./config.js";
+import { ShlinkClient } from "./shlink/client.js";
+export declare function createServer(config: Config, client?: ShlinkClient): McpServer;

package/dist/server.js

@@ -0,0 +1,281 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ShlinkClient, ShlinkError } from "./shlink/client.js";
+const shortCodeIdentity = {
+    shortCode: z.string().min(1).describe("The Shlink short code"),
+    domain: z.string().min(1).optional().describe("Domain when the short code is not on the default domain"),
+};
+const isoDate = z.string().datetime({ offset: true });
+const pagination = {
+    page: z.number().int().positive().optional(),
+    itemsPerPage: z.number().int().min(1).max(100).optional(),
+};
+const shortUrlBody = {
+    longUrl: z.string().url().optional(),
+    customSlug: z.string().min(1).optional(),
+    title: z.string().nullable().optional(),
+    tags: z.array(z.string()).optional(),
+    domain: z.string().optional(),
+    validSince: isoDate.nullable().optional(),
+    validUntil: isoDate.nullable().optional(),
+    maxVisits: z.number().int().positive().nullable().optional(),
+    crawlable: z.boolean().optional(),
+    forwardQuery: z.boolean().optional(),
+};
+const visitFilters = {
+    ...pagination,
+    startDate: isoDate.optional(),
+    endDate: isoDate.optional(),
+    excludeBots: z.boolean().optional(),
+};
+function result(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function errorResult(error) {
+    if (error instanceof ShlinkError) {
+        return {
+            isError: true,
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        error: error.message,
+                        status: error.status,
+                        requestId: error.requestId,
+                        type: error.problemType,
+                    }),
+                }],
+        };
+    }
+    return {
+        isError: true,
+        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+    };
+}
+function queryOf(values) {
+    return values;
+}
+export function createServer(config, client = new ShlinkClient(config)) {
+    const server = new McpServer({ name: "shlink-mcp", version: "0.1.0" }, {
+        instructions: "Use read-only tools freely. Create and edit tools change Shlink. Deletion requires explicit confirmation and server-side opt-in.",
+    });
+    const register = (name, 
+    // The SDK's registerTool overload is generic over each individual schema.
+    // This small wrapper centralizes result/error formatting, so preserve the
+    // SDK's runtime validation while allowing each call to infer independently.
+    definition, handler) => {
+        server.registerTool(name, definition, async (args) => {
+            try {
+                return result(await handler(args));
+            }
+            catch (error) {
+                return errorResult(error);
+            }
+        });
+    };
+    register("shlink_health", {
+        description: "Check whether the configured Shlink instance is healthy.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, () => client.health());
+    register("list_short_urls", {
+        description: "List and search short URLs, with bounded pagination.",
+        inputSchema: {
+            ...pagination,
+            searchTerm: z.string().optional(),
+            tags: z.array(z.string()).optional(),
+            orderBy: z.string().optional(),
+            startDate: isoDate.optional(),
+            endDate: isoDate.optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, (args) => client.api("/short-urls", { query: queryOf(args) }));
+    register("get_short_url", {
+        description: "Get details for one Shlink short code.",
+        inputSchema: shortCodeIdentity,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ shortCode, domain }) => client.api(`/short-urls/${encodeURIComponent(shortCode)}`, { query: { domain } }));
+    register("create_short_url", {
+        description: "Create a new Shlink short URL.",
+        inputSchema: {
+            ...shortUrlBody,
+            longUrl: z.string().url(),
+            findIfExists: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }, (args) => client.api("/short-urls", { method: "POST", body: args }));
+    register("edit_short_url", {
+        description: "Edit an existing Shlink short URL.",
+        inputSchema: { ...shortCodeIdentity, ...shortUrlBody },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, ({ shortCode, domain, ...body }) => client.api(`/short-urls/${encodeURIComponent(shortCode)}`, {
+        method: "PATCH",
+        query: { domain },
+        body,
+    }));
+    register("delete_short_url", {
+        description: "Permanently delete a short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.",
+        inputSchema: { ...shortCodeIdentity, confirm: z.literal(true) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async ({ shortCode, domain }) => {
+        if (!config.allowDestructive) {
+            throw new Error("Deletion is disabled. Set SHLINK_ALLOW_DESTRUCTIVE=true to enable it.");
+        }
+        await client.api(`/short-urls/${encodeURIComponent(shortCode)}`, {
+            method: "DELETE",
+            query: { domain },
+        });
+        return { deleted: true, shortCode, domain: domain ?? null };
+    });
+    register("get_short_url_visits", {
+        description: "List visits for one short URL.",
+        inputSchema: {
+            ...shortCodeIdentity,
+            ...pagination,
+            startDate: isoDate.optional(),
+            endDate: isoDate.optional(),
+            excludeBots: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ shortCode, ...query }) => client.api(`/short-urls/${encodeURIComponent(shortCode)}/visits`, {
+        query: queryOf(query),
+    }));
+    register("list_tags", {
+        description: "List Shlink tags, optionally including usage and visit statistics.",
+        inputSchema: { withStats: z.boolean().optional() },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ withStats }) => client.api(withStats ? "/tags/stats" : "/tags"));
+    register("list_domains", {
+        description: "List domains configured or used by Shlink.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, () => client.api("/domains"));
+    register("get_visit_stats", {
+        description: "Get general visit statistics from Shlink.",
+        inputSchema: {
+            startDate: isoDate.optional(),
+            endDate: isoDate.optional(),
+            groupBy: z.enum(["date", "country", "city", "browser", "os", "referer"]).optional(),
+            excludeBots: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, (args) => client.api("/visits", { query: queryOf(args) }));
+    register("get_redirect_rules", {
+        description: "List dynamic redirect rules configured for a short URL.",
+        inputSchema: shortCodeIdentity,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ shortCode, domain }) => client.api(`/short-urls/${encodeURIComponent(shortCode)}/redirect-rules`, {
+        query: { domain },
+    }));
+    register("set_redirect_rules", {
+        description: "Replace the dynamic redirect rules for a short URL. Rules are evaluated by Shlink in their provided order.",
+        inputSchema: {
+            ...shortCodeIdentity,
+            redirectRules: z.array(z.record(z.unknown())).describe("Shlink redirect-rule objects"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, ({ shortCode, domain, redirectRules }) => client.api(`/short-urls/${encodeURIComponent(shortCode)}/redirect-rules`, {
+        method: "POST",
+        query: { domain },
+        body: { redirectRules },
+    }));
+    register("get_tag_visits", {
+        description: "List visits associated with short URLs carrying a specific tag.",
+        inputSchema: { tag: z.string().min(1), ...visitFilters },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ tag, ...query }) => client.api(`/tags/${encodeURIComponent(tag)}/visits`, { query: queryOf(query) }));
+    register("get_domain_visits", {
+        description: "List visits for short URLs under a specific domain.",
+        inputSchema: { domain: z.string().min(1), ...visitFilters },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ domain, ...query }) => client.api(`/domains/${encodeURIComponent(domain)}/visits`, { query: queryOf(query) }));
+    register("list_orphan_visits", {
+        description: "List visits that did not resolve to a valid short URL.",
+        inputSchema: visitFilters,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, (args) => client.api("/visits/orphan", { query: queryOf(args) }));
+    register("list_non_orphan_visits", {
+        description: "List visits that belong to valid short URLs.",
+        inputSchema: visitFilters,
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, (args) => client.api("/visits/non-orphan", { query: queryOf(args) }));
+    register("rename_tag", {
+        description: "Rename a tag everywhere it is used.",
+        inputSchema: {
+            oldName: z.string().min(1),
+            newName: z.string().min(1),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, (body) => client.api("/tags", { method: "PUT", body }));
+    register("delete_tags", {
+        description: "Delete one or more tags. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.",
+        inputSchema: {
+            tags: z.array(z.string().min(1)).min(1),
+            confirm: z.literal(true),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async ({ tags }) => {
+        if (!config.allowDestructive) {
+            throw new Error("Tag deletion is disabled. Set SHLINK_ALLOW_DESTRUCTIVE=true to enable it.");
+        }
+        await client.api("/tags", { method: "DELETE", query: { tags } });
+        return { deleted: true, tags };
+    });
+    register("set_domain_redirects", {
+        description: "Configure optional fallback redirects for the base URL, invalid short URLs, and regular 404 paths.",
+        inputSchema: {
+            baseUrlRedirect: z.string().url().nullable().optional(),
+            invalidShortUrlRedirect: z.string().url().nullable().optional(),
+            regular404Redirect: z.string().url().nullable().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, (body) => client.api("/domains/redirects", { method: "PATCH", body }));
+    register("delete_short_url_visits", {
+        description: "Permanently erase visit history for one short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.",
+        inputSchema: { ...shortCodeIdentity, confirm: z.literal(true) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async ({ shortCode, domain }) => {
+        if (!config.allowDestructive) {
+            throw new Error("Visit deletion is disabled. Set SHLINK_ALLOW_DESTRUCTIVE=true to enable it.");
+        }
+        const response = await client.api(`/short-urls/${encodeURIComponent(shortCode)}/visits`, {
+            method: "DELETE",
+            query: { domain },
+        });
+        return { deleted: true, shortCode, domain: domain ?? null, response };
+    });
+    register("delete_orphan_visits", {
+        description: "Permanently erase all orphan visits. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.",
+        inputSchema: { confirm: z.literal(true) },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+    }, async () => {
+        if (!config.allowDestructive) {
+            throw new Error("Visit deletion is disabled. Set SHLINK_ALLOW_DESTRUCTIVE=true to enable it.");
+        }
+        const response = await client.api("/visits/orphan", { method: "DELETE" });
+        return { deleted: true, response };
+    });
+    register("get_mercure_info", {
+        description: "Get Shlink's Mercure real-time integration information when configured.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, () => client.api("/mercure-info"));
+    register("get_qr_code_url", {
+        description: "Build the public Shlink QR-code image URL for a short code. This returns a URL rather than downloading binary image data.",
+        inputSchema: {
+            ...shortCodeIdentity,
+            size: z.number().int().min(50).max(1000).optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, ({ shortCode, domain, size }) => {
+        const origin = domain ? new URL(config.baseUrl) : null;
+        if (origin && domain)
+            origin.hostname = domain;
+        const base = (origin?.toString() ?? config.baseUrl).replace(/\/+$/, "");
+        const suffix = size ? `/qr-code/${size}` : "/qr-code";
+        return { qrCodeUrl: `${base}/${encodeURIComponent(shortCode)}${suffix}` };
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/shlink/client.d.ts

@@ -0,0 +1,21 @@
+import type { Config } from "../config.js";
+export declare class ShlinkError extends Error {
+    readonly status?: number | undefined;
+    readonly requestId?: string | undefined;
+    readonly problemType?: string | undefined;
+    constructor(message: string, status?: number | undefined, requestId?: string | undefined, problemType?: string | undefined);
+}
+export type QueryValue = string | number | boolean | undefined | null | string[];
+export type FetchLike = typeof fetch;
+export declare class ShlinkClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: Config, fetchImpl?: FetchLike);
+    health(): Promise<unknown>;
+    api(path: string, options?: {
+        method?: string;
+        query?: Record<string, QueryValue>;
+        body?: unknown;
+    }): Promise<unknown>;
+    private request;
+}

package/dist/shlink/client.js

@@ -0,0 +1,82 @@
+export class ShlinkError extends Error {
+    status;
+    requestId;
+    problemType;
+    constructor(message, status, requestId, problemType) {
+        super(message);
+        this.status = status;
+        this.requestId = requestId;
+        this.problemType = problemType;
+        this.name = "ShlinkError";
+    }
+}
+export class ShlinkClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    health() {
+        return this.request("/rest/health", { authenticated: false });
+    }
+    api(path, options = {}) {
+        return this.request(`/rest/v${this.config.apiVersion}${path}`, options);
+    }
+    async request(path, options = {}) {
+        const url = new URL(`${this.config.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            if (Array.isArray(value)) {
+                for (const item of value)
+                    url.searchParams.append(key, item);
+            }
+            else {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = { Accept: "application/json" };
+        if (options.authenticated !== false)
+            headers["X-Api-Key"] = this.config.apiKey;
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: options.method ?? "GET",
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(this.config.timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new ShlinkError(error instanceof Error ? `Could not reach Shlink: ${error.message}` : "Could not reach Shlink");
+        }
+        const requestId = response.headers.get("x-request-id") ?? undefined;
+        const text = await response.text();
+        let data = null;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                if (!response.ok) {
+                    throw new ShlinkError(`Shlink returned HTTP ${response.status}`, response.status, requestId);
+                }
+                data = text;
+            }
+        }
+        if (!response.ok) {
+            const problem = data && typeof data === "object" ? data : {};
+            const detail = typeof problem.detail === "string"
+                ? problem.detail
+                : typeof problem.title === "string"
+                    ? problem.title
+                    : `Shlink returned HTTP ${response.status}`;
+            throw new ShlinkError(detail, response.status, requestId, typeof problem.type === "string" ? problem.type : undefined);
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/shlink/client.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "xs-shlink-mcp",
+  "version": "0.1.0",
+  "description": "A Model Context Protocol server for Shlink",
+  "type": "module",
+  "bin": {
+    "xs-shlink-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node scripts/clean.mjs",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "npm run build && tsx --test tests/*.test.ts",
+    "check": "tsc -p tsconfig.json",
+    "validate": "npm run check && npm test",
+    "prepack": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "shlink",
+    "url-shortener"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "AlexGreenUK",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexGreenUK/XS-Shlink-MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlexGreenUK/XS-Shlink-MCP/issues"
+  },
+  "homepage": "https://github.com/AlexGreenUK/XS-Shlink-MCP#readme",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}