MCP ShortURL

Instructions

Implementation Reference

• tools/info_tools.py:6-70 (handler)

  Main implementation of shorturl_get_usage_guide tool. This async function is decorated with @mcp.tool() which registers it with the MCP server. It returns a comprehensive usage guide in markdown format covering available tools, examples, response structures, and best practices.

  @mcp.tool()
  async def shorturl_get_usage_guide() -> str:
      """Get a comprehensive guide for using the ShortURL tools.
  
      Provides detailed information on how to use the ShortURL tools
      effectively, including parameters, examples, and best practices.
  
      Returns:
          Complete usage guide for ShortURL tools.
      """
      return """# ShortURL Tools Usage Guide
  
  ## Available Tools
  
  ### URL Shortening
  **shorturl_create** - Shorten a single URL
  - url: The long URL to shorten (required, must start with http:// or https://)
  
  **shorturl_batch_create** - Shorten multiple URLs at once
  - urls: List of long URLs to shorten (max 10 per batch)
  
  ## Example Usage
  
  ### Shorten a Single URL
  ```
  shorturl_create(url="https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9")
  ```
  
  **Response:**
  ```json
  {
    "success": true,
    "data": {
      "url": "https://surl.id/1uHCs01xa5"
    }
  }
  ```
  
  ### Batch Shorten Multiple URLs
  ```
  shorturl_batch_create(urls=[
      "https://example.com/very-long-url-1",
      "https://example.com/very-long-url-2"
  ])
  ```
  
  ## Response Structure
  
  ### Successful Response
  - **success**: `true` - indicates the request was successful
  - **data.url**: The shortened URL (e.g., `https://surl.id/abc123`)
  
  ### Error Response
  - **success**: `false` - indicates an error occurred
  - **error.code**: Error code (e.g., `api_error`, `bad_request`)
  - **error.message**: Human-readable error description
  - **trace_id**: Request trace ID for debugging
  
  ## Notes
  - The service is **free** (0 credits per request)
  - Short URLs use the `surl.id` domain
  - Short URLs are permanent and redirect to the original URL
  - Only valid HTTP/HTTPS URLs can be shortened
  - Rate limiting applies to prevent abuse
  """

• tools/info_tools.py:1-5 (registration)

  Import statement that brings in the mcp server instance from core.server. The @mcp.tool() decorator on the function uses this instance to register the tool automatically when the module is imported.

  """Informational tools for ShortURL API."""
  
  from core.server import mcp

• tools/__init__.py:1-10 (registration)

  Tools module initialization that imports info_tools (containing shorturl_get_usage_guide). This import triggers the @mcp.tool() decorator execution, which registers the tool with the MCP server.

  """Tools module for MCP ShortURL server."""
  
  # Import all tools to register them with the MCP server
  from tools import info_tools, shorturl_tools
  
  __all__ = [
      "shorturl_tools",
      "info_tools",
  ]

• main.py:110-115 (registration)

  Main server initialization that imports the tools module. This triggers the registration of all tools including shorturl_get_usage_guide through the decorator system.

  # Import tools and prompts to register them
  safe_print("  Loading tools and prompts...")
  import prompts  # noqa: F401, I001
  import tools  # noqa: F401
  
  safe_print("  [OK] Tools and prompts loaded")

• prompts/__init__.py:44-49 (helper)

  Documentation in the prompts module that provides LLM guidance on when to use the shorturl_get_usage_guide tool. This helps LLMs understand the tool's purpose and appropriate usage scenarios.

  ## Usage Guide
  **Tool:** `shorturl_get_usage_guide`
  **Use when:**
  - User wants to understand how to use the tools
  - User needs examples or best practices