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');
  }