使用说明

fm链接存储

Web 能够有效地组织和管理链接的现代AI 的书签管理应用程序。LLM 的自动标记功能Web 接口和MCP (Model Context Protocol) 服务器都可以访问AI 也可以与助手集成。

✨ 特徴

主要机能

🔖 快速URL 注册: URL 粘贴即可自动获取页面信息
🔍 全文検索：标题、说明文、URL 快速查找所需页面（所有标签通用）
🤖 AI 整理: LLM 使用自动标题优化和标记候选方案
🏷️ 基于标记的组织：灵活的标记系统和标记搜索筛选
⭐ 最爱：标记重要书签并快速访问
📊 多个显示模式：可按最近注册访问更新的顺序排序
🎨 两种显示格式：可在卡片格式和列表格式之间切换
📱 反射式设计：台式机和移动式无缝工作

高级功能

🔐 安全认证: PocketBase 基于认证的安全机制
🌐 CORS 获取自由：后端URL 处理捕获CORS 避免问题
📈 访问跟踪：记录访问书签的日期和时间
🌗 主题支持：切换灯光模式和黑暗模式的主题
🔄 实时更新：在所有设备之间同步

MCP 服务器整合

🤝 LLM 统合: AI 直接从聊天应用程序中使用书签
🔑 基于令牌的访问：安全MCP 标记管理
📡 JSON-RPC 2.0：工具调用标准协议
🛠️ 丰富的API: MCP 完整的工具CRUD 操作、搜索和过滤

🏗️ 体系结构

前端+后端配置

┌─────────────────────┐
│  React フロントエンド │  ← ユーザーインターフェース (Vite + React + Tailwind)
│   (ブラウザアプリ)    │
└──────────┬──────────┘
           │ PocketBase JWT 認証
           ↓
┌─────────────────────┐
│   PocketBase        │  ← バックエンド (DB + 認証 + API + 静的サーバー)
│   v0.23 (JSVM)      │
└──────────┬──────────┘
           │
           ├──→ データベース (SQLite)
           ├──→ MCP JSON-RPC サーバー (POST /mcp/bookmark)
           └──→ LLM プロバイダ (OpenAI API 互換)

技术栈

前端：

反应19.1
TypeScript
顺风CSS v4
维特
Zustand (状態管理)
PocketBase SDK

后端：

PocketBase v0.23（JSVM）
SQLite 数据库
JSON-RPC 2.0（MCP）
OpenAI 互换LLM API

🚀 前言

前提条件

Docker (推奨)
Node.js 18+ (前端开发用）
PocketBase v0.23+ (本地开发时）
OpenAI API 兼容服务（例如：OpenRouter, OpenAI)

🐳 Docker 使用（推荐）

构建映像

git clone https://github.com/yourusername/fm-link-stash.git
cd fm-link-stash
docker build -t fm-link-stash .

启动容器

docker run -it --rm -p 8090:8090 \
  -v ./pb_data:/pb/pb_data \
  -v ./pb_public:/pb/pb_public \
  fm-link-stash

初回起动时の管理者作成
- pb_data 如果为空，则在容器启动时显示在控制台日志中superuser 创建URL 访问
- 创建管理员帐户并完成设置

重要： pb_data 目录必须永久。存储数据库和上载的文件。

💻 本地开发

安装和启动

克隆存储库

git clone https://github.com/yourusername/fm-link-stash.git
cd fm-link-stash

设置环境变量

在根目录中 .env 创建文件：

LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://openrouter.ai/api/v1/
LLM_MODEL_NAME=openrouter/auto
HTTP_FETCH_USER_AGENT=fm-link-stash/0.1

PocketBase 设置
- pocketbase.io 从PocketBase 下载
- 项目根目录 pocketbase （或 pocketbase.exe），模板名称将采用不同的格式
- PocketBase 启动：
```
./pocketbase serve --http 0.0.0.0:8090
```
前端开发首选项设置

frontend/.env 创建文件：
```
VITE_API_URL=http://localhost:8090
```
前端启动：
```
cd frontend
npm install
npm run dev
```
开发服务器 http://localhost:5173 启动
CORS 设定

PocketBase 管理画面 (http://localhost:8090/_/的，之Settings > API > CORS origins 开发服务器URL（http://localhost:5173），模板名称将采用不同的格式。

生产部署构建

前端构建
```
cd frontend
npm install
npm run build
```

配置静态文件

# frontend/dist/ の中身を pb_public/ 直下にコピー
cp -r frontend/dist/* pb_public/

因此PocketBase 将条目添加到文档注册表。

首次安装

PocketBase 打开管理屏幕： http://localhost:8090/_/
在初次访问时显示的画面上创建管理员帐户
访问前端以注册或登录新用户

📖 用法

Web 接口，接口

注册书签
- 在页眉的输入栏中URL 粘贴
- Enter 按键
- 应用程序自动获取页面内容，并提出标签
浏览书签
- 在导航选项卡中，按以下条件进行筛选：
  - 最近登録
  - 最近访问
  - 最近更新
  - 最爱
  - 标签列表
搜索和过滤
- 点击标题的检索按钮（放大镜图标）显示检索窗
- 标题、说明文、URL 的关键字实时缩小范围
- 在保持当前标签的排序顺序（访问顺序、注册顺序等）的情况下显示搜索结果
- 单击标记列表中的标记以显示相关书签
管理书签
- 点击编辑按钮标题URL、更改标记
- 单击星形图标切换收藏夹
- 单击书签打开（记录访问时间）

MCP 服务器（AI助手）

MCP 生成标记
- 登录前端
- 转到配置/标记
- 新的MCP 创建标记

AI 助手设置 MCP 添加服务器设置：

{
  "mcpServers": {
    "fm-link-stash": {
      "url": "http://127.0.0.1:8090/mcp/bookmark",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}

可用的MCP 工具
- bookmark.createFromUrl -注册新书签
- bookmark.list -搜索和过滤书签
- bookmark.get -获取书签详细信息
- bookmark.update -编辑书签
- bookmark.delete -删除书签
- bookmark.toggleFavorite -切换收藏夹状态
- bookmark.registerAccess -记录访问
- tag.listWithCounts -获取标记统计信息
- tag.search -查找标记
- token.introspect -确认标记状态

🔧 设定

环境变数

｜变量名｜说明｜默认值｜ |--------|------|-------------| | LLM_API_KEY | LLM 提供程序API 关键字｜必需｜ | LLM_BASE_URL | LLM API 基础URL | https://openrouter.ai/api/v1/ | | LLM_MODEL_NAME 默认模型名称 openrouter/auto | | HTTP_FETCH_USER_AGENT | URL 检索时的User-Agent | fm-link-stash/0.1 | | FETCH_TIMEOUT_MS | URL 捕获超时 15000 | | MAX_FETCH_SIZE_BYTES 要检索的页面的最大大小 4194304 （4MB）|

安全设置

后端实施以下安全措施：

SSRF 保护：私有IP 阻止访问范围
URL 検证：检索前URL 验证规范化
汇率限制：按用户限制汇率以防止滥用
Content-Type 検证: HTML 仅检索内容
令牌认证：安全MCP 标记管理

📚 API 文档

MCP JSON-RPC 端点

端点： POST /mcp/bookmark

认证：

Authorization: Bearer {MCP_TOKEN}

请求格式（JSON-RPC2.0）：

{
  "jsonrpc": "2.0",
  "method": "bookmark.createFromUrl",
  "params": {
    "url": "https://example.com",
    "options": {
      "dedupe": true
    }
  },
  "id": "1"
}

响应格式：

{
  "jsonrpc": "2.0",
  "result": {
    "data": {
      "id": "abc123",
      "title": "Example Page",
      "url": "https://example.com",
      "tags": ["example", "website"],
      "registered_at": "2025-01-01T00:00:00Z"
    }
  },
  "id": "1"
}

详细信息API 关于规格 docs/03_mcp_tools_specifications.md 来修改标记元素的显示属性。

🗄️ 数据库架构

应用程序使用以下主要集合：

用户 -用户帐户（PocketBase认证）
书签 -带元数据的书签记录
标签 -颜色标记定义
书签标签 -多对多关系
mcp令牌 - MCP 访问标记

有关详细的架构信息，请参见 docs/02_db.er.md 来修改标记元素的显示属性。

📁 目录配置

fm-link-stash/
├── frontend/          # フロントエンドソースコード
│   ├── src/           # React アプリケーション
│   ├── dist/          # ビルド成果物（npm run build 後）
│   └── .env           # 開発時の環境変数
├── pb_public/         # PocketBase が配信する静的ファイル
│                   # (frontend/dist の内容をここにコピー)
├── pb_data/           # PocketBase データベースとアップロードファイル
│                   # ※必ずバックアップ・永続化が必要
├── pb_hooks/          # PocketBase JSVM フック
├── pb_migrations/     # データベースマイグレーション
├── .env               # バックエンド環境変数
├── pocketbase         # PocketBase バイナリ（ローカル開発時）
└── Dockerfile         # Docker イメージビルド用

📋 备份和还原

备份

服务器停止: PocketBase 停止

数据存档: pb_data/ 存档整个目录

tar -czf backup-$(date +%Y%m%d-%H%M%S).tar.gz pb_data/

恢复

服务器停止: PocketBase 停止
数据还原：备份 pb_data/ 替换为
服务器重新启动: PocketBase 重新启动

🛣️ 路线图

[ ] Favicon 文件保存（当前为URL 保存）
[]导入/导出功能（HTML，JSON）
[]浏览器扩展功能
[]高级过滤选项

🤝 分发

欢迎分享！请随便Pull Request 中所述修改相应参数的值。

分叉存储库
创建特征分支（git checkout -b feature/AmazingFeature)
提交更改（git commit -m 'Add some AmazingFeature')
推到分支（git push origin feature/AmazingFeature)
Pull Request 的双曲正切值

📝 许可证

这个项目MIT 在许可证下被许可。了解更多信息许可证请参见文件。

🙏 谢辞

PocketBase -很好BaaS (Backend as a Service)
反应 -前端框架
顺风 CSS -造型
模型上下文协议 - AI 统合标准

📞 支持

如果出现问题或有问题：

GitHub 的Issue 的双曲正切值
文档确认

👤 作者

雷罗富米

⭐ 如果你觉得这个项目有用GitHub 如果能加上明星的话我会很高兴的！