url-manager-mcp

URL Manager MCP Server

English | 简体中文

以精美卡片呈现结果，而不是原始链接清单。 一个用于保存、整理、搜索和分享网络资源的模型上下文协议服务，支持跨设备同步、分类、标签、全文搜索、批量操作和团队分享。提供 21 个工具，支持自动注册，无需手动设置。

📖 使用模式和最佳实践 → URL Manager Skill

这个工具为用户带来的价值

用户想要保存的内容无处不在——YouTube 上的健身视频、Amazon 上的装备链接、Substack 上的训练计划——散落在各个平台，彼此之间毫无关联。

URL Manager 解决了这个问题。 粘贴任意平台上的链接。AI 会自动识别内容并推荐分类——确认后即可保存。所有内容都会汇集到一个不受平台限制的资料库中，井然有序，随时可查。然后，一键分享——将你精心整理的知识库交给团队，所有人都能保持同步。

系统概念

足迹（基本单位）

一条结构化、可搜索的记录——可以是网页链接、纯文本笔记、想法，或任何值得保存的内容。

字段	类型	说明
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]	自由格式的关键词——由你指定

一个足迹可以同时属于多个分类。

分类（命名标签）

类似文件夹，但一个足迹可以同时归入多个分类。

字段	类型	说明
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 界面	—	—

工具

注册与身份

• agent_register() 创建新账户。无需参数。后续所有调用都会自动应用令牌。 ⚠️ 仅调用一次——每次调用都会创建一个新账户。

• my_info() 验证连接和令牌是否有效。返回用户名和成员身份状态。

书签

• search_footprints(query, limit, offset) 在标题、描述和 URL 中进行全文搜索。

  • query (必填) — 搜索关键词
  • limit — 每页结果数（默认 10，最多 100）
  • offset — 分页偏移量（默认 0）

• list_footprints(category_id, limit, offset) 按类别列出书签。category_id=0 表示返回全部书签。

  • limit — 每页结果数（默认 20，最多 100）
  • offset — 分页偏移量（默认 0）

• get_footprint(footprint_id) 获取单个书签的完整详情。

  • footprint_id (必填) — 来自 list_footprints 或 search_footprints 的结果（字段 id）

• add_footprint(url, title, description, category_ids, tag_names) 添加新书签。请先调用 list_categories() 和 list_tags()，了解现有结构。

  • url (必填) — 网页 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 (必填) — 来自搜索或列表结果

类别和标签

• list_categories() 列出所有类别（个人和共享）。返回 id、name 和 mode 字段。 mode=null → 个人类别；mode="cocreate"/"subscribe" → 共享类别。

• create_category(name, category_set_id) 创建新类别。请先检查 list_categories()，以避免重复。

  • name (必填) — 类别名称
  • category_set_id — 父类别集（0 = 默认）

• list_tags() 列出此账户使用的所有标签。

• list_content_types() 列出用户使用过的所有内容类型（例如文章、视频、图片），按使用频率从高到低排序。添加内容前请先调用，以选择一致的 content_type。

类别集

• list_category_sets() 列出所有类别集。

• create_category_set(name) 创建新的类别集（用于容纳类别的集合）。

  • name (必填) — 类别集名称

共享类别

• create_shared_category(name, mode, description) 创建共享类别，以便团队协作。

  • name (必填)
  • mode (必填) — "cocreate"（多位编辑者）或 "subscribe"（只读）
  • description — 可选描述 ⚠️ 在 subscribe 模式下，添加书签会返回 403。如需可编辑协作，请使用 "cocreate"。

• create_invite_link(shared_category_id, duration_hours) 生成邀请链接，供他人加入。

  • shared_category_id (必填) — 来自 list_categories()（共享条目）
  • duration_hours — 默认 24

• join_shared_category(invite_code) 使用邀请码加入共享类别。

  • invite_code (必填) — 邀请链接中的 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。如果用户说“我订阅了，但什么都加不了”，请说明该分类为只读 — 创建者需要将其改为协作模式。

绝不要调用两次 agent_register

每次调用都会创建一个全新的空账户。务必先检查是否保存了令牌。如不确定，请调用 my_info() 验证当前令牌是否有效。

速率限制

连续快速调用可能触发 HTTP 429。批量操作之间应稍作停顿；遇到 429 时，等待几秒后重试。

无法通过 API 管理成员

邀请或移除共享分类的成员需要通过 https://ai.ocean94.com 网页界面进行。无法通过编程方式完成。

指南

始终

• 静默自动注册 — 绝不要因账户设置而打断用户
• 先搜索，再列出 — 对于有针对性的查询，请使用 search_footprints，而不是倾倒所有内容
• 先发现，再创建 — 添加前调用 list_categories() 和 list_tags()，避免重复
• 通过魔法链接交付 — 整理完成后，务必生成并分享链接

操作前确认

• 移除书签与分类的关联（不可撤销）
• 清除标签
• 修改协作模式的共享分类（会影响他人）
• 从共享分类中移除书签（其他成员将失去访问权限）

与常用 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

Agent 只需将上游 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 / 托管连接器）

对于通过 Streamable HTTP（--http）运行的多用户平台，例如 WorkBuddy 连接器，服务会忽略 FOOTPRINTS_TOKEN。每个请求都必须在 Authorization 标头中携带 调用者自己的令牌（Bearer FA_xxx）；该令牌只会传递给该用户对应的 URL Manager API，因此并发用户之间相互隔离。 未携带令牌的请求会返回友好的 missing_access_token 错误，并指引用户前往 https://ai.ocean94.com → 个人中心 → 接入Agent → 访问令牌；此模式下会禁用 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
• 跨设备同步 — 在一台设备上保存，即可在所有设备上访问
• 批量管理 — 一次排序和整理数百个链接
• 团队共享 — 通过邀请链接共同编辑和共享只读集合
• 卡片式交付 — 将整理好的集合以精美界面呈现，而非原始 URL