mliev/open/mliev-dwz-mcp

Public

Code Issues Pull requests Events Packages Insights

main

mliev-dwz-mcp/README.zh-CN.md

专属De

docs: 将README翻译为英文并添加中文版本

0ef906f6

PreviewCode viewBlame

Raw

Mliev 短网址 MCP 客户端

基于 MCP（Model Context Protocol）协议的短网址管理客户端，为 AI 助手提供完整的短网址生成、管理和统计功能。本项目的 MCP 服务端基于 dwz-server 项目的 API 接口实现。

🏛️ 服务端架构

本 MCP 客户端调用的是基于 dwz-server 项目的短网址服务 API。dwz-server 是一个基于 Go 语言开发的高性能短网址服务，提供完整的短网址生成、管理和统计功能。

使用 Docker 部署 dwz-server

推荐使用 Docker 部署 dwz-server 作为 MCP 客户端的后端服务：


# docker-compose.yml
services:
  dwz-server:
    container_name: dwz-server
    image: docker.cnb.cool/mliev/open/dwz-server:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - "./config/:/app/config/"
    environment:
      - TZ=Asia/Shanghai
      - GIN_MODE=release

启动服务：


docker-compose up -d

服务启动后，API 地址为 http://localhost:8080，在 MCP 客户端配置中设置：


REMOTE_BASE_URL=http://localhost:8080

✨ 功能特性

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