Piccolo123/url-manager-mcp

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.
| 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
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)**
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)