picoli-mcp 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# picoli-mcp
+
+MCP server for [picoli.site](https://picoli.site) — URL shortening and click analytics for AI agents.
+
+Shorten URLs, track clicks, and analyze link performance directly from your AI assistant.
+
+## Setup
+
+### 1. Get your API key
+
+Create an account at [picoli.site](https://picoli.site) and get your API key from the dashboard.
+
+### 2. Configure your MCP client
+
+#### Claude Desktop / Claude Code
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "picoli": {
+      "command": "npx",
+      "args": ["-y", "picoli-mcp"],
+      "env": {
+        "PICOLI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "picoli": {
+      "command": "npx",
+      "args": ["-y", "picoli-mcp"],
+      "env": {
+        "PICOLI_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `shorten_url`
+
+Create a short URL with an optional custom slug.
+
+**Example prompts:**
+- "Shorten https://example.com/very-long-article-url"
+- "Create a short link for https://my-site.com with slug 'launch'"
+
+### `shorten_urls`
+
+Create multiple short URLs at once (up to 500).
+
+**Example prompts:**
+- "Shorten these 3 URLs: ..."
+
+### `get_link_stats`
+
+Get click statistics for specific links (bot traffic excluded).
+
+**Example prompts:**
+- "How many clicks did my 'launch' link get?"
+- "Show me stats for these slugs: launch, demo, blog-post"
+
+### `list_links`
+
+List all shortened URLs with click counts and pagination.
+
+**Example prompts:**
+- "Show me all my short links"
+- "List my links sorted by clicks"
+
+### `get_analytics`
+
+Get analytics overview: top 10 links, daily click trends, and totals.
+
+**Example prompts:**
+- "Show me my link analytics for this week"
+- "What are my top performing links?"
+- "Give me click stats from 2026-01-01 to 2026-01-31"
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `PICOLI_API_KEY` | Yes | — | Your picoli.site API key |
+| `PICOLI_BASE_URL` | No | `https://picoli.site` | API base URL (for self-hosted instances) |
+
+## Development
+
+```bash
+git clone https://github.com/yun/picoli-mcp.git
+cd picoli-mcp
+npm install
+npm run build
+```
+
+Test locally:
+
+```bash
+PICOLI_API_KEY=your-key npx tsx src/index.ts
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+declare const ConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    apiKey: string;
+    baseUrl: string;
+}, {
+    apiKey: string;
+    baseUrl?: string | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+const ConfigSchema = z.object({
+    apiKey: z.string().min(1, "PICOLI_API_KEY is required. Get your API key at https://picoli.site"),
+    baseUrl: z.string().url().default("https://picoli.site"),
+});
+export function loadConfig() {
+    const result = ConfigSchema.safeParse({
+        apiKey: process.env.PICOLI_API_KEY,
+        baseUrl: process.env.PICOLI_BASE_URL,
+    });
+    if (!result.success) {
+        const errors = result.error.issues.map((i) => `  - ${i.message}`).join("\n");
+        console.error(`picoli-mcp: Configuration error:\n${errors}`);
+        console.error("\nSet PICOLI_API_KEY in your MCP server configuration.");
+        console.error("Get your API key at https://picoli.site");
+        process.exit(1);
+    }
+    return result.data;
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { registerTools } from "./tools.js";
+const config = loadConfig();
+const server = new McpServer({
+    name: "picoli-mcp",
+    version: "1.0.0",
+});
+registerTools(server, config);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("picoli-mcp server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Config } from "./config.js";
+export declare function registerTools(server: McpServer, config: Config): void;

package/dist/tools.js

@@ -0,0 +1,241 @@
+import { z } from "zod";
+async function picoliRequest(config, path, options = {}) {
+    const url = `${config.baseUrl}${path}`;
+    return fetch(url, {
+        ...options,
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": config.apiKey,
+            ...options.headers,
+        },
+    });
+}
+export function registerTools(server, config) {
+    // ── shorten_url ──────────────────────────────────────
+    server.registerTool("shorten_url", {
+        title: "Shorten URL",
+        description: "Create a short URL using picoli.site. Optionally specify a custom slug. Returns the shortened URL and slug.",
+        inputSchema: z.object({
+            url: z.string().url().describe("The destination URL to shorten"),
+            slug: z
+                .string()
+                .optional()
+                .describe("Optional custom slug (e.g. 'my-link'). If not provided, a random slug is generated."),
+        }),
+    }, async ({ url, slug }) => {
+        const link = { url };
+        if (slug)
+            link.slug = slug;
+        const res = await picoliRequest(config, "/api/links/bulk", {
+            method: "POST",
+            body: JSON.stringify({ links: [link] }),
+        });
+        if (!res.ok) {
+            const error = await res.text();
+            return {
+                content: [{ type: "text", text: `Error: ${res.status} - ${error}` }],
+                isError: true,
+            };
+        }
+        const data = await res.json();
+        if (data.errors?.length > 0) {
+            return {
+                content: [
+                    { type: "text", text: `Error: ${data.errors[0].error}` },
+                ],
+                isError: true,
+            };
+        }
+        const created = data.links[0];
+        const shortUrl = `${config.baseUrl}/${created.slug}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        shortUrl,
+                        slug: created.slug,
+                        destinationUrl: created.destination_url,
+                        createdAt: created.created_at,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    // ── shorten_urls ─────────────────────────────────────
+    server.registerTool("shorten_urls", {
+        title: "Shorten Multiple URLs",
+        description: "Create multiple short URLs at once (up to 500). Each URL can have an optional custom slug.",
+        inputSchema: z.object({
+            links: z
+                .array(z.object({
+                url: z.string().url().describe("The destination URL"),
+                slug: z.string().optional().describe("Optional custom slug"),
+            }))
+                .min(1)
+                .max(500)
+                .describe("Array of URLs to shorten"),
+        }),
+    }, async ({ links }) => {
+        const res = await picoliRequest(config, "/api/links/bulk", {
+            method: "POST",
+            body: JSON.stringify({ links }),
+        });
+        if (!res.ok) {
+            const error = await res.text();
+            return {
+                content: [{ type: "text", text: `Error: ${res.status} - ${error}` }],
+                isError: true,
+            };
+        }
+        const data = await res.json();
+        const results = (data.links || []).map((l) => ({
+            shortUrl: `${config.baseUrl}/${l.slug}`,
+            slug: l.slug,
+            destinationUrl: l.destination_url,
+        }));
+        const summary = {
+            created: data.created,
+            errors: data.errors?.length || 0,
+            links: results,
+        };
+        if (data.errors?.length > 0) {
+            summary.errorDetails = data.errors;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    // ── get_link_stats ───────────────────────────────────
+    server.registerTool("get_link_stats", {
+        title: "Get Link Stats",
+        description: "Get click statistics for one or more short links by their slugs. Returns human click counts (bot traffic excluded).",
+        inputSchema: z.object({
+            slugs: z
+                .array(z.string())
+                .min(1)
+                .max(500)
+                .describe("Array of slugs to get stats for (e.g. ['my-link', 'abc123'])"),
+        }),
+    }, async ({ slugs }) => {
+        const res = await picoliRequest(config, "/api/stats/batch", {
+            method: "POST",
+            body: JSON.stringify({ slugs }),
+        });
+        if (!res.ok) {
+            const error = await res.text();
+            return {
+                content: [{ type: "text", text: `Error: ${res.status} - ${error}` }],
+                isError: true,
+            };
+        }
+        const data = await res.json();
+        const stats = (data.stats || []).map((s) => ({
+            slug: s.slug,
+            shortUrl: `${config.baseUrl}/${s.slug}`,
+            destinationUrl: s.destination_url,
+            clicks: s.human_clicks,
+            createdAt: s.created_at,
+        }));
+        // Identify slugs with no data
+        const foundSlugs = new Set(stats.map((s) => s.slug));
+        const notFound = slugs.filter((s) => !foundSlugs.has(s));
+        const result = { stats };
+        if (notFound.length > 0) {
+            result.notFound = notFound;
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // ── list_links ───────────────────────────────────────
+    server.registerTool("list_links", {
+        title: "List Links",
+        description: "List all shortened URLs with their click counts. Supports pagination.",
+        inputSchema: z.object({
+            page: z
+                .number()
+                .int()
+                .positive()
+                .default(1)
+                .describe("Page number (default: 1)"),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Items per page (default: 20, max: 100)"),
+        }),
+    }, async ({ page, limit }) => {
+        const res = await picoliRequest(config, `/api/links?page=${page}&limit=${limit}`);
+        if (!res.ok) {
+            const error = await res.text();
+            return {
+                content: [{ type: "text", text: `Error: ${res.status} - ${error}` }],
+                isError: true,
+            };
+        }
+        const data = await res.json();
+        const links = (data.data || []).map((l) => ({
+            shortUrl: `${config.baseUrl}/${l.slug}`,
+            slug: l.slug,
+            destinationUrl: l.destination_url,
+            clicks: l.clicks,
+            createdAt: l.created_at,
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ links, pagination: data.pagination }, null, 2),
+                },
+            ],
+        };
+    });
+    // ── get_analytics ────────────────────────────────────
+    server.registerTool("get_analytics", {
+        title: "Get Analytics",
+        description: "Get analytics overview: top 10 links by clicks, daily click stats, and total link count. Defaults to last 7 days.",
+        inputSchema: z.object({
+            start_date: z
+                .string()
+                .optional()
+                .describe("Start date in YYYY-MM-DD format (default: 7 days ago)"),
+            end_date: z
+                .string()
+                .optional()
+                .describe("End date in YYYY-MM-DD format (default: today)"),
+        }),
+    }, async ({ start_date, end_date }) => {
+        const params = new URLSearchParams();
+        if (start_date)
+            params.set("start_date", start_date);
+        if (end_date)
+            params.set("end_date", end_date);
+        const query = params.toString();
+        const path = `/api/stats${query ? `?${query}` : ""}`;
+        const res = await picoliRequest(config, path);
+        if (!res.ok) {
+            const error = await res.text();
+            return {
+                content: [{ type: "text", text: `Error: ${res.status} - ${error}` }],
+                isError: true,
+            };
+        }
+        const data = await res.json();
+        const result = {
+            dateRange: data.date_filter,
+            totalLinks: data.total_links,
+            top10: (data.top_10 || []).map((t) => ({
+                shortUrl: `${config.baseUrl}/${t.slug}`,
+                slug: t.slug,
+                clicks: t.human_clicks,
+            })),
+            dailyStats: data.daily_stats || [],
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "picoli-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for picoli.site - URL shortening and click analytics",
+  "type": "module",
+  "bin": {
+    "picoli-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "url-shortener",
+    "analytics",
+    "picoli",
+    "ai-tools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amaterous/picoli-mcp"
+  }
+}