yhn-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 y.hn
+
+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,91 @@
+# yhn-mcp
+
+Model Context Protocol server for [y.hn](https://y.hn). Lets Claude Code, Cursor, Cline, and any other MCP-aware AI agent create and manage short links by talking to the y.hn API.
+
+## Quick start
+
+1. Generate an API key at <https://y.hn/dashboard/settings>.
+2. Add the server to your MCP client config (examples below).
+3. Restart the client. Type something like *"Shorten https://example.com with custom slug demo"* — the agent now has tools.
+
+No global install needed; `npx` fetches the package on demand.
+
+### Claude Code
+
+Add to `~/.claude.json` (or your project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "yhn": {
+      "command": "npx",
+      "args": ["-y", "yhn-mcp"],
+      "env": {
+        "YHN_API_KEY": "yhn_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+`Settings → MCP → New MCP Server`, paste the same JSON.
+
+### Cline / Continue / other MCP clients
+
+Same JSON shape, drop into the client's MCP config. Anything that speaks stdio MCP works.
+
+## Available tools
+
+| Tool | Purpose |
+|---|---|
+| `whoami` | Verify the API key, return plan + email |
+| `create_link` | Create a short link (url, optional customSlug, password, expiresAt, OG, UTM, tags) |
+| `list_links` | Paginated list with search / folder / tag filter |
+| `get_link` | Fetch one link by ID |
+| `update_link` | Patch any field (retarget, expire, archive, move folder) |
+| `delete_link` | Permanent delete |
+| `get_link_stats` | Time series + geo + device + referrer for one link |
+| `bulk_create_links` | Create many links in one call (CSV import / migration) |
+| `get_qr_url` | Returns a signed-style QR PNG URL for a link |
+| `list_folders` / `create_folder` | Folder management |
+| `list_tags` / `create_tag` | Tag management |
+| `analytics_overview` | Account-wide totals + top links |
+| `analytics_geo` | Country/city click breakdown |
+| `list_conversion_goals` / `track_conversion` | Server-side conversion events |
+| `list_webhooks` / `create_webhook` | Webhook subscriptions |
+| `list_domains` | Custom domains (Pro+) |
+
+More endpoints (A/B test, geo/device routing rules, pixels, marketplace) are exposed via the raw [y.hn API](https://y.hn/docs); ask if you'd like a tool for them.
+
+## Configuration
+
+| env var | default | purpose |
+|---|---|---|
+| `YHN_API_KEY` | *required* | Your y.hn API key (`yhn_...`) |
+| `YHN_BASE_URL` | `https://y.hn/api` | Override for self-hosted / staging |
+
+## Examples
+
+Once installed, you can prompt naturally:
+
+> Shorten `https://huggingface.co/blog/agents` and put it in folder `Reading list`.
+
+> Bulk-shorten the URLs in `/path/to/links.txt`, set utm_source=newsletter on all of them, and email me the resulting CSV.
+
+> What's my top performing link this week? Pull stats and tell me where the clicks came from.
+
+The agent picks the right tool, calls it, and continues.
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/index.js   # smoke test (will exit because YHN_API_KEY missing)
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+/**
+ * y.hn MCP server.
+ *
+ * Lets AI agents (Claude Code, Cursor, Cline, etc.) create and manage y.hn short
+ * links over the Model Context Protocol. Auth is via your y.hn API key.
+ *
+ * Get a key at https://y.hn/dashboard/settings, then set YHN_API_KEY before
+ * launching this server.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+const BASE_URL = (process.env.YHN_BASE_URL || 'https://y.hn/api').replace(/\/+$/, '');
+const API_KEY = process.env.YHN_API_KEY;
+if (!API_KEY) {
+    process.stderr.write('YHN_API_KEY is required.\n' +
+        'Generate one at https://y.hn/dashboard/settings, then add it to your\n' +
+        'MCP client config (Claude Code, Cursor, Cline, etc.).\n');
+    process.exit(1);
+}
+async function api(method, path, body, query) {
+    let url = `${BASE_URL}${path}`;
+    if (query) {
+        const sp = new URLSearchParams();
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== null && v !== '')
+                sp.set(k, String(v));
+        }
+        const qs = sp.toString();
+        if (qs)
+            url += `?${qs}`;
+    }
+    const res = await fetch(url, {
+        method,
+        headers: {
+            'x-api-key': API_KEY,
+            ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let parsed = text;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // leave as text
+        }
+    }
+    if (!res.ok) {
+        const errMsg = parsed?.error ||
+            (typeof parsed === 'string' ? parsed : '') ||
+            res.statusText;
+        throw new Error(`yhn ${method} ${path} → ${res.status} ${errMsg}`);
+    }
+    return parsed;
+}
+const tools = [
+    // ── Account / auth ────────────────────────────────────────────────────
+    {
+        name: 'whoami',
+        description: 'Verify the configured y.hn API key and return account info: email, plan tier (free/pro/business), name. Use this first if anything feels off.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/settings/api-key'),
+    },
+    // ── Links: CRUD ───────────────────────────────────────────────────────
+    {
+        name: 'create_link',
+        description: 'Create a new short link. Returns { shortUrl, slug, id, targetUrl }. ' +
+            "Tip: customSlug is optional — if omitted, y.hn generates a 6-char slug. " +
+            "Free plan: 25 links/month, links auto-expire in 30 days, no password, slugs must be ≥6 chars. " +
+            "Pro+: unlimited links, custom expiry, password, shorter slugs. " +
+            'Pass UTM and OG fields directly — y.hn appends UTM to the redirect target and serves OG tags on share preview.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Target (long) URL to shorten. Must be http(s).' },
+                customSlug: {
+                    type: 'string',
+                    description: 'Optional custom slug. a-z0-9- only. ≥6 chars on free; ≥3 chars on Pro.',
+                },
+                password: { type: 'string', description: 'Pro+: password-protect the redirect.' },
+                expiresAt: { type: 'string', description: 'Pro+: ISO 8601 expiration timestamp.' },
+                fallbackUrl: {
+                    type: 'string',
+                    description: 'Where to send visitors when the link expires or hits maxClicks.',
+                },
+                maxClicks: { type: 'number', description: 'Deactivate after N clicks.' },
+                ogTitle: { type: 'string', description: 'Open Graph title for social previews.' },
+                ogDescription: { type: 'string', description: 'Open Graph description.' },
+                ogImage: { type: 'string', description: 'Open Graph image URL.' },
+                utmSource: { type: 'string' },
+                utmMedium: { type: 'string' },
+                utmCampaign: { type: 'string' },
+                tagIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tag IDs to attach (use list_tags / create_tag to manage tags).',
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+        run: (args) => api('POST', '/links', args),
+    },
+    {
+        name: 'list_links',
+        description: 'List the authenticated user\'s links, paginated. Returns { links, total, page, totalPages }. ' +
+            'Each link has slug, targetUrl, clicks, createdAt, archived, suspicious, and full metadata.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: { type: 'number', description: 'Page number (default 1).' },
+                limit: { type: 'number', description: 'Page size (default 20, max 100).' },
+                search: {
+                    type: 'string',
+                    description: 'Search across slug, targetUrl, title, tags (case-insensitive substring).',
+                },
+                folderId: { type: 'string', description: 'Filter to a specific folder.' },
+                tag: { type: 'string', description: 'Filter to links containing this tag substring.' },
+            },
+            additionalProperties: false,
+        },
+        run: (args) => api('GET', '/links', undefined, args),
+    },
+    {
+        name: 'get_link',
+        description: 'Get a single link by linkId (UUID). Returns full link object including rules, conversions, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: { linkId: { type: 'string' } },
+            required: ['linkId'],
+            additionalProperties: false,
+        },
+        run: ({ linkId }) => api('GET', `/links/${linkId}`),
+    },
+    {
+        name: 'update_link',
+        description: 'Update a link. Pass linkId plus any fields to change. Same fields as create_link except url (use targetUrl to retarget).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                linkId: { type: 'string' },
+                targetUrl: { type: 'string' },
+                password: { type: 'string' },
+                expiresAt: { type: 'string' },
+                fallbackUrl: { type: 'string' },
+                maxClicks: { type: 'number' },
+                ogTitle: { type: 'string' },
+                ogDescription: { type: 'string' },
+                ogImage: { type: 'string' },
+                utmSource: { type: 'string' },
+                utmMedium: { type: 'string' },
+                utmCampaign: { type: 'string' },
+                archived: { type: 'boolean', description: 'Set true to disable the link (410 Gone).' },
+                folderId: { type: 'string', description: 'Move into a folder (or null to remove).' },
+            },
+            required: ['linkId'],
+            additionalProperties: false,
+        },
+        run: ({ linkId, ...patch }) => api('PATCH', `/links/${linkId}`, patch),
+    },
+    {
+        name: 'delete_link',
+        description: 'Permanently delete a link by linkId. Click history is preserved separately.',
+        inputSchema: {
+            type: 'object',
+            properties: { linkId: { type: 'string' } },
+            required: ['linkId'],
+            additionalProperties: false,
+        },
+        run: ({ linkId }) => api('DELETE', `/links/${linkId}`),
+    },
+    {
+        name: 'get_link_stats',
+        description: 'Get analytics for a single link: clicks over time, geo breakdown, device, browser, referrer. Period is "24h" | "7d" | "30d" | "all" (default 30d).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                linkId: { type: 'string' },
+                period: { type: 'string', enum: ['24h', '7d', '30d', 'all'] },
+            },
+            required: ['linkId'],
+            additionalProperties: false,
+        },
+        run: ({ linkId, ...q }) => api('GET', `/links/${linkId}/stats`, undefined, q),
+    },
+    {
+        name: 'bulk_create_links',
+        description: 'Create many links in one request. Pass `links: CreateLinkParams[]`. Useful for migrating from another shortener or batching from a CSV. Returns { links, errors }.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                links: {
+                    type: 'array',
+                    items: { type: 'object' },
+                    description: 'Array of CreateLinkParams (same shape as create_link input).',
+                },
+            },
+            required: ['links'],
+            additionalProperties: false,
+        },
+        run: (args) => api('POST', '/links/bulk', args),
+    },
+    // ── QR ────────────────────────────────────────────────────────────────
+    {
+        name: 'get_qr_url',
+        description: 'Returns a URL to the QR-code image PNG for a link. ' +
+            'You can embed the URL directly (`<img src=...>`) or fetch it. The endpoint requires the same API key. ' +
+            'Customise size (px) and dark/light colors via params.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                linkId: { type: 'string' },
+                size: { type: 'number', description: 'PNG size in pixels (default 256).' },
+                color: { type: 'string', description: 'Foreground hex (e.g. #000000).' },
+                background: { type: 'string', description: 'Background hex (e.g. #ffffff).' },
+            },
+            required: ['linkId'],
+            additionalProperties: false,
+        },
+        run: ({ linkId, ...q }) => {
+            const sp = new URLSearchParams();
+            for (const [k, v] of Object.entries(q)) {
+                if (v !== undefined && v !== null && v !== '')
+                    sp.set(k, String(v));
+            }
+            const qs = sp.toString();
+            return Promise.resolve({
+                qrUrl: `${BASE_URL}/links/${linkId}/qr${qs ? `?${qs}` : ''}`,
+                note: 'Send the x-api-key header when fetching this URL.',
+            });
+        },
+    },
+    // ── Folders ──────────────────────────────────────────────────────────
+    {
+        name: 'list_folders',
+        description: 'List all folders for the authenticated user. Returns { folders } with link counts.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/folders'),
+    },
+    {
+        name: 'create_folder',
+        description: 'Create a folder. Color is optional hex (default indigo).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                color: { type: 'string', description: 'Hex color, e.g. #6366f1.' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+        run: (args) => api('POST', '/folders', args),
+    },
+    // ── Tags ──────────────────────────────────────────────────────────────
+    {
+        name: 'list_tags',
+        description: 'List all tags for the authenticated user.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/tags'),
+    },
+    {
+        name: 'create_tag',
+        description: 'Create a tag. 409 if a tag with the same name exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                color: { type: 'string', description: 'Hex color.' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        },
+        run: (args) => api('POST', '/tags', args),
+    },
+    // ── Analytics ────────────────────────────────────────────────────────
+    {
+        name: 'analytics_overview',
+        description: 'Account-wide analytics: today/week/month/all-time clicks, unique visitors, growth rate, top links, plan tier.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/analytics/overview'),
+    },
+    {
+        name: 'analytics_geo',
+        description: 'Geographic breakdown of clicks across all the user\'s links.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                period: { type: 'string', enum: ['24h', '7d', '30d', 'all'] },
+            },
+            additionalProperties: false,
+        },
+        run: (args) => api('GET', '/analytics/geo', undefined, args),
+    },
+    // ── Conversion goals ──────────────────────────────────────────────────
+    {
+        name: 'list_conversion_goals',
+        description: 'List conversion goals + per-goal totals (count, revenue).',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/conversions'),
+    },
+    {
+        name: 'track_conversion',
+        description: 'Server-side conversion event for a goal. Pass linkId or sessionId to attribute. ' +
+            'Use this in your webhook from Stripe, Paddle, etc. to record purchase/signup events.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                goalId: { type: 'string' },
+                linkId: { type: 'string', description: 'The yhn link that drove this conversion.' },
+                sessionId: { type: 'string', description: 'Visitor session ID (alternative to linkId).' },
+                revenue: { type: 'number', description: 'Optional revenue attributable to this conversion.' },
+                metadata: { type: 'object', description: 'Free-form JSON metadata.' },
+            },
+            required: ['goalId'],
+            additionalProperties: false,
+        },
+        run: ({ goalId, ...payload }) => api('POST', `/conversions/${goalId}/track`, payload),
+    },
+    // ── Webhooks ──────────────────────────────────────────────────────────
+    {
+        name: 'list_webhooks',
+        description: 'List configured webhooks for this account.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/webhooks'),
+    },
+    {
+        name: 'create_webhook',
+        description: 'Register a webhook URL. y.hn POSTs JSON events with HMAC-SHA256 signature (x-yhn-signature header). ' +
+            'Events: "create" (link created), "click" (visitor clicked), "expire", "delete".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'Your endpoint that will receive events.' },
+                events: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['create', 'click', 'expire', 'delete'] },
+                    description: 'Subscribe to these event types.',
+                },
+            },
+            required: ['url', 'events'],
+            additionalProperties: false,
+        },
+        run: (args) => api('POST', '/webhooks', args),
+    },
+    // ── Domains ───────────────────────────────────────────────────────────
+    {
+        name: 'list_domains',
+        description: 'List custom domains for this account (Pro+ only).',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        run: () => api('GET', '/domains'),
+    },
+];
+const toolByName = new Map(tools.map((t) => [t.name, t]));
+const server = new Server({ name: 'yhn-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const tool = toolByName.get(req.params.name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }],
+        };
+    }
+    try {
+        const result = await tool.run((req.params.arguments ?? {}));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [{ type: 'text', text: msg }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`yhn-mcp connected. base=${BASE_URL}\n`);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "yhn-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for y.hn — lets Claude Code, Cursor, Cline and other AI agents create and manage short links.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "yhn-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "y.hn",
+    "yhn",
+    "url-shortener",
+    "short-link",
+    "claude",
+    "cursor",
+    "ai-agent"
+  ],
+  "homepage": "https://y.hn",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/97wow/yhn",
+    "directory": "sdk/mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}