zulk-url-shortener

通过 MCP 进行实时分析和团队协作，实现高级 AI 优先 URL 缩短和管理。在缩短营销链接、跟踪 AI 交互或管理自定义域时使用。关键词：url、缩短器、分析、链接管理、mcp。

## 概述（中文）

通过 MCP 进行实时分析和团队协作，实现高级 AI 优先 URL 缩短和管理。在缩短营销链接、跟踪 AI 交互或管理自定义域时使用。关键词：url、缩短器、分析、链接管理、mcp。

## 原文

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

---

## 中文说明

# Zulk URL Shortener Skill

此技能使 AI 代理能够使用 Zu.lk MCP（Model Context Protocol）服务器管理短链接、组织和分析数据。

## 概述

Zu.lk 是一个以 AI 为先的高级 URL 缩短器，专为极速性能和无缝 AI 集成而设计。此技能将你的代理连接到 Zulk MCP 服务器，使其能够：

- 创建缩短的 URL（例如 `zu.lk/abcd`）
- 管理现有链接和营销活动
- 访问实时分析数据
- 管理组织并与团队成员协作

## 安装

要使用此技能，请将 Zulk MCP 服务器配置添加到你的 AI 助手的设置中（例如 `mcp.json` 或等效文件）。

### 配置选项

选择最适合你环境的传输方式：

#### 1. Streamable HTTP（推荐）

最快且最可靠的通信方式。

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

#### 2. SSE（Server-Sent Events）

为某些客户端专门提供的实时流式传输。

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

#### 3. Stdio（通过 mcp-remote 或 mcporter）

通过远程桥接使用标准输入/输出。

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

## 分步说明

1.  **准备工作**：确保你拥有 Zu.lk 账户或已准备好通过 Google 登录。
2.  **配置**：将上述某个 JSON 配置添加到你代理的 MCP 设置文件中。
3.  **认证**：当你首次运行诸如 "shorten this link" 的命令时，代理会呈现一个 OAuth URL。按照链接完成认证。
4.  **验证**：让代理 "List my recently created links" 以验证连接是否处于活动状态。
5.  **执行**：使用自然语言创建链接，例如 "Create a short link for https://google.com with alias 'my-search'"。

## 何时使用此技能

当用户要求执行以下操作时使用此技能：

- 缩短一个 URL
- 管理短链接
- 查看或更新现有短链接
- 管理组织
- 邀请或管理组织成员
- 检索链接分析数据
- 列出属于某组织的