# AgentClip

Clip selected browser text — with a confirm/edit step — into a personal store on
Cloudflare, then retrieve it from **AI agents (MCP)** and tools over a
per-user-token-authenticated **REST API**.

- **agent** — AI clients reach your clips over MCP / REST with a per-user token.
- **clip** — a Chrome extension (Manifest V3) adds a "Save to AgentClip" context menu;
  you edit the text before it's saved.

Production runs as a **single Cloudflare Worker** at `https://agentclip.0xkaz.com` serving
the API, the MCP server, Google OAuth, and the dashboard from one origin.

- **Live app:** https://agentclip.0xkaz.com
- **Source:** https://github.com/0xkaz/agentclip
- **日本語版 README:** [README.ja.md](README.ja.md)

## Features

- **Clip & edit** — right-click any selection → edit content/title/tags/source → save.
- **Keyword search** — substring match over content/title/tags (works for Japanese too).
- **Semantic search** — meaning-based search via Workers AI embeddings + Vectorize.
- **Per-clip encryption** — mark a clip to encrypt it at rest; encrypted clips are
  excluded from search (and shown masked, with a reveal toggle).
- **Share links** — publish a single clip at a public read-only `/s/<slug>` URL; revoke
  anytime (encrypted clips can't be shared).
- **MCP + REST** — AI agents and tools read/write your clips with a per-user token.
- **Google sign-in** for the dashboard; opaque per-user Bearer tokens for machines.

## Use the hosted app

The fastest path — no local setup:

1. Open **https://agentclip.0xkaz.com** and **Sign in with Google**.
2. Go to **API Tokens** → create a token (`ac_live_…`, shown once — copy it).
3. Open **Setup & Usage** in the app — it shows your exact MCP config and `curl`
   examples, plus the Chrome-extension steps below.

The dashboard has three pages:

| Page | What it does |
|------|--------------|
| **Snippets** | Browse, add/edit/delete, keyword & semantic search your clips |
| **API Tokens** | Create / revoke per-user Bearer tokens |
| **Setup & Usage** | Copy-paste MCP config, REST `curl`, and extension setup |

## Monorepo layout

```
apps/api         Cloudflare Worker — REST + MCP + Google OAuth, D1, serves dashboard
apps/web         React + Vite dashboard — landing page + Snippets / Tokens / Setup
apps/extension   Chrome MV3 extension — capture + confirm/edit
packages/shared  shared TypeScript types
```

The rest of this README covers running and deploying it yourself.
Requirements: **Node 20+**, **pnpm 9+** (`npm i -g pnpm`), a Cloudflare account, and a
Google OAuth client.

---

## 1. Clone & install

```sh
git clone https://github.com/0xkaz/agentclip.git
cd agentclip
pnpm install      # or: make install
```

## 2. Configure Cloudflare D1

```sh
pnpm --filter @agentclip/api exec wrangler d1 create agentclip
```

Paste the returned `database_id` into **both** `[[d1_databases]]` blocks in
`apps/api/wrangler.toml` (the top-level one and the `[env.production]` one).

```sh
make db-init                # apply schema.sql to the LOCAL D1
# later, for production:
pnpm --filter @agentclip/api db:init:remote
```

## 3. Configure Google OAuth

In Google Cloud Console → Credentials → create an **OAuth client ID (Web application)**.
Add authorized redirect URIs:

- Local: `http://localhost:8787/auth/google/callback`
- Production: `https://agentclip.0xkaz.com/auth/google/callback`

Then create local secrets:

```sh
cp apps/api/.dev.vars.example apps/api/.dev.vars
# edit apps/api/.dev.vars:
#   GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, SESSION_SECRET (any random 32+ byte string)
```

## 4. Run locally

```sh
make dev                              # API + MCP on http://localhost:8787
pnpm --filter @agentclip/web dev      # dashboard on http://localhost:5173
```

Open `http://localhost:5173`, sign in with Google, and create an API token.

## 5. Install the Chrome extension

```sh
pnpm --filter @agentclip/extension build      # outputs apps/extension/dist
```

1. Open `chrome://extensions` → enable **Developer mode**.
2. **Load unpacked** → select `apps/extension/dist`.
3. Click the AgentClip icon → set **API base URL** and paste the **token** from the dashboard.
   - Local: `http://localhost:8787`
   - Production: `https://agentclip.0xkaz.com`
4. Select text on any page → right-click → **Save to AgentClip** → edit → **Save**.

## 6. Deploy to production (`agentclip.0xkaz.com`)

```sh
# one-time: set production secrets
pnpm --filter @agentclip/api exec wrangler secret put GOOGLE_CLIENT_ID --env production
pnpm --filter @agentclip/api exec wrangler secret put GOOGLE_CLIENT_SECRET --env production
pnpm --filter @agentclip/api exec wrangler secret put SESSION_SECRET --env production
pnpm --filter @agentclip/api db:init:remote        # schema on remote D1

make deploy        # builds the dashboard, then deploys the Worker (--env production)
```

> The custom domain route (`agentclip.0xkaz.com`) requires the Cloudflare API token to
> have **Zone:Edit** on `0xkaz.com` in addition to Workers/D1 edit. Without it, deploy
> the Worker and bind the domain from the dashboard, or use the `*.workers.dev` URL.

---

## Using the REST API

```sh
# save (add "encrypted": true to encrypt at rest + exclude from search)
curl -X POST https://agentclip.0xkaz.com/api/snippets \
  -H "Authorization: Bearer ac_live_..." \
  -H "Content-Type: application/json" \
  -d '{"content":"hello","tags":"demo"}'

# keyword search (substring; works for Japanese)
curl "https://agentclip.0xkaz.com/api/snippets?q=hello" -H "Authorization: Bearer ac_live_..."

# semantic search (meaning-based)
curl "https://agentclip.0xkaz.com/api/snippets?q=greeting&mode=semantic" -H "Authorization: Bearer ac_live_..."

# update / delete
curl -X PATCH  https://agentclip.0xkaz.com/api/snippets/1 -H "Authorization: Bearer ac_live_..." -H "Content-Type: application/json" -d '{"content":"updated"}'
curl -X DELETE https://agentclip.0xkaz.com/api/snippets/1 -H "Authorization: Bearer ac_live_..."
```

## Using MCP

Point an MCP client at `https://agentclip.0xkaz.com/mcp` with header
`Authorization: Bearer ac_live_...`. Tools: `store_snippet`, `search_snippets`,
`semantic_search`, `get_snippet`, `list_recent`, `update_snippet`, `delete_snippet`.

> Semantic search indexes new clips automatically; to index clips made earlier, open the
> **Snippets** page, switch to **Semantic**, and click **Rebuild index** (or
> `POST /api/my/reindex`). Vectorize is eventually consistent (new clips become
> searchable within ~1 minute).

See [docs/architecture.md](docs/architecture.md) and
[docs/agent-workflow.md](docs/agent-workflow.md) for details.