DWZ Short URL MCP Server

Mliev短URL MCP客户端

基于MCP（模型上下文协议）协议的短URL管理客户端，为AI助手提供完整的短URL生成、管理和统计功能。此MCP服务器是基于 dwz服务器 项目。

🏛️ 服务器架构

此MCP客户端基于 dwz服务器 项目。dwz服务器是用Go语言开发的高性能短URL服务，提供完整的短URL生成、管理和统计功能。

使用Docker部署dwz服务器

建议使用Docker作为MCP客户端的后端服务部署dwz服务器：

# 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

✨ 特性

• 🔗 短URL创建：支持自定义域、短代码、标题和描述
• 📋 批量操作：一次创建多个短网址以提高效率
• 🔍 搜索和筛选：支持域名过滤和关键字搜索
• 📊 统计与分析：获取详细的点击统计信息
• 🛡️ 错误处理：全面的错误处理和重试机制
• 🔒 安全认证：基于承载令牌的API认证

🚀 快速开始

先决条件

• Node.js>=18.0.0
• npm或纱线

直接MCP使用

{
  "mcpServers": {
    "dwz-mcp": {
      "name": "dwz-mcp",
      "type": "stdio",
      "isActive": true,
      "registryUrl": "",
      "command": "npx",
      "args": [
        "-y",
        "@muleiwu/dwz-mcp"
      ],
      "env": {
        "REMOTE_BASE_URL": "Your short URL service address",
        "REMOTE_API_KEY": "apiKey"
      }
    }
  }
}

安装依赖项

npm install

配置环境变量

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

cp .env.example .env

编辑 .env 文件：

# Remote short URL server configuration
REMOTE_BASE_URL=https://api.example.com
REMOTE_API_KEY=your-api-key-here

# Other optional configuration
REQUEST_TIMEOUT=10000
MAX_RETRIES=3
LOG_LEVEL=info

启动服务

# Development mode
npm run dev

# Production mode
npm start

📖 MCP工具列表

1.create_short_url

创建新的短URL

参数：

• original_url （必填）：原始URL地址
• domain （必填）：短URL域
• title （必填）：网页标题
• custom_code （可选）：自定义短代码
• description （可选）：描述信息
• expire_at （可选）：到期时间

例子：

{
  "original_url": "https://www.example.com/products",
  "domain": "short.ly",
  "title": "Product Page",
  "description": "Our product showcase page",
  "custom_code": "products"
}

2.获取信息

获取有关短URL的详细信息

参数：

• id （必填）：短URL ID

例子：

{
  "id": 123
}

3.list_short_url

列出具有分页和搜索支持的短网址

参数：

• page （可选）：页码，默认1
• page_size （可选）：每页项目数，默认为10
• domain （可选）：域筛选器
• keyword （可选）：搜索关键字

例子：

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

4.删除_short_url

删除短URL

参数：

• id （必填）：短URL ID

例子：

{
  "id": 123
}

5.batch_create_short_url

批量创建短网址

参数：

• urls （必填）：URL数组（最多50个）
• domain （必填）：短URL域

例子：

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

6.域名列表

获取所有可用域的列表

参数： 无需

例子：

{}

退货信息：

• 域基本信息：ID、域、协议
• 网站信息：网站名称、注册信息
• 配置信息：激活状态、参数传递设置
• 统计信息：总计数、活动计数、非活动计数

🏗️ 项目结构

mliev-dwz-mcp/
├── src/
│   ├── index.js                 # Entry file
│   ├── config/
│   │   └── remoteConfig.js      # Configuration management
│   ├── services/
│   │   ├── httpClient.js        # HTTP client
│   │   └── shortLinkService.js  # Short link service
│   ├── utils/
│   │   ├── validation.js        # Parameter validation
│   │   └── errorHandler.js      # Error handling
│   └── mcp/
│       ├── server.js            # MCP server
│       └── tools/               # MCP tools
│           ├── createShortUrl.js
│           ├── getUrlInfo.js
│           ├── listShortUrls.js
│           ├── deleteShortUrl.js
│           ├── batchCreateShortUrls.js
│           └── listDomains.js
├── tests/                       # Test files
├── package.json                 # Project configuration
├── .env.example                 # Environment variable template
└── README.md                    # Project documentation

🔧 开发指南

可用脚本

# Start development server (hot reload)
npm run dev

# Build project
npm run build

# Run production environment
npm start

# Run tests
npm test

# Code linting
npm run lint

# Auto-fix code formatting
npm run format

添加新工具

1. 在中创建新的工具文件 src/mcp/tools/ 目录
2. 实现工具对象，包括 name, description, inputSchema，以及 handler
3. 在中注册新工具 src/mcp/server.js

错误处理

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

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

📝 API 规范

响应格式

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

{
  "success": true,
  "message": "Operation successful",
  "data": {
    // Response data
  },
  "meta": {
    "operation": "Operation name",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": {},
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

🔐 配置说明

环境变量

域配置

确保在远程短URL服务中正确配置了使用的域。

🚨 故障排除

常见问题

1. 连接失败

- 检查 REMOTE_BASE_URL 和 REMOTE_API_KEY 配置 - 确认网络连接正常 - 验证远程服务状态

1. 认证失败

- 确认API密钥正确 - 检查密钥是否具有足够的权限

1. 参数验证失败

- 检查参数格式是否正确 - 确认提供了所有必需的参数

日志调试

将日志级别设置为调试以查看详细信息：

LOG_LEVEL=debug npm start

🤝 贡献指南

1. 分叉项目
2. 创建特征分支(git checkout -b feature/AmazingFeature)
3. 提交更改(git commit -m 'Add some AmazingFeature')
4. 推送到分支(git push origin feature/AmazingFeature)
5. 打开拉取请求

📄 许可证

此项目是MIT许可证下的开源项目-请参阅 许可证 文件以获取详细信息。

🆘 支持

如果您遇到问题或有建议，请：

1. 检查 故障排除 部分
2. 搜索现有 问题
3. 创建一个描述问题的新问题

📊 版本历史

• v1.0.0 -初始版本

- 基本的短URL管理功能 - MCP协议支持 - 完整的错误处理机制