Mliev Short URL MCP Client

A short URL management client based on MCP (Model Context Protocol) protocol, providing complete short URL generation, management, and statistics functionality for AI assistants. This MCP server is implemented based on the API interface of the dwz-server project.

🏛️ Server Architecture

This MCP client calls the short URL service API based on the dwz-server project. dwz-server is a high-performance short URL service developed in Go language, providing complete short URL generation, management, and statistics functionality.

Deploy dwz-server with Docker

It is recommended to deploy dwz-server using Docker as the backend service for the MCP client:

# 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

Start the service:

docker-compose up -d

After the service starts, the API address will be http://localhost:8080. Configure it in the MCP client:

REMOTE_BASE_URL=http://localhost:8080

✨ Features

🔗 Short URL Creation: Support custom domains, short codes, titles, and descriptions
📋 Batch Operations: Create multiple short URLs at once to improve efficiency
🔍 Search & Filter: Support domain filtering and keyword search
📊 Statistics & Analytics: Get detailed click statistics information
🛡️ Error Handling: Comprehensive error handling and retry mechanisms
🔒 Security Authentication: API authentication based on Bearer Token

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm or yarn

Direct MCP Usage

{ "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" } } } }

Install Dependencies

npm install

Configure Environment Variables

Copy the environment variable template and configure:

cp .env.example .env

Edit the .env file:

# 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

Start Service

# Development mode npm run dev # Production mode npm start

📖 MCP Tool List

1. create_short_url

Create a new short URL

Parameters:

original_url (required): Original URL address
domain (required): Short URL domain
title (required): Web page title
custom_code (optional): Custom short code
description (optional): Description information
expire_at (optional): Expiration time

Example:

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

2. get_url_info

Get detailed information about a short URL

Parameters:

id (required): Short URL ID

Example:

{ "id": 123 }

3. list_short_urls

List short URLs with pagination and search support

Parameters:

page (optional): Page number, default 1
page_size (optional): Items per page, default 10
domain (optional): Domain filter
keyword (optional): Search keyword

Example:

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

4. delete_short_url

Delete a short URL

Parameters:

id (required): Short URL ID

Example:

{ "id": 123 }

5. batch_create_short_urls

Batch create short URLs

Parameters:

urls (required): URL array (maximum 50)
domain (required): Short URL domain

Example:

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

6. list_domains

Get list of all available domains

Parameters: None required

Example:

{}

Return Information:

Domain basic information: ID, domain, protocol
Website information: website name, registration information
Configuration information: activation status, parameter pass-through settings
Statistics information: total count, active count, inactive count

🏗️ Project Structure

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

🔧 Development Guide

Available Scripts

# 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

Adding New Tools

Create a new tool file in the src/mcp/tools/ directory
Implement the tool object, including name, description, inputSchema, and handler
Register the new tool in src/mcp/server.js

Error Handling

The project uses a unified error handling mechanism:

ErrorHandler.asyncWrapper(): Wrap async functions, automatically handle errors
CustomError: Custom error base class
ValidationError: Parameter validation error
NetworkError: Network request error

📝 API Specification

Response Format

All API responses follow a unified format:

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

Error Response

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

🔐 Configuration Instructions

Environment Variables

Variable Name	Description	Default Value	Required
`REMOTE_BASE_URL`	Remote server address	-	✅
`REMOTE_API_KEY`	API key	-	✅
`API_VERSION`	API version	v1	❌
`REQUEST_TIMEOUT`	Request timeout (ms)	10000	❌
`MAX_RETRIES`	Maximum retry count	3	❌
`LOG_LEVEL`	Log level	info	❌

Domain Configuration

Ensure that the domains used are correctly configured in the remote short URL service.

🚨 Troubleshooting

Common Issues

Connection Failed
- Check REMOTE_BASE_URL and REMOTE_API_KEY configuration
- Confirm network connection is normal
- Verify remote service status
Authentication Failed
- Confirm API key is correct
- Check if the key has sufficient permissions
Parameter Validation Failed
- Check if parameter format is correct
- Confirm all required parameters are provided

Log Debugging

Set log level to debug to view detailed information:

LOG_LEVEL=debug npm start

🤝 Contributing Guide

Fork the project
Create feature branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is open source under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter problems or have suggestions, please:

Check the Troubleshooting section
Search existing Issues
Create a new Issue describing the problem

📊 Version History

v1.0.0 - Initial version
- Basic short URL management functionality
- MCP protocol support
- Complete error handling mechanism

DWZ Short URL MCP Server

Mliev Short URL MCP Client

🏛️ Server Architecture

Deploy dwz-server with Docker

✨ Features

🚀 Quick Start

Prerequisites

Direct MCP Usage

Install Dependencies

Configure Environment Variables

Start Service

📖 MCP Tool List

1. create_short_url

2. get_url_info

3. list_short_urls

4. delete_short_url

5. batch_create_short_urls

6. list_domains

🏗️ Project Structure

🔧 Development Guide

Available Scripts

Adding New Tools

Error Handling

📝 API Specification

Response Format

Error Response

🔐 Configuration Instructions

Environment Variables

Domain Configuration

🚨 Troubleshooting

Common Issues

Log Debugging

🤝 Contributing Guide

📄 License

🆘 Support

📊 Version History

Related Resources

Tools

New MCP Servers

MCP directory API