url-manager-mcp

URL Manager MCP Server

[English](./README.md) | [简体中文](./README.zh-CN.md)

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](https://github.com/Piccolo123/url-manager/blob/main/SKILL.md)

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.

| Field | Type | Description |

|-------|------|-------------|

| id | UUID | Permanent unique identifier — use for all operations |

| url | string (8192) | Original link. Can be empty for text-only footprints |

| title | string (512) | Short title |

| description | string (1024) | Additional context or notes |

| content_type | string (50) | Free text (e.g. article, video, image). Use list_content_types() to see existing values |

| category_ids | list[int] | Which categories this belongs to — you assign |

| tag_names | list[str] | Free-form keywords — you assign |

A footprint can belong to multiple categories simultaneously.

Category (a named label)

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

| Field | Type | Description |

|-------|------|-------------|

| id | int | Permanent numeric identifier — always reference by ID |

| name | string (50) | Display name |

| mode | string \| null | null = personal, "cocreate" = shared co-edit, "subscribe" = shared read-only |

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

| | Personal | Shared |

|---|---|---|

| mode | null | "cocreate" or "subscribe" |

| Visible to | Only you | You + invited members |

| Members & invite links | No | Yes |

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

| Action | Owner | Admin | Member |

|--------|:-----:|:-----:|:------:|

| Add/remove footprints (cocreate) | ✅ | ✅ | ✅ |

| Add/remove footprints (subscribe) | ✅ | ❌ | ❌ |

| Generate invite link (cocreate) | ✅ | ✅ | ✅ |

| Generate invite link (subscribe) | ✅ | ❌ | ❌ |

| Switch cocreate ↔ subscribe | ✅ | ❌ | ❌ |

| Manage members | Web UI only | — | — |

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)