Zulk URL Shortener Skill

This skill enables AI agents to manage short links, organizations, and analytics using the Zu.lk MCP (Model Context Protocol) server.

Overview

Zu.lk is an AI-first premium URL shortener designed for blazing-fast performance and seamless AI integration. This skill connects your agent to the Zulk MCP server, allowing it to:

Create shortened URLs (e.g., zu.lk/abcd)
Manage existing links and campaigns
Access real-time analytics
Manage organizations and collaborate with team members

Installation

To use this skill, add the Zulk MCP server configuration to your AI assistant's settings (e.g., mcp.json or equivalent).

Configuration Options

Choose the transport method that best fits your environment:

1. Streamable HTTP (Recommended)

Fastest and most reliable communication.

{
  "mcpServers": {
    "zulk-url-shortener": { "url": "https://mcp.zu.lk/mcp" }
  }
}

2. SSE (Server-Sent Events)

Real-time streaming specialized for certain clients.

{
  "mcpServers": {
    "zulk-url-shortener": { "url": "https://mcp.zu.lk/sse" }
  }
}

3. Stdio (via mcp-remote or mcporter)

Uses standard input/output via a remote bridge.

{
  "mcpServers": {
    "zulk-url-shortener": {
      "command": "npx",
      "args": ["mcporter", "https://mcp.zu.lk/mcp"]
    }
  }
}

Step-by-Step Instructions

Preparation: Ensure you have a Zu.lk account or are ready to sign in via Google.
Configuration: Add one of the JSON configurations above to your agent's MCP settings file.
Authentication: When you first run a command like "shorten this link", the agent will present an OAuth URL. Follow the link to authenticate.
Verification: Ask the agent "List my recently created links" to verify the connection is active.
Execution: Use natural language to create links, e.g., "Create a short link for https://google.com with alias 'my-search'".

When To Use This Skill

Use this skill when the user asks to:

shorten a URL
manage short links
view or update an existing short link
manage organizations
invite or manage organization members
retrieve link analytics
list links belonging to an organization

Available MCP Tools

The Zulk MCP server provides the following tools. Note that tool names use an underscore (_) instead of a dot:

Organization Management

zulk_get_organizations(): Returns all organizations that the authenticated user has access to.
zulk_create_organization(name: string): Creates a new organization with the authenticated user as owner.

Organization Members

zulk_get_organization_members(orgId: string): Returns all members of a specific organization.
zulk_add_organization_member(orgId: string, email: string, role?: "MANAGER" | "ADMIN" | "OWNER"): Adds a new member to an organization (requires ADMIN or OWNER role).
zulk_update_member_role(orgId: string, memberId: string, role: "MANAGER" | "ADMIN" | "OWNER"): Updates the role of a specific member in an organization.
zulk_remove_organization_member(orgId: string, memberId: string): Removes a member from an organization (requires ADMIN or OWNER role).

Link Management

zulk_get_organization_links(orgId: string): Returns all short links for a specific organization.
zulk_create_link(orgId: string, url: string, key?: string, length?: number, expiresAt?: string, password?: string, utmParams?: any): Creates a new short link for the given URL in the specified organization. (Note: length is 5-10, expiresAt and password are Pro plan features).
zulk_get_link(orgId: string, linkId: string): Returns details of a specific link by ID from the specified organization.
zulk_update_link(orgId: string, linkId: string, url: string, key: string, expiresAt?: string, password?: string): Updates an existing short link for the specified organization. (Note: expiresAt and password are Pro plan features).

Analytics

zulk_get_organization_analytics(orgId: string, dateFrom?: string, dateTo?: string, interval?: string): Returns click analytics data for an organization's links. (Defaults: dateFrom "-7d", dateTo "today", interval "day").

Common Workflows

Creating a Short Link

Determine which organization the link should belong to.
If the organization is not specified, call zulk_get_organizations to list available organizations.
Call zulk_create_link with the specific orgId and url.
Return the generated short link to the user.

Listing Links in an Organization

Identify the organization.
Call zulk_get_organization_links.
Return the list of links in a readable format.

Inviting a Member

Ensure the user has ADMIN or OWNER permissions.
Call zulk_add_organization_member with the organization ID and member details.
Confirm the member was successfully added.

Viewing Analytics

Identify the organization.
Call zulk_get_organization_analytics.
Summarize click metrics for the user.

Best Practices

Always verify the organization before creating or modifying links.
Prefer listing organizations if the user did not specify one.
Provide clean responses when returning links or analytics.
Clearly report permission errors when they occur.

Usage Examples

Creating a Link

Input: "Shorten https://github.com/Zu-lk/zulk-short-url-skill for my marketing team" Agent reasoning:

Identify the organization belonging to the marketing team.
Call zulk_create_link.
Return the generated short link. Output: "Generated short link: https://zu.lk/z-skill"

Checking Analytics

Input: "Show analytics for our links" Agent reasoning:

Determine the organization.
Call zulk_get_organization_analytics.
Summarize the click data. Output: "Your links received 1,240 clicks yesterday. Here is the breakdown..."

Edge Cases & Troubleshooting

Auth Failure: If authentication fails, ensure you are using the correct Google account. You may need to restart the agent to re-trigger the OAuth flow.
Alias Taken: If a custom alias is already in use, the agent should suggest an alternative or append a random string.
Rate Limits: If you exceed your plan's link limit, the MCP server will return an error indicating the limit has been reached.
Link Expiration: Ensure you check if the link has an expiration date if it suddenly stops working.