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.

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.

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

• 🔗 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

• Node.js >= 18.0.0
• npm or yarn

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

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

# Development mode
npm run dev

# Production mode
npm start

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

Get detailed information about a short URL

Parameters:

• id (required): Short URL ID

Example:

{
  "id": 123
}

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

Delete a short URL

Parameters:

• id (required): Short URL ID

Example:

{
  "id": 123
}

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

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

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. Create a new tool file in the src/mcp/tools/ directory
2. Implement the tool object, including name, description, inputSchema, and handler
3. Register the new tool in src/mcp/server.js

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

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

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

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	❌

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

1. Connection Failed

   • Check REMOTE_BASE_URL and REMOTE_API_KEY configuration
   • Confirm network connection is normal
   • Verify remote service status

2. Authentication Failed

   • Confirm API key is correct
   • Check if the key has sufficient permissions

3. Parameter Validation Failed

   • Check if parameter format is correct
   • Confirm all required parameters are provided

Set log level to debug to view detailed information:

LOG_LEVEL=debug npm start

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

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

If you encounter problems or have suggestions, please:

1. Check the Troubleshooting section
2. Search existing Issues
3. Create a new Issue describing the problem

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