zulk-url-shortener

# 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.

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

#### 2. SSE (Server-Sent Events)

Real-time streaming specialized for certain clients.

```json
{
  "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.

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

## Step-by-Step Instructions

1.  **Preparation**: Ensure you have a Zu.lk account or are ready to sign in via Google.
2.  **Configuration**: Add one of the JSON configurations above to your agent's MCP settings file.
3.  **Authentication**: When you first run a command like "shorten this link", the agent will present an OAuth URL. Follow the link to authenticate.
4.  **Verification**: Ask the agent "List my recently created links" to verify the connection is active.
5.  **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

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

### Listing Links in an Organization

1. Identify the organization.
2. Call `zulk_get_organization_links`.
3. Return the list of links in a readable format.

### Inviting a Member

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

### Viewing Analytics

1. Identify the organization.
2. Call `zulk_get_organization_analytics`.
3. 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**:

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

### Checking Analytics

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

1. Determine the organization.
2. Call `zulk_get_organization_analytics`.
3. 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.

## References

- [Official Website](https://zu.lk)
- [MCP Documentation](https://zu.lk/-/mcp)