URL Manager MCP Server

English | 简体中文

Deliver results as beautiful cards, not raw link dumps. A Model Context Protocol server for saving, organizing, searching, and sharing web resources — cross-device sync, categories, tags, full-text search, batch operations, and team sharing. 21 tools with auto-registration so no manual setup is required.

📖 Usage patterns and best practices → URL Manager Skill

What This Tool Gives Humans

The content human users want to save is everywhere — a YouTube workout video, an Amazon gear link, a Substack training plan — scattered across platforms with no connection.

URL Manager fixes this. Paste any link from any platform. AI auto-identifies the content and suggests a category — confirm and it's a footprint. All saves flow into one platform-agnostic library, organized and always findable. Then share in one click — hand your curated knowledge base to your team, and everyone stays in sync.

System Concepts

Footprint (the fundamental unit)

A structured, searchable record — a web link, a plain-text note, an idea, or anything worth saving.

A footprint can belong to multiple categories simultaneously.

Category (a named label)

Like a folder, but a footprint can be in several at once.

Category Set (a workspace)

A container that groups related categories. Every user starts with "My Categories" (personal) and "Shared Categories" (shared container).

Data hierarchy

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

Personal vs Shared

Cocreate — everyone adds/removes footprints. Subscribe — read-only for members (writing returns 403).

Tools

Registration & Identity

• agent_register() Create a new account. No parameters. Token is auto-applied for all subsequent calls. ⚠️ Call once only — each invocation creates a fresh account.

• my_info() Verify connection and token validity. Returns username and membership status.

Bookmarks

• search_footprints(query, limit, offset) Full-text search across titles, descriptions, and URLs.

  • query (required) — Search keywords
  • limit — Results per page (default 10, max 100)
  • offset — Pagination offset (default 0)

• list_footprints(category_id, limit, offset) List bookmarks by category. category_id=0 returns all.

  • limit — Results per page (default 20, max 100)
  • offset — Pagination offset (default 0)

• get_footprint(footprint_id) Get full details of a single bookmark.

  • footprint_id (required) — From list_footprints or search_footprints results (field id)

• add_footprint(url, title, description, category_ids, tag_names) Add a new bookmark. Call list_categories() and list_tags() first to discover existing structure.

  • url (required) — Web page URL
  • title — Leave empty to auto-extract from the page
  • description — Summary or notes
  • category_ids — Comma-separated IDs, e.g. "1,3"
  • tag_names — Comma-separated names, e.g. "AI,tutorial"

• update_footprint(footprint_id, title, description, category_ids, tag_names) Update a bookmark. Omitted fields stay unchanged. ⚠️ category_ids replaces the entire list — not append. Call get_footprint() first, then merge IDs.

  • footprint_id (required) — From search or list results

Categories & Tags

• list_categories() List all categories (personal + shared). Returns id, name, and mode fields. mode=null → personal; mode="cocreate"/"subscribe" → shared.

• create_category(name, category_set_id) Create a new category. Check list_categories() first to avoid duplicates.

  • name (required) — Category name
  • category_set_id — Parent category set (0 = default)

• list_tags() List all tags used by this account.

• list_content_types() List all content types the user has used (e.g. article, video, image), ordered most-used first. Use before adding to pick a consistent content_type.

Category Sets

• list_category_sets() List all category sets.

• create_category_set(name) Create a new category set (a container of categories).

  • name (required) — Category set name

Shared Categories

• create_shared_category(name, mode, description) Create a shared category for team collaboration.

  • name (required)
  • mode (required) — "cocreate" (multiple editors) or "subscribe" (read-only)
  • description — Optional description ⚠️ In subscribe mode, adding bookmarks returns 403. Use "cocreate" for editable collaboration.

• create_invite_link(shared_category_id, duration_hours) Generate an invite link for others to join.

  • shared_category_id (required) — From list_categories() (shared entries)
  • duration_hours — Default 24

• join_shared_category(invite_code) Join a shared category by invite code.

  • invite_code (required) — 8-character code from the invite link

• add_to_shared_category(shared_category_id, footprint_id) Add one of your own bookmarks to a shared category.

  • Both parameters required

• remove_from_shared_category(shared_category_id, footprint_id) Remove a bookmark from a shared category. Does not delete the bookmark itself.

  • Both parameters required

• copy_footprint(footprint_id, category_ids) Copy a bookmark from a shared category into your personal collection.

  • Both parameters required

Batch & Delivery

• batch_update_footprints(updates) Bulk edit up to 50 bookmarks at once.

  • updates (required) — JSON string: [{"id":"...", "title":"New Title", "category_ids":"1,3"}, ...] Each object may contain title, description, category_ids, tag_names; id is required.

• agent_magic_link() 🔑 The delivery loop core. After organizing, generate a link → send to user. They click to see a card-based interface with all their organized bookmarks. Valid for 30 days, reusable.

Workflows

New User — Zero Setup

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

Returning User — Daily Use

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

Create Shared Category

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)

⚠️ Critical Pitfalls

category_ids REPLACES, not appends

# ❌ 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")

Subscribe mode is READ-ONLY

Writing to a subscribe-mode shared category returns 403. If the user says "I subscribed but can't add anything", explain it's read-only — the creator needs to change it to cocreate.

NEVER call agent_register twice

Each call creates a fresh empty account. Always check for a saved token first. If unsure, call my_info() to verify the current token is valid.

Rate Limiting

Rapid consecutive calls may trigger HTTP 429. Add short delays between batch operations; on 429, wait a few seconds and retry.

No member management via API

Inviting or removing members from shared categories requires the web UI at https://ai.ocean94.com. You cannot do this programmatically.