U301 URL Shortener MCP Server

Instructions

Implementation Reference

• src/index.ts:62-97 (handler)

  The tool handler function registered with server.tool. It validates the input URLs array, limits to 200, makes a POST request to U301 bulk shorten endpoint, formats the results using helper functions, and returns success or error response.
  server.tool(toolName, toolDescription, { urls: inputSchema }, async(args) => { const urls = inputSchema.parse(args.urls); if (urls.length > 200) { throw new Error("Too many URLs provided"); } else if (urls.length === 0) { throw new Error("No URLs provided"); } try { const responseLinks = await U301Request<(ShortenedURL | ShortenedURLFailed)[]>(`/shorten/bulk?workspaceId=${workspaceId}`, { method: "POST", headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(urls.map((url) => ({ url: url.url, slug: url.slug, domain: shortenDomain, expiredAt: url.expiredAt, password: url.password, comment: url.comment, }))), }) if (!responseLinks) { throw new Error("No response from U301 API"); } return { content: [{ type: "text", text: formatResults(responseLinks) }], isError: false, } } catch (e) { return { content: [{ type: "text", text: `Error: ${e}` }], isError: true, } } })
• src/index.ts:31-48 (schema)

  Zod schema defining the input structure: an array of URL shortening requests, each with required 'url' and optional 'slug', 'expiredAt', 'password', 'comment'.
  const inputSchema = z.array(z.object({ url: z.string({ description: "URL to shorten e.g. https://example.com/very/long/url" }), slug: z.string({ description: "(optional) Custom slug for the shortened URL" }).optional(), expiredAt: z.string({ description: "(optional) Expiration date for the shortened URL, e.g. 2023-01-01T00:00:00Z", coerce: true, }).optional(), password: z.string({ description: "(optional) Password for the shortened URL" }).optional(), comment: z.string({ description: "(optional) Comment, displayed on the dashboard" }).optional(), }))
• src/index.ts:49-62 (registration)

  Tool name, detailed description, and registration call to server.tool with schema and handler.
  const toolName = "u301_shortening_urls_in_bulk" const toolDescription = `Use U301's short link service API to batch shorten long URLs. Custom domains are supported, with up to 200 URLs per request. You should provide as "{ urls: <URLItem>[]}" Current ShortLink domain is ${shortenDomain} URLItem Supported Parameters are` + [ "url: required, the URL to be shortened", `slug: optional, a custom slug for the shortened URL, the final shortened URL will be https://${shortenDomain}/<slug> if you leave it empty, random slug will create`, "expiredAt: optional, the expiration date for the shortened URL, e.g. 2023-01-01T00:00:00Z", "password: optional, a password for the shortened URL", "comment: optional, a comment, displayed on the dashboard" ].join("\n"); server.tool(toolName, toolDescription, { urls: inputSchema }, async(args) => {
• src/index.ts:98-113 (helper)

  Helper function for making authenticated HTTP requests to the U301 API, used by the handler for the bulk shorten call.
  async function U301Request<T>(url: string, options?: RequestInit): Promise<T | null> { options = options || {} as RequestInit; const originalHeaders = options?.headers || {}; options.headers = { 'User-Agent': USER_AGENT, 'Authorization': `Bearer ${U301_API_KEY}`, 'Accept-Encoding': 'gzip', 'Accept': 'application/json', ...originalHeaders }; const response = await fetch(U301_API_BASE + url, options); if (!response.ok) { throw new Error(`U301 API error: ${response.status} ${response.statusText}\n${await response.text()}`); } return (await response.json()) as T; }
• src/index.ts:144-165 (helper)

  Helper functions to check if a link shortening failed (type guard) and to format the results into a readable text output.
  function isFailedLink(link: ShortenedURL | ShortenedURLFailed): link is ShortenedURLFailed { return (link as ShortenedURLFailed).error !== undefined; } function formatResults(links: (ShortenedURL | ShortenedURLFailed)[]): string { return (links || []).map((link, i) => { if (isFailedLink(link)) { return `[${i}]: Failed to shorten ${link.url}: ${link.error} - ${link.message}`; } const items = [ `Index: ${i}`, `Id: ${link.id}`, `Original URL: ${link.url}`, `Short Link: ${link.shortLink}`, `Domain: ${link.domain}`, `Reused: ${link.isReused ? 'Yes' : 'No'}`, `Comment: ${link.comment || 'N/A'}`, ]; return items.join('\n') }).join('\n---\n'); }