# Favorites MCP

[English](README.en.md) | **简体中文**

**让任意支持 MCP 的 AI Agent，在用户始终掌控的前提下整理真实的
Microsoft Edge / Google Chrome 收藏夹。**

用自然语言让 Claude、Copilot、Cursor 或其他 MCP Host 查重、重组目录、排序、
移动、重命名、创建和清理收藏夹。项目不绑定模型厂商，不操作浏览器页面，也不
直接修改 Profile 文件。

## 导航

- [为什么做这个项目](#为什么做这个项目)
- [核心能力](#核心能力)
- [如何工作](#如何工作)
- [快速开始](#快速开始)
- [完整文档](#完整文档)

> 当前版本：`0.1.0`。目前通过源码 sideload 分发，尚未上架浏览器扩展商店或 npm。

> [!WARNING]
> **执行写入前请先备份收藏夹。**初次使用请保持人工审批，并优先使用“移入回收站
> 文件夹”。快照和回滚只是尽力而为，不能替代浏览器备份。

## 为什么做这个项目

现有开源方案通常侧重于直接编辑 Profile 文件、通用浏览器自动化、独立 AI 书签库，
或由 Agent 自己传入 `dry_run` / `confirm` 的直接 CRUD。Favorites MCP 补充的是
**Agent 与真实浏览器收藏夹之间、独立于 Agent 的用户控制层**：

| 重点 | 行为 |
| --- | --- |
| 任意 MCP Agent | 标准 stdio MCP 接口，不绑定聊天客户端或模型 API |
| 真实浏览器数据 | 通过 `chrome.bookmarks` 操作当前 Profile，不维护第二份书签库 |
| 浏览器侧审批 | Agent 提交计划，扩展独立执行权限、审批和删除策略 |
| 隐私先于可见性 | 私密目录和敏感 URL 值在离开扩展前过滤 |
| 并发安全 | 计划绑定树指纹；收藏夹变化后拒绝过期写入 |
| 恢复与追踪 | 快照、HTML 备份、审计、回收站和冲突安全的尽力回滚 |

其他项目可能更适合网页自动化、语义知识库或跨浏览器同步；本项目只专注于安全地
让 AI 整理浏览器原生收藏夹。

## 核心能力

- 分页读取大型收藏夹树，并按规范化完整 URL 查找重复项。
- 创建多级文件夹和新收藏项，移动、重命名、排序及删除。
- 每种读写能力可独立关闭；每种写操作可设为整批审批、逐项确认或自动批准。
- 删除默认关闭，可优先移动到用户指定的回收站目录。
- 私密目录及全部后代不会进入读取、分页、查重、计划或 Agent 可见指纹。
- URL 脱敏规则覆盖敏感参数、内嵌密码及结构有效的 JWT/JWE，也支持 RE2JS 自定义规则。
- 单 Profile 连接锁、异步执行队列、执行前快照和本地审计。

## 如何工作

```mermaid
flowchart LR
    A["AI Agent / MCP Host"] <-->|"stdio MCP"| M["本地 Node.js Server"]
    M <-->|"127.0.0.1 + 256 位配对令牌"| E["Edge / Chrome 扩展"]
    U["用户"] -->|"权限、审批、备份"| E
    E <-->|"chrome.bookmarks"| B[("真实浏览器收藏夹")]
```

只有浏览器扩展持有 `bookmarks` 权限。Server 只监听回环地址，并且一次锁定一个完成
鉴权的浏览器 Profile。Agent 只能读取扩展允许的数据、提交计划和轮询结果，不能绕过
扩展内的权限、私密目录或审批策略。

## 快速开始

要求：macOS、Node.js 20+、Edge 或 Chrome，以及支持 stdio MCP Server 的 AI 客户端。

1. 克隆、构建并生成本机私有配置：

   ```bash
   git clone https://github.com/lizy14/favorites-mcp.git
   cd favorites-mcp
   npm install
   npm run build
   node dist/index.js setup
   ```

2. 在 `edge://extensions` 或 `chrome://extensions` 开启开发者模式，加载 setup 输出的
   生成目录，默认是 `~/.config/favorites-mcp/extension`。**不要直接加载仓库里的
   `extension/` 源码目录。**
3. 打开扩展设置，填写 setup 输出的 Bridge URL 和配对令牌。不要把令牌放进聊天、
   Issue、日志或 MCP 配置。
4. 把下面条目合并到 MCP 客户端配置；将路径替换为仓库的真实绝对路径：

   ```json
   {
     "mcpServers": {
       "favorites": {
         "tools": ["*"],
         "type": "stdio",
         "command": "node",
         "args": [
           "/absolute/path/to/favorites-mcp/dist/index.js",
           "serve"
         ]
       }
     }
   }
   ```

5. 完全重启 MCP 客户端，确认扩展显示已连接，再从 `favorites_status` 开始。首次使用
   请逐项配置权限并保持人工审批。

setup 不会常驻启动 Server；MCP 客户端负责启动 `serve` 进程。多 Profile、自定义
端口和配置路径、Copilot CLI 路径、令牌轮换及故障排查见[安装与配置](docs/setup.md)。

## 完整文档

| 文档 | 内容 |
| --- | --- |
| [安装与配置](docs/setup.md) | 构建、sideload、配对、MCP 客户端、多 Profile、升级与故障排查 |
| [使用指南](docs/usage.md) | 权限、审批、URL 脱敏、对话流程、备份、审计与 MCP 工具 |
| [设计与安全](docs/design.md) | 架构图、写入时序、信任边界、并发、恢复、安全与隐私模型 |
| [English documentation](README.en.md#documentation) | 对应的完整英文文档入口 |
| [安全策略](SECURITY.md) | 支持版本、漏洞报告与安全边界 |
| [贡献指南](CONTRIBUTING.md) | 开发、验证和提交要求 |
| [第三方声明](THIRD_PARTY_NOTICES.md) | Bundled dependency attribution |

## 当前限制

- 当前设置页和审批 UI 只有中文，安装说明以 macOS 为主。
- 一个 Server 实例只接受一个活动 Profile；多 Profile 需要独立端口、令牌和配置。
- 完整树读取上限为 1,000 个节点，单份计划最多 200 项。
- 回滚不是数据库事务；永久删除无法恢复原浏览器 ID。
- 当前没有商店签名版本或自动更新。

Favorites MCP 是独立开源项目，与 Google 或 Microsoft 没有隶属、赞助或背书关系。
项目采用 [Apache License 2.0](LICENSE)。

## 开发方式

本项目主要由 GitHub Copilot 设计和实现，由人类维护者提供产品方向、风险决策与审查。