url-manager-mcp

URL Manager MCP サーバー

英語 | 簡体字中国語

生のリンクを並べるのではなく、美しいカードで結果を表示します。 Web リソースの保存、整理、検索、共有を行う Model Context Protocol サーバーです。デバイス間同期、カテゴリ、タグ、全文検索、一括操作、チーム共有に対応しています。自動登録機能を備えた21種類のツールがあり、手動でのセットアップは不要です。

📖 使用パターンとベストプラクティス → URL Manager Skill

このツールが人々にもたらすもの

人が保存したいコンテンツはあらゆる場所にあります。YouTube のワークアウト動画、Amazon のギアへのリンク、Substack のトレーニング計画などが、つながりのない複数のプラットフォームに散らばっています。

URL Manager はこの問題を解決します。 どのプラットフォームのリンクでも貼り付けられます。AI がコンテンツを自動で識別し、カテゴリを提案します。確認すれば、足跡として保存されます。保存したものはすべて、プラットフォームに依存しない1つのライブラリに集約され、整理されて、いつでも見つけられます。さらにワンクリックで共有できます。整理したナレッジベースをチームに渡せば、全員が同期された状態を保てます。

システムの概念

足跡（基本単位）

構造化され、検索可能なレコードです。Web リンク、プレーンテキストのメモ、アイデアなど、保存する価値のあるものを記録します。

フィールド	型	説明
id	UUID	永続的な一意の識別子。すべての操作で使用します
url	string (8192)	元のリンク。テキストのみの足跡では空にできます
title	string (512)	短いタイトル
description	string (1024)	追加のコンテキストやメモ
content_type	string (50)	自由入力のテキスト（例：article、video、image）。既存の値を確認するには list_content_types() を使用します
category_ids	list[int]	所属するカテゴリ。自分で割り当てます
tag_names	list[str]	自由形式のキーワード。自分で割り当てます

1つの足跡を複数のカテゴリに同時に所属させることができます。

カテゴリ（名前付きラベル）

フォルダーのようなものですが、足跡は複数のカテゴリに同時に所属できます。

フィールド	型	説明
id	int	永続的な数値の識別子。常に ID で参照します
name	string (50)	表示名
mode	string | null	null = 個人用、"cocreate" = 共同編集で共有、"subscribe" = 読み取り専用で共有

カテゴリセット（ワークスペース）

関連するカテゴリをまとめるコンテナです。すべてのユーザーには、最初から「My Categories」（個人用）と「Shared Categories」（共有コンテナ）が用意されています。

データ階層

Category Sets (workspaces)
  └── Categories (labels like "Shopping", "Learning")
        └── Footprints
             └── Tags (free-form keywords)

個人用と共有

	個人用	共有
mode	null	"cocreate" または "subscribe"
表示対象	自分のみ	自分と招待されたメンバー
メンバーと招待リンク	いいえ	はい

共同編集 — 全員が足跡を追加・削除できます。購読 — メンバーは読み取り専用です（書き込みは403を返します）。

操作	オーナー	管理者	メンバー
足跡の追加・削除（共同編集）	✅	✅	✅
足跡の追加・削除（購読）	✅	❌	❌
招待リンクの生成（共同編集）	✅	✅	✅
招待リンクの生成（購読）	✅	❌	❌
共同編集 ↔ 購読の切り替え	✅	❌	❌
メンバーの管理	Web UI のみ	—	—

ツール

登録と本人確認

• agent_register() 新しいアカウントを作成します。パラメーターはありません。トークンは以降のすべての呼び出しに自動で適用されます。 ⚠️ 1回だけ呼び出してください。呼び出すたびに新しいアカウントが作成されます。

• my_info() 接続とトークンの有効性を確認します。ユーザー名とメンバーシップの状態を返します。

ブックマーク

• search_footprints(query, limit, offset) タイトル、説明、URLを全文検索します。

  • query (required) — 検索キーワード
  • limit — 1ページあたりの結果数（デフォルト10、最大100）
  • offset — ページネーションのオフセット（デフォルト0）

• list_footprints(category_id, limit, offset) カテゴリ別にブックマークを一覧表示します。category_id=0 を指定するとすべて表示します。

  • limit — 1ページあたりの結果数（デフォルト20、最大100）
  • offset — ページネーションのオフセット（デフォルト0）

• get_footprint(footprint_id) 1件のブックマークの詳細をすべて取得します。

  • footprint_id (required) — list_footprints または search_footprints の結果に含まれる値（フィールド id）

• add_footprint(url, title, description, category_ids, tag_names) 新しいブックマークを追加します。既存の構成を確認するため、先に list_categories() と list_tags() を呼び出してください。

  • url (required) — ウェブページのURL
  • title — 空欄にするとページから自動抽出します
  • description — 要約またはメモ
  • category_ids — カンマ区切りのID。例："1,3"
  • tag_names — カンマ区切りの名前。例："AI,tutorial"

• update_footprint(footprint_id, title, description, category_ids, tag_names) ブックマークを更新します。省略したフィールドは変更されません。 ⚠️ category_ids はリスト全体を置き換えます。追加ではありません。先に get_footprint() を呼び出し、IDを統合してください。

  • footprint_id (required) — 検索または一覧表示の結果に含まれる値

カテゴリとタグ

• list_categories() すべてのカテゴリ（個人用＋共有）を一覧表示します。id、name、mode フィールドを返します。 mode=null → 個人用、mode="cocreate"/"subscribe" → 共有。

• create_category(name, category_set_id) 新しいカテゴリを作成します。重複を避けるため、先に list_categories() を確認してください。

  • name (required) — カテゴリ名
  • category_set_id — 親カテゴリセット（0 = デフォルト）

• list_tags() このアカウントで使用されているすべてのタグを一覧表示します。

• list_content_types() ユーザーが使用したすべてのコンテンツタイプ（例：記事、動画、画像）を、使用頻度の高い順に一覧表示します。追加する前に使用して、一貫性のある content_type を選んでください。

カテゴリセット

• list_category_sets() すべてのカテゴリセットを一覧表示します。

• create_category_set(name) 新しいカテゴリセット（カテゴリをまとめるコンテナー）を作成します。

  • name (required) — カテゴリセット名

共有カテゴリ

• create_shared_category(name, mode, description) チームでの共同作業用に共有カテゴリを作成します。

  • name (required)
  • mode (required) — "cocreate"（複数の編集者）または "subscribe"（読み取り専用）
  • description — 任意の説明 ⚠️ subscribe モードでは、ブックマークを追加すると 403 が返されます。編集可能な共同作業には "cocreate" を使用してください。

• create_invite_link(shared_category_id, duration_hours) 他のユーザーが参加するための招待リンクを生成します。

  • shared_category_id (required) — list_categories() の共有エントリから取得
  • duration_hours — デフォルト24

• join_shared_category(invite_code) 招待コードを使って共有カテゴリに参加します。

  • invite_code (required) — 招待リンクに含まれる8文字のコード

• add_to_shared_category(shared_category_id, footprint_id) 自分のブックマークを共有カテゴリに追加します。

  • 両方のパラメーターが必須です

• remove_from_shared_category(shared_category_id, footprint_id) 共有カテゴリからブックマークを削除します。ブックマーク自体は削除されません。

  • 両方のパラメーターが必須です

• copy_footprint(footprint_id, category_ids) 共有カテゴリから個人用コレクションにブックマークをコピーします。

  • 両方のパラメーターが必須です

バッチ処理と共有

• batch_update_footprints(updates) 最大50件のブックマークを一括編集します。

  • updates (必須) — JSON 文字列：[{"id":"...", "title":"New Title", "category_ids":"1,3"}, ...] 各オブジェクトには title、description、category_ids、tag_names を指定できます。id は必須です。

• agent_magic_link() 🔑 共有ワークフローの要です。整理後にリンクを生成して、ユーザーに送信します。リンクをクリックすると、整理したブックマークがカード形式のインターフェースにすべて表示されます。有効期間は30日間で、繰り返し使用できます。

ワークフロー

新規ユーザー — セットアップ不要

1. agent_register() → get token (auto-memorized)
2. add_footprint(url="...") × N → save bookmarks one by one
3. list_categories() → understand current structure
4. create_category(name="Learning") → create a category
5. update_footprint(id, category_ids="...") → categorize
6. agent_magic_link() → "Done! View your collection here → [link]"

リピーター — 日常的な利用

1. my_info() → confirm identity
2. list_categories() + list_tags() → understand current structure
3. search_footprints(query) or list_footprints(category_id) → find targets
4. add_footprint / update_footprint → operate
5. agent_magic_link() → deliver results

共有カテゴリーを作成する

1. create_shared_category(name="Team KB", mode="cocreate")
2. create_invite_link(shared_category_id=<returned ID>)
3. Send invite code to user → user shares with teammates
4. Teammates' agents join via join_shared_category(invite_code)

⚠️ 重大な注意点

category_ids は追加ではなく置き換えです

# ❌ Wrong: moving bookmark 42 to category 7 loses existing categories 3 and 5
update_footprint(42, category_ids="7")

# ✅ Right: fetch current categories first, then merge
get_footprint(42) → existing categories [3, 5]
update_footprint(42, category_ids="3,5,7")

購読モードは読み取り専用です

購読モードの共有カテゴリーへの書き込みは403エラーになります。ユーザーから「購読したのに追加できない」と言われた場合は、読み取り専用であることを説明してください。作成者がモードをcocreateに変更する必要があります。

agent_register は絶対に2回呼び出さないでください

呼び出すたびに新しい空のアカウントが作成されます。必ず最初に保存済みのトークンがあるか確認してください。不明な場合は my_info() を呼び出し、現在のトークンが有効か確認してください。

レート制限

短時間に連続して呼び出すと、HTTP 429が発生することがあります。バッチ処理の間には短い間隔を空けてください。429が発生した場合は、数秒待ってから再試行してください。

API経由でのメンバー管理はできません

共有カテゴリーのメンバーの招待や削除には、https://ai.ocean94.com のウェブUIが必要です。プログラムからこれらの操作を行うことはできません。

ガイドライン

常に実行すること

• 自動登録をユーザーに知らせずに行う — アカウントのセットアップのためにユーザーの操作を中断しないでください
• 一覧表示する前に検索する — すべてを表示するのではなく、対象を絞った検索には search_footprints を使用してください
• 作成前に確認する — 重複を避けるため、追加する前に list_categories() と list_tags() を呼び出してください
• マジックリンクで共有する — 整理後は必ずリンクを生成して共有してください

次の操作の前に確認すること

• ブックマークとカテゴリーの関連付けを解除する（元に戻せません）
• タグをすべて削除する
• cocreate共有カテゴリーを変更する（他のユーザーにも影響します）
• 共有カテゴリーからブックマークを削除する（他のメンバーがアクセスできなくなります）

人気のMCPサーバーとの連携

URL Managerは保存と整理を得意としています。発見と取得を得意とするツールと組み合わせてください。

Fetch MCP scrapes web  →  add_footprint()  →  auto-categorized, permanent, searchable
Firecrawl crawls pages →  add_footprint()  →  organized into cards
Brave Search finds URLs →  add_footprint()  →  one-click save from search results

エージェントは、上流のMCPのURLとタイトルをパラメーターとして add_footprint に渡すだけです。

インストール

git clone https://github.com/Piccolo123/url-manager-mcp.git
cd url-manager-mcp
pip install -r requirements.txt

または、PyPIからインストールします。

uvx url-manager-mcp   # or: pip install url-manager-mcp

前提条件

• Python 3.10+
• https://ai.ocean94.com へのネットワークアクセス

DeepSeek Harness (dsh)

プロフィールの cordis.patch.yml（例：~/.dsh/profiles/headless/cordis.patch.yml または web プロフィール）に追加します。

- insert:
    - id: mcp-url-manager
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: url_manager
        transport: stdio
        command: uvx
        args: ['url-manager-mcp']
        env:
          FOOTPRINTS_ENDPOINT: 'https://ai.ocean94.com'

21個のツールはすべて mcp__url_manager__*（add_footprint、search_footprints、list_categories、agent_magic_link、…）として表示されます。モデルは初回使用時に自動登録されるため、APIキーは不要です。補助スキル（Piccolo123/url-manager）も、~/.dsh/skills/ にクローンするとdshによって自動検出されます。

設定

Claude Desktop / Claude Code

{
  "mcpServers": {
    "url-manager": {
      "command": "python",
      "args": ["path/to/url-manager-mcp/server.py"]
    }
  }
}

ユーザーが既存のアカウントを持っている場合：

{
  "mcpServers": {
    "url-manager": {
      "command": "python",
      "args": ["path/to/url-manager-mcp/server.py"],
      "env": {
        "FOOTPRINTS_TOKEN": "FA_xxxxxxxxxxxx"
      }
    }
  }
}

Cursor / Windsurf / Cherry Studio

上記と同じJSON構造です。STDIOトランスポートに対応するMCP互換クライアントであれば、どれでも動作します。

その他のクライアント

このサーバーはSTDIO（デフォルト）とStreamable HTTPの両方のトランスポートに対応しています。

# STDIO (default)
python server.py

# Streamable HTTP (for Docker / Glama / hosted environments)
python server.py --http

マルチユーザーのリモートモード（WorkBuddy / ホスト型コネクター）

WorkBuddyコネクターなどのマルチユーザープラットフォームでStreamable HTTP（--http）を使用する場合、サーバーは FOOTPRINTS_TOKEN を無視します。すべてのリクエストに、呼び出し元自身のトークンを Authorization ヘッダー（Bearer FA_xxx）で含める必要があります。このトークンは、そのユーザー専用のURL Manager APIに渡されるため、複数のユーザーは互いに分離された状態に保たれます。トークンを含まないリクエストには、https://ai.ocean94.com → 个人中心 → 接入Agent → 访问令牌 を案内する missing_access_token エラーが表示されます。また、このモードでは agent_register() は無効になります（呼び出すと、使用されないアカウントが作成されるだけです）。単一ユーザー向けのSTDIOデプロイ（python server.py、--http なし）では、従来どおり FOOTPRINTS_TOKEN と自動登録の動作が維持されます。

デプロイ

Docker

docker build -t url-manager-mcp .
docker run -e FOOTPRINTS_TOKEN="FA_xxx" url-manager-mcp

ModelScope

ワンクリックでホスト環境にデプロイできます：url-manager-mcp

URL Manager を選ぶ理由

ブラウザーのブックマークは、整理機能も検索機能も共有機能もないフラットなリストです。URL Manager では、次のことができます。

• カテゴリ、カテゴリセット、タグ — 階層的に整理できます
• 全文検索 — すべてのタイトル、説明、URL を横断して検索できます
• デバイス間同期 — 1 台のデバイスで保存し、すべてのデバイスからアクセスできます
• 一括管理 — 数百件のリンクを一度に並べ替えて整理できます
• チームでの共有 — 招待リンクを使って、共同編集可能なコレクションや読み取り専用のコレクションを共有できます
• カード形式での提供 — URL をそのまま送るのではなく、整理されたコレクションを見やすいインターフェースで共有できます