MCP 服务器

DWZ Short URL MCP Server

Enables AI assistants to create, manage, and analyze short URLs through complete URL shortening functionality. Supports batch operations, custom domains, click statistics, and comprehensive link management.

README

Mliev 短网址 MCP 客户端

基于 MCP（Model Context Protocol）协议的短网址管理客户端，为 AI 助手提供完整的短网址生成、管理和统计功能。

✨ 功能特性

🔗 短网址创建: 支持自定义域名、短代码、标题和描述
📋 批量操作: 一次性创建多个短网址，提高效率
🔍 搜索筛选: 支持域名筛选和关键词搜索
📊 统计分析: 获取详细的点击统计信息
🛡️ 错误处理: 完善的错误处理和重试机制
🔒 安全认证: 基于 Bearer Token 的 API 认证

🚀 快速开始

环境要求

Node.js >= 18.0.0
npm 或 yarn

直接使用MCP

{
  "mcpServers": {
    "dwz-mcp": {
      "name": "dwz-mcp",
      "type": "stdio",
      "isActive": true,
      "registryUrl": "",
      "command": "npx",
      "args": [
        "-y",
        "@muleiwu/dwz-mcp"
      ],
      "env": {
        "REMOTE_BASE_URL": "您的短网址服务地址",
        "REMOTE_API_KEY": "apiKey"
      }
    }
  }
}

安装依赖

npm install

配置环境变量

复制环境变量模板并配置：

cp .env.example .env

编辑 .env 文件：

# 远程短网址服务器配置
REMOTE_BASE_URL=https://api.example.com
REMOTE_API_KEY=your-api-key-here

# 其他可选配置
REQUEST_TIMEOUT=10000
MAX_RETRIES=3
LOG_LEVEL=info

启动服务

# 开发模式
npm run dev

# 生产模式
npm start

📖 MCP 工具列表

1. create_short_url

创建新的短网址

参数：

original_url (必填): 原始URL地址
domain (必填): 短网址域名
title (必填): 网页标题
custom_code (可选): 自定义短代码
description (可选): 描述信息
expire_at (可选): 过期时间

示例：

{
  "original_url": "https://www.example.com/products",
  "domain": "short.ly",
  "title": "产品页面",
  "description": "我们的产品展示页面",
  "custom_code": "products"
}

2. get_url_info

获取短网址详细信息

参数：

id (必填): 短网址ID

示例：

{
  "id": 123
}

3. list_short_urls

列出短网址，支持分页和搜索

参数：

page (可选): 页码，默认1
page_size (可选): 每页数量，默认10
domain (可选): 域名筛选
keyword (可选): 搜索关键词

示例：

{
  "page": 1,
  "page_size": 20,
  "domain": "short.ly",
  "keyword": "产品"
}

4. delete_short_url

删除短网址

参数：

id (必填): 短网址ID

示例：

{
  "id": 123
}

5. batch_create_short_urls

批量创建短网址

参数：

urls (必填): URL数组（最多50个）
domain (必填): 短网址域名

示例：

{
  "urls": [
    "https://www.example1.com",
    "https://www.example2.com"
  ],
  "domain": "short.ly"
}

6. list_domains

获取所有可用域名列表

参数： 无需参数

示例：

{}

返回信息：

域名基本信息：ID、域名、协议
网站信息：网站名称、备案信息
配置信息：是否激活、参数透传设置
统计信息：总数、激活数量、未激活数量

🏗️ 项目结构

mliev-dwz-mcp/
├── src/
│   ├── index.js                 # 入口文件
│   ├── config/
│   │   └── remoteConfig.js      # 配置管理
│   ├── services/
│   │   ├── httpClient.js        # HTTP客户端
│   │   └── shortLinkService.js  # 短链接服务
│   ├── utils/
│   │   ├── validation.js        # 参数验证
│   │   └── errorHandler.js      # 错误处理
│   └── mcp/
│       ├── server.js            # MCP服务器
│       └── tools/               # MCP工具
│           ├── createShortUrl.js
│           ├── getUrlInfo.js
│           ├── listShortUrls.js
│           ├── deleteShortUrl.js
│           ├── batchCreateShortUrls.js
│           └── listDomains.js
├── tests/                       # 测试文件
├── package.json                 # 项目配置
├── .env.example                 # 环境变量模板
└── README.md                    # 项目说明

🔧 开发指南

可用脚本

# 启动开发服务器（热重载）
npm run dev

# 构建项目
npm run build

# 运行生产环境
npm start

# 运行测试
npm test

# 代码检查
npm run lint

# 自动修复代码格式
npm run format

添加新工具

在 src/mcp/tools/ 目录下创建新工具文件
实现工具对象，包含 name、description、inputSchema 和 handler
在 src/mcp/server.js 中注册新工具

错误处理

项目使用统一的错误处理机制：

ErrorHandler.asyncWrapper(): 包装异步函数，自动处理错误
CustomError: 自定义错误基类
ValidationError: 参数验证错误
NetworkError: 网络请求错误

📝 API 规范

响应格式

所有API响应都遵循统一格式：

{
  "success": true,
  "message": "操作成功",
  "data": {
    // 响应数据
  },
  "meta": {
    "operation": "操作名称",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": {},
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

🔐 配置说明

环境变量

变量名	说明	默认值	必填
`REMOTE_BASE_URL`	远程服务器地址	-	✅
`REMOTE_API_KEY`	API密钥	-	✅
`API_VERSION`	API版本	v1	❌
`REQUEST_TIMEOUT`	请求超时时间(ms)	10000	❌
`MAX_RETRIES`	最大重试次数	3	❌
`LOG_LEVEL`	日志级别	info	❌