@open-short-url/mcp

v0.5.0

Published

2 days ago

Model Context Protocol (MCP) Server for Open Short URL

0High
0Medium
0Low

supra126

open-short-url short-url url-shortener mcp model-context-protocol vercel-ai

Open Short URL - MCP Server

English | 繁體中文

Model Context Protocol (MCP) Server for Open Short URL，讓 AI 助手能夠管理您的短網址系統。

使用前提

重要：此 MCP Server 是 Open Short URL 的客戶端工具，需要連接到已部署的 Open Short URL 後端系統才能使用。
這不是一個獨立的短網址服務，而是透過支援 MCP 協議的 AI 應用來管理您現有的短網址系統。

必要條件

1. Open Short URL 後端系統（必須）

您需要先部署 Open Short URL 後端：

從 Open Short URL 主專案部署
後端必須正在運行並可透過網路訪問
記下您的後端網址（例如：https://your-backend.com）

沒有後端系統？請先前往主專案倉庫了解如何部署。

2. API Key

從您的後端系統獲取 API Key：

登入後端管理介面
前往「設定」→「API Keys」
點擊「創建新的 API Key」
複製生成的 API Key（格式：ak_xxxxxxxxxxxxxx）

快速測試連接

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://your-backend.com/api/urls

功能特色

77 個 MCP 工具，涵蓋 11 個模組：

| 模組 | 工具數 | 說明 | | ----------- | ------ | ----------------------------------------- | | URL 管理 | 10 | 建立、列表、更新、刪除、QR Code、批量操作 | | Bundle 管理 | 12 | 分組管理 URL、排序、歸檔/恢復、統計 | | 分析數據 | 10 | 點擊分析、趨勢、機器人偵測、數據匯出 | | A/B 測試 | 5 | 建立變體、流量分配、效果比較 | | 智慧路由 | 8 | 條件式路由規則、範本、地理/裝置定向 | | Webhooks | 7 | 事件通知、傳送日誌、Webhook 測試 | | 使用者管理 | 11 | 建立/管理使用者、角色、2FA、OIDC 帳號 | | API Keys | 4 | 建立、列表、檢視、撤銷 API 金鑰 | | OIDC/SSO | 5 | 管理 OIDC/SSO 身份驗證提供者 | | 系統設定 | 4 | 檢視及管理系統配置 | | 稽核日誌 | 1 | 查詢系統稽核紀錄 |

安全機制

敏感資料脫敏 — API Key、Token、密碼在所有回應中自動遮蔽
破壞性操作標記 — 刪除/重設操作會標示 [DESTRUCTIVE]，並提示 AI 助手確認
錯誤訊息清理 — 錯誤輸出中的憑證會被自動移除

快速開始

傳輸模式

MCP Server 支援兩種傳輸模式：

| 模式 | 使用場景 | 協議 | | ----------------- | --------------------------------------------- | --------------- | | stdio（預設） | CLI 及 IDE 整合（Claude Desktop、VS Code 等） | 標準 I/O | | http | 遠端存取、容器化部署、多客戶端 | Streamable HTTP |

方式一：npm（stdio）

全局安裝（推薦）

npm install -g @open-short-url/mcp

使用 npx

npx @open-short-url/mcp

MCP 客戶端配置

{
  "mcpServers": {
    "open-short-url": {
      "command": "open-short-url-mcp",
      "env": {
        "API_URL": "https://your-backend.com",
        "API_KEY": "ak_your_api_key_here"
      }
    }
  }
}

方式二：Docker（HTTP）

docker run -p 3200:3200 \
  -e API_URL=http://your-backend:4101 \
  -e API_KEY=ak_your_api_key_here \
  ghcr.io/supra126/open-short-url-mcp:latest

服務將在 http://localhost:3200/mcp 啟動。

健康檢查

curl http://localhost:3200/health

方式三：Docker Compose

在現有的 Open Short URL 部署中啟用 mcp profile：

docker compose --profile mcp up -d

在 .env.docker 中設定 MCP_API_KEY。完整配置請參考主專案的 docker-compose.yml。

方式四：從源碼建置

git clone https://github.com/supra126/open-short-url.git
cd open-short-url/packages/mcp
pnpm install && pnpm build

# stdio 模式
API_URL=https://your-backend.com API_KEY=ak_xxx node dist/index.js

# HTTP 模式
MCP_TRANSPORT=http API_URL=https://your-backend.com API_KEY=ak_xxx node dist/index.js

環境變數

| 變數名稱 | 必填 | 預設值 | 說明 | | --------------- | ---- | --------- | ------------------------------- | | API_URL | 是 | — | Open Short URL 後端 API 位址 | | API_KEY | 是 | — | 後端系統生成的 API Key | | MCP_TRANSPORT | 否 | stdio | 傳輸模式：stdio 或 http | | MCP_PORT | 否 | 3200 | HTTP 伺服器埠號（僅 http 模式） | | MCP_HOST | 否 | 0.0.0.0 | HTTP 綁定位址（僅 http 模式） |

可用工具列表（77 個）

URL 管理（10 個）

| 工具 | 說明 | | ------------------ | -------------------------------------------------- | | create_short_url | 建立短網址（自定義 slug、密碼保護、過期時間、UTM） | | list_short_urls | 列出所有短網址（分頁、搜尋、篩選） | | get_short_url | 查詢短網址詳情 | | update_short_url | 更新短網址設定 | | delete_short_url | 刪除短網址 [DESTRUCTIVE] | | get_url_stats | 取得 URL 儀表板統計 | | generate_qrcode | 生成短網址 QR Code | | bulk_create_urls | 批量建立短網址（最多 100 個） | | bulk_update_urls | 批量更新短網址 | | bulk_delete_urls | 批量刪除短網址 [DESTRUCTIVE] |

Bundle 管理（12 個）

| 工具 | 說明 | | ----------------------------- | --------------------------- | | create_bundle | 建立新的 Bundle | | list_bundles | 列出所有 Bundle | | get_bundle | 查詢 Bundle 詳情 | | update_bundle | 更新 Bundle 資訊 | | delete_bundle | 刪除 Bundle [DESTRUCTIVE] | | add_url_to_bundle | 添加單個 URL 到 Bundle | | add_multiple_urls_to_bundle | 批量添加 URL 到 Bundle | | remove_url_from_bundle | 從 Bundle 移除 URL | | update_url_order_in_bundle | 更新 URL 在 Bundle 中的順序 | | get_bundle_stats | 獲取 Bundle 統計數據 | | archive_bundle | 歸檔 Bundle | | restore_bundle | 恢復已歸檔的 Bundle |

分析數據（10 個）

| 工具 | 說明 | | ------------------------- | ---------------------------------- | | get_url_analytics | URL 點擊分析（地理、裝置、瀏覽器） | | get_overview_analytics | 總覽分析儀表板 | | get_top_performing_urls | 點擊量最高的 URL | | get_recent_clicks | 最近點擊紀錄 | | get_bot_analytics | 單個 URL 的機器人分析 | | get_user_bot_analytics | 全局機器人分析 | | get_ab_test_analytics | A/B 測試分析 | | get_routing_analytics | 智慧路由統計 | | export_url_analytics | 匯出單個 URL 分析數據（CSV/JSON） | | export_all_analytics | 匯出所有分析數據（CSV/JSON） |

A/B 測試（5 個）

| 工具 | 說明 | | ---------------- | ---------------------- | | create_variant | 建立測試變體 | | list_variants | 列出所有變體 | | get_variant | 查詢變體詳情 | | update_variant | 更新變體設定 | | delete_variant | 刪除變體 [DESTRUCTIVE] |

智慧路由（8 個）

| 工具 | 說明 | | ----------------------------------- | ------------------------------ | | create_routing_rule | 建立條件式路由規則 | | create_routing_rule_from_template | 從範本建立規則（地理、裝置等） | | list_routing_rules | 列出 URL 的路由規則 | | get_routing_rule | 查詢路由規則詳情 | | update_routing_rule | 更新路由規則 | | delete_routing_rule | 刪除路由規則 [DESTRUCTIVE] | | update_smart_routing_settings | 更新 URL 的路由設定 | | list_routing_templates | 列出可用的路由範本 |

Webhooks（7 個）

| 工具 | 說明 | | ------------------ | -------------------------- | | create_webhook | 建立 Webhook 端點 | | list_webhooks | 列出所有 Webhooks | | get_webhook | 查詢 Webhook 詳情 | | update_webhook | 更新 Webhook 設定 | | delete_webhook | 刪除 Webhook [DESTRUCTIVE] | | get_webhook_logs | 查看 Webhook 傳送日誌 | | test_webhook | 發送測試 Webhook 事件 |

使用者管理（11 個）

| 工具 | 說明 | | -------------------------- | -------------------------------- | | create_user | 建立新使用者 | | list_users | 列出所有使用者 | | get_user | 查詢使用者詳情 | | update_user_role | 更新使用者角色 | | update_user_status | 啟用/停用使用者 | | update_user_name | 更新使用者顯示名稱 | | delete_user | 刪除使用者 [DESTRUCTIVE] | | reset_user_password | 重設使用者密碼 [DESTRUCTIVE] | | disable_user_2fa | 停用使用者 2FA [DESTRUCTIVE] | | get_user_oidc_accounts | 列出使用者已連結的 OIDC 帳號 | | unlink_user_oidc_account | 解除連結 OIDC 帳號 [DESTRUCTIVE] |

API Keys（4 個）

| 工具 | 說明 | | ---------------- | -------------------------------------- | | create_api_key | 建立新 API Key（僅顯示一次，之後遮蔽） | | list_api_keys | 列出所有 API Keys | | get_api_key | 查詢 API Key 詳情 | | delete_api_key | 撤銷 API Key [DESTRUCTIVE] |

OIDC/SSO 提供者（5 個）

| 工具 | 說明 | | ---------------------- | ------------------------------ | | list_oidc_providers | 列出 OIDC 提供者 | | create_oidc_provider | 建立 OIDC 提供者 | | get_oidc_provider | 查詢 OIDC 提供者詳情 | | update_oidc_provider | 更新 OIDC 提供者 | | delete_oidc_provider | 刪除 OIDC 提供者 [DESTRUCTIVE] |

系統設定（4 個）

| 工具 | 說明 | | ----------------------- | -------------------------- | | get_system_settings | 取得所有系統設定 | | get_system_setting | 取得單一設定值 | | update_system_setting | 更新系統設定 | | delete_system_setting | 刪除系統設定 [DESTRUCTIVE] |

稽核日誌（1 個）

| 工具 | 說明 | | ---------------- | ------------------------ | | get_audit_logs | 查詢稽核日誌（支援篩選） |

疑難排解

MCP Server 無法啟動

確認 API_URL 和 API_KEY 已正確設定

測試 API 連線：

curl -H "Authorization: Bearer YOUR_API_KEY" https://your-backend.com/api/urls

工具調用失敗

檢查 API Key 是否有效且未過期
檢查後端服務是否正常運行
檢查網路連線是否可達後端
檢查 API Key 是否有足夠權限

Docker 容器問題

確保 API_URL 使用 Docker 網路主機名（例如 http://backend:4101），而非 localhost
查看容器日誌：docker logs <container-id>
驗證健康檢查端點：curl http://localhost:3200/health

安全建議

不要分享或將 API Key 提交到 Git
定期輪換 API Key
為不同環境使用不同的 API Key
為 MCP Server 建立權限最小化的專用 API Key
MCP Server 會自動脫敏所有回應中的敏感資料（金鑰、Token、密碼）

授權

MIT License - 詳見 LICENSE 檔案。