# Defuddle Clip MCP

[![Tests](https://github.com/eothL/defuddle-clip-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/eothL/defuddle-clip-mcp/actions/workflows/test.yml)

Clip webpages and YouTube transcripts into Obsidian from your AI assistant.

A small, local MCP server powered by [Defuddle](https://github.com/kepano/defuddle). No browser extension or API key required.

```text
URL → extract_url → Markdown preview → save_clip → Obsidian
```

## Quick start

You need **Node.js 22.12+**, an MCP client that supports local stdio servers, and a local Obsidian vault if you want to save notes.

```sh
git clone https://github.com/eothL/defuddle-clip-mcp.git
cd defuddle-clip-mcp
npm ci
npm run setup
```

Setup asks for your vault's absolute path and clipping folder, then generates `mcp-config.local.json`. Add its server entry to your MCP client's settings without replacing your other servers. For clients with a form or another config format, copy the `command`, `args`, and environment variables into the matching fields.

Set the tool timeout to **120 seconds or more**, then reconnect the client. Ask:

> Extract this URL and save it to my Obsidian vault: [URL]

The client launches the server automatically; you do not need to run `npm start` separately. Rerun setup if you move the repository or change Node's installation path.

## Tools

| Tool | Purpose |
|---|---|
| `extract_url` | Return readable Markdown, metadata, and a clip ID. |
| `save_clip` | Save that clip to your configured vault and optionally open it. |

### Extract

```json
{
  "url": "https://www.youtube.com/watch?v=VIDEO_ID",
  "language": "en",
  "require_transcript": true,
  "force_refresh": false
}
```

Only `url` is required. YouTube URLs require a transcript by default. Results include `markdown`, `clip_id`, `transcript_present`, `warnings`, `cached`, and `extracted_at`.

### Save

```json
{
  "clip_id": "ID_FROM_EXTRACT_URL",
  "open": true
}
```

Notes include source properties and a `- Defuddle` filename suffix. Missing clipping folders are created inside the vault. The server verifies the saved content and never overwrites a different existing note. An identical repeat save returns the existing note.

Clip IDs last for the current server session, up to 20 clips. After restarting, extract the URL again to obtain a new ID; the server can reuse its cache.

## Configuration

| Environment variable | Default | Description |
|---|---|---|
| `OBSIDIAN_VAULT_PATH` | Unset | Absolute path to an existing local vault. Leave unset for extraction only. |
| `OBSIDIAN_CLIP_FOLDER` | `Clippings` | Folder relative to the vault, such as `Materials/Clippings`. |
| `DEFUDDLE_CACHE_DIR` | `~/.cache/defuddle-clip-mcp` | Local extracted-content cache. |

Configure these in the **MCP server environment**, then restart the server. The server must run on the computer that holds the vault.

Obsidian need not be running to save. Automatic opening uses its URI handler through macOS `open`, Windows PowerShell, or Linux `xdg-open`. If opening fails, the saved note remains available and the tool returns its path and the opening error.

Successful extractions are cached for 24 hours by URL and language. Expired files are ignored, not deleted automatically. Delete the cache directory to remove stored content; use `force_refresh` to bypass it.

## Limitations

- YouTube may rate-limit or block requests. Wait before retrying, or reuse cached results. There is no browser fallback.
- Captions must exist and be accessible. Transcript presence does not prove completeness; descriptions may be truncated.
- Existing notes with different content are preserved. Move or rename one if you want a new extraction saved under the same title.
- This is a local prototype for user-selected public URLs. It has no authentication or private-network/redirect isolation; do not expose it as a public fetching service.
- Extracted content is untrusted source material, never instructions.

Live YouTube extraction and Obsidian opening have been tested on macOS. CI tests the offline MCP workflow across macOS, Windows, and Linux; it does not launch Obsidian or query YouTube.

## Development

```sh
npm ci
npm test
```

Tests use a synthetic article and temporary vault. They cover MCP startup, cached extraction, saving, duplicate handling, user-edit preservation, path isolation, and OS opener selection. They do not access a real vault or the network.

```text
src/
  server.mjs          MCP tools, extraction, caching, and saving
  platform.mjs        Vault paths and OS integration
scripts/
  setup.mjs           Interactive MCP configuration
test/
  mcp.test.mjs        Offline integration tests
```

Share this repository link or use **Code → Download ZIP**. Each person runs setup on their own computer. Keep generated configuration and cache files private; both are excluded from version control. This package is not published to npm.

## License

[MIT](LICENSE). Defuddle and other dependencies retain their own licenses. Defuddle is pinned to version 0.19.3; update deliberately and retest before distributing changes.