shorturl_batch_create

Instructions

Shortens multiple URLs at once, returning a mapping of original URLs
to their shortened versions. Useful for bulk URL shortening tasks.

Args:
    urls: A list of long URLs to shorten (max 10 per batch).

Returns:
    JSON response containing the mapping of original to shortened URLs.

Example:
    shorturl_batch_create(urls=["https://example.com/long-url-1", "https://example.com/long-url-2"])

Implementation Reference

• tools/shorturl_tools.py:67-137 (handler)

  The main handler function for the shorturl_batch_create tool. It accepts a list of URLs (max 10), validates each, calls client.shorten() per URL via the core API client, collects results with error handling for auth and API errors, and returns a JSON summary with total/successful/failed counts and per-URL results.

  @mcp.tool()
  async def shorturl_batch_create(
      urls: Annotated[
          list[str],
          Field(
              description="A list of long URLs to shorten. Each must be a valid HTTP or HTTPS URL. Maximum 10 URLs per batch."
          ),
      ],
  ) -> str:
      """Create short URLs for multiple long URLs in a single batch.
  
      Shortens multiple URLs at once, returning a mapping of original URLs
      to their shortened versions. Useful for bulk URL shortening tasks.
  
      Args:
          urls: A list of long URLs to shorten (max 10 per batch).
  
      Returns:
          JSON response containing the mapping of original to shortened URLs.
  
      Example:
          shorturl_batch_create(urls=["https://example.com/long-url-1", "https://example.com/long-url-2"])
      """
      if not urls:
          return json.dumps({"error": "Validation Error", "message": "URLs list is required"})
  
      if len(urls) > 10:
          return json.dumps(
              {
                  "error": "Validation Error",
                  "message": "Maximum 10 URLs per batch. Please split into smaller batches.",
              }
          )
  
      results = []
      for url in urls:
          if not url.startswith(("http://", "https://")):
              results.append(
                  {
                      "original_url": url,
                      "short_url": None,
                      "error": "URL must start with http:// or https://",
                  }
              )
              continue
  
          try:
              result = await client.shorten(content=url)
              short_url = result.get("data", {}).get("url", "") if result.get("success") else None
              entry: dict = {"original_url": url, "short_url": short_url}
              if not short_url:
                  entry["error"] = result.get("error", {}).get("message", "Unknown error")
              results.append(entry)
          except ShortURLAuthError as e:
              results.append({"original_url": url, "short_url": None, "error": e.message})
              break  # Auth errors affect all subsequent requests
          except (ShortURLAPIError, Exception) as e:
              msg = e.message if hasattr(e, "message") else str(e)
              results.append({"original_url": url, "short_url": None, "error": msg})
  
      successful = sum(1 for r in results if r.get("short_url"))
      return json.dumps(
          {
              "total": len(urls),
              "successful": successful,
              "failed": len(urls) - successful,
              "results": results,
          },
          ensure_ascii=False,
          indent=2,
      )

• tools/shorturl_tools.py:67-75 (schema)

  The function signature uses Pydantic Field annotations via Annotated type to define the input schema: a list[str] of URLs with a description stating max 10 URLs per batch.

  @mcp.tool()
  async def shorturl_batch_create(
      urls: Annotated[
          list[str],
          Field(
              description="A list of long URLs to shorten. Each must be a valid HTTP or HTTPS URL. Maximum 10 URLs per batch."
          ),
      ],
  ) -> str:

• main.py:112-113 (registration)

  Registration is triggered by importing the tools module (line 113), which loads tools/shorturl_tools.py. The @mcp.tool() decorator on the function (line 67) registers it with the FastMCP server instance.

  import prompts  # noqa: F401, I001
  import tools  # noqa: F401

• main.py:162-165 (registration)

  The tool is also listed in the server card JSON response under 'tools' with name 'shorturl_batch_create' and description 'Create multiple short URLs', used for Smithery/registry discovery.

  {
      "name": "shorturl_batch_create",
      "description": "Create multiple short URLs",
  },

• core/client.py:148-158 (helper)

  The underlying client.shorten() method that the handler calls for each URL. It sends a POST request to /shorturl with the long URL as the content field.

  async def shorten(self, content: str) -> dict[str, Any]:
      """Create a short URL from a long URL.
  
      Args:
          content: The long URL to shorten.
  
      Returns:
          API response dictionary containing the short URL.
      """
      logger.info(f"Shortening URL: {content[:80]}...")
      return await self.request("/shorturl", {"content": content})