Dwz Mcp

Mliev Short URL MCP クライアント

MCP（Model Context Protocol）プロトコルに基づく短縮 URL 管理クライアントです。AI アシスタント向けに、短縮 URL の生成、管理、統計機能を一通り提供します。この MCP サーバーは、dwz-server プロジェクトの API インターフェースに基づいて実装されています。

🏛️ サーバーアーキテクチャ

この MCP クライアントは、dwz-server プロジェクトに基づく短縮 URL サービス API を呼び出します。dwz-server は Go 言語で開発された高性能な短縮 URL サービスで、短縮 URL の生成、管理、統計機能を一通り提供します。

Docker で dwz-server をデプロイする

MCP クライアントのバックエンドサービスとして、Docker を使用して dwz-server をデプロイすることをおすすめします。

# 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 の作成：カスタムドメイン、短縮コード、タイトル、説明に対応
• 📋 一括操作：複数の短縮 URL を一度に作成し、効率を高めます
• 🔍 検索とフィルタリング：ドメインによるフィルタリングとキーワード検索に対応
• 📊 統計と分析：詳細なクリック統計情報を取得します
• 🛡️ エラー処理：包括的なエラー処理と再試行の仕組みを提供
• 🔒 セキュリティ認証：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": "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（必須）：Web ページのタイトル
• 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. get_url_info

短縮 URL の詳細情報を取得します

パラメーター：

• id（必須）：短縮 URL の ID

例：

{
  "id": 123
}

3. list_short_urls

ページネーションと検索に対応した短縮 URL の一覧を取得します

パラメーター：

• page（任意）：ページ番号。デフォルトは 1
• page_size（任意）：1 ページあたりの項目数。デフォルトは 10
• domain（任意）：ドメインフィルター
• keyword（任意）：検索キーワード

例：

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

4. delete_short_url

短縮 URL を削除します

パラメーター：

• id（必須）：短縮 URL の ID

例：

{
  "id": 123
}

5. batch_create_short_urls

短縮 URL を一括作成します

パラメーター：

• urls（必須）：URL の配列（最大 50 件）
• domain（必須）：短縮 URL のドメイン

例：

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

6. list_domains

利用可能なすべてのドメインの一覧を取得します

パラメーター： 必須項目なし

例：

{}

返される情報：

• ドメインの基本情報：ID、ドメイン、プロトコル
• Web サイト情報：Web サイト名、登録情報
• 設定情報：有効化状態、パラメーターの引き継ぎ設定
• 統計情報：総数、有効数、無効数

🏗️ プロジェクト構成

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

🔐 設定手順

環境変数

変数名	説明	デフォルト値	必須
REMOTE_BASE_URL	リモートサーバーのアドレス	-	✅
REMOTE_API_KEY	API キー	-	✅
API_VERSION	API バージョン	v1	❌
REQUEST_TIMEOUT	リクエストのタイムアウト（ms）	10000	❌
MAX_RETRIES	最大再試行回数	3	❌
LOG_LEVEL	ログレベル	info	❌

ドメイン設定

使用するドメインが、リモート短縮 URL サービスで正しく設定されていることを確認してください。

🚨 トラブルシューティング

よくある問題

1. 接続に失敗する

   • REMOTE_BASE_URL と REMOTE_API_KEY の設定を確認します
   • ネットワーク接続が正常であることを確認します
   • リモートサービスの状態を確認します

2. 認証に失敗する

   • API キーが正しいことを確認します
   • キーに十分な権限があるか確認します

3. パラメーターの検証に失敗する

   • パラメーターの形式が正しいか確認します
   • 必須パラメーターがすべて指定されていることを確認します

ログのデバッグ

詳細情報を表示するには、ログレベルを debug に設定します。

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 License の下でオープンソースとして公開されています。詳細については、LICENSE ファイルを参照してください。

🆘 サポート

問題が発生した場合や提案がある場合は、次の手順に従ってください。

1. トラブルシューティング セクションを確認します
2. 既存の Issue を検索します
3. 問題の内容を説明する新しい Issue を作成します

📊 バージョン履歴

• v1.0.0 - 初回バージョン
  • 基本的な短縮 URL 管理機能
  • MCP プロトコルのサポート
  • 完全なエラー処理メカニズム