Content
# Tool List
> Integrate web clipping into one VPS,
> Automatically AI summarize / tag / save to Obsidian vault,
> Local machine sync in real-time via fast-note-sync plugin.
## What is this?
A web clipping + sync gateway deployed on a VPS. It collects inputs from three sources into your Obsidian vault:
1. **Browser Web Clipper extension** (based on SingleFile) - One-click package webpage into HTML and upload
2. **AI clients** (Cursor / Claude Desktop / Cherry Studio) - Read and write notes via MCP SSE
All paths lead to the vault managed by [fast-note-sync-service](https://github.com/haierkeys/fast-note-sync-service). The local Obsidian syncs in real-time (millisecond-level) via [fast-note-sync plugin](https://github.com/haierkeys/obsidian-fast-note-sync).
## Architecture
```
Browser extension
(SingleFile)
│
POST /api/upload
│
▼
┌──────────────┐
│ Traefik │ TLS / Let's Encrypt
└──────┬───────┘
│
┌──────▼───────────────────────────┐
│ web_clipper │
│ ① /upload │
│ GitHub Pages snapshot │
│ Jina → Markdown │
│ OpenAI summarize + tag │
│ → Write to FNS │
│ │
└──────────────┬───────────────────┘
│ REST
▼
┌──────────────────────────────────┐
│ fast-note-sync-service │
│ │
│ · File storage + SQLite history │
│ · S3/R2/WebDAV backup │
│ · WebSocket /api/user/sync ─────┼──→ Local Obsidian
│ · MCP /api/mcp/sse ──────┼──→ Cursor/Claude
└──────────────────────────────────┘
```
See [docs/architecture.md](docs/architecture.md) for details.
## Quick Start
### 0. Prerequisites
- A public VPS with Linux (≥ 1 GB RAM)
- A domain with two A/AAAA records:
- `example.com` → VPS IP
- `sync.example.com` → VPS IP
- Docker + Docker Compose installed
### 1. Clone and configure
```bash
git clone https://github.com/yefeng8771/obsidian-clipper-gateway.git
cd obsidian-clipper-gateway
cp .env.example .env
# Update at least these: DOMAIN / ACME_EMAIL / API_KEY / FNS_TOKEN
# And GITHUB_* / OPENAI_API_KEY (if using browser extension clipping)
$EDITOR .env
```
Generate random keys:
```bash
echo "API_KEY=$(openssl rand -hex 32)"
echo "FNS_TOKEN=(Copy from fast-note-sync backend API Configuration)"
```
### 2. Start
```bash
docker compose up -d
docker compose logs -f
```
Traefik will automatically request a Let's Encrypt certificate on the first start (about 30 seconds).
### 3. Create token in fast-note-sync backend
```bash
docker compose logs fast-note-sync-service | grep -i "admin\|password\|token" | head
# Or open https://sync.example.com and follow the web guide
```
Fill the generated token back into `.env`'s `FNS_TOKEN`, then `docker compose up -d` to reload web_clipper.
### 4. Verify three things
```bash
KEY=<your API_KEY>
DOMAIN=example.com
# Status
curl -H "Authorization: Bearer $KEY" https://$DOMAIN/api/
# Write a note
curl -X PUT \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: text/markdown" \
--data $'# Hello\n\nFrom obsidian-clipper-gateway' \
https://$DOMAIN/api/vault/Inbox/test.md
# List files
curl -H "Authorization: Bearer $KEY" https://$DOMAIN/api/vault/
```
If successful, your local Obsidian should see `Inbox/test.md` within a few hundred milliseconds (assuming fast-note-sync plugin is configured, see below).
### 5. Configure local Obsidian
Open Obsidian → Settings → Community plugins → Browse → search **Fast Note Sync** → Install and enable:
| Field | Fill method |
| -------- | --------------------------------------- |
| Endpoint | `https://sync.example.com` |
| Token | Same as `.env`'s `FNS_TOKEN` |
| Vault | `Inbox` (or your `.env`'s `FNS_VAULT`) |
See [docs/obsidian-plugin.md](docs/obsidian-plugin.md) for details.
### 6. Configure browser extension
If you previously used goxofy's [SingleFile + web_clipper](https://github.com/goxofy/web_clipper) workflow, update the extension settings:
| Field | New value |
| ------------ | --------------------------------- |
| Upload URL | `https://example.com/api/upload/` |
| Bearer Token | `.env`'s `API_KEY` |
See [docs/browser-extension.md](docs/browser-extension.md) for details.
## Directory Structure
```
obsidian-clipper-gateway/
├── README.md ← This document
├── LICENSE ← MIT (covers modifications/additions)
├── ATTRIBUTION.md ← Upstream acknowledgments and licenses
├── docker-compose.yml
├── .env.example
├── app/ ← web_clipper service (based on goxofy/web_clipper)
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── main.py
│ ├── config.py ← Remove NOTION_*, add FNS_*
│ ├── web_clipper.py ← save_to_notion → save_to_fns
│ └── vault_api.py ← New: Local REST API compatibility layer
├── docs/
│ ├── architecture.md
│ ├── deploy.md
│ ├── browser-extension.md
│ ├── obsidian-plugin.md
│ ├── dataview-recipes.md
│ └── troubleshooting.md
├── examples/
│ └── dataview-clippings-index.md
└── .github/
└── ISSUE_TEMPLATE/
└── upstream-license-notice.md
```
## Replaced/Not Replaced
| Original capability | This repository's handling |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Notion database as clipping dir | **Removed**. Use Obsidian + Dataview to dynamically generate dir views ( [recipes](docs/dataview-recipes.md) ) |
| GitHub Pages hosting HTML snapshots | **Retained**. Clipped HTML still hosted on GitHub Pages, with `snapshot:` field in frontmatter |
| OpenAI generating summaries + tags | **Retained**. Saved in frontmatter |
| Telegram notifications | **Retained**. Optional |
| Real-time sync to local Obsidian | **Added**. fast-note-sync's WebSocket plugin |
## Documentation Index
- [Architecture](docs/architecture.md) — Data flow / sequence / key decisions
- [Deploy](docs/deploy.md) — Complete VPS deployment process
- [Browser extension integration](docs/browser-extension.md) — SingleFile-based extension
- [Local Obsidian configuration](docs/obsidian-plugin.md) — fast-note-sync plugin
- [Dataview recipes](docs/dataview-recipes.md) — Alternative to Notion views
- [Troubleshooting](docs/troubleshooting.md)
## Upstream Acknowledgments
This repository is based on the following open-source/public projects:
- [goxofy/web_clipper](https://github.com/goxofy/web_clipper) — Clipping pipeline and GitHub Pages / OpenAI / Telegram integration code
- [haierkeys/fast-note-sync-service](https://github.com/haierkeys/fast-note-sync-service) — Vault backend
- [haierkeys/obsidian-fast-note-sync](https://github.com/haierkeys/obsidian-fast-note-sync) — Obsidian sync plugin
- [coddingtonbear/obsidian-local-rest-api](https://github.com/coddingtonbear/obsidian-local-rest-api) — Compatibility protocol specification
See [ATTRIBUTION.md](ATTRIBUTION.md) for details.
## License
This repository's modifications/additions are licensed under [MIT](LICENSE).
Upstream `goxofy/web_clipper` code has **no declared license**, see [ATTRIBUTION.md](ATTRIBUTION.md).
