<p align="center">
  <img src="plugins/obsidian-bridge/assets/logo.png" alt="Obsidian Bridge" width="180" />
</p>

# Obsidian Bridge

**Connect Cursor agents to your local Obsidian vault** — calmly, securely, and with production-grade tooling.

Obsidian Bridge is a **Cursor Plugin** that ships an MCP server for reading, writing, searching, patching, and organizing notes through the Obsidian **Local REST API**. Vault traffic stays on your machine; the API key never leaves Cursor Configure / your environment.

## Highlights

- Local-first MCP bridge (`127.0.0.1:27124` by default)
- Daily notes, search, tags, append/patch, open-in-Obsidian
- Setup + note-writing skills, vault-safety rules, hub-and-spoke graph guidance
- Typed TypeScript server, tests, and CI

## Install (Cursor Marketplace)

1. Install / enable **Local REST API** in Obsidian  
   (`obsidian://show-plugin?id=obsidian-local-rest-api`) and copy the API key.
2. Build once so the plugin ships the MCP binary:

```bash
npm install
npm run build
```

3. In Cursor, add this GitHub repo as a marketplace:  
   `https://github.com/dkdottk/obsidian-bridge`  
   (prefer GitHub over `file://` — Cursor’s sandbox blocks `git ls-remote` on the file protocol).
4. Install **Obsidian Bridge** → **Plugins → Configure** → paste the API key.
5. Ask Cursor: “Check Obsidian status.”

Defaults: `https://127.0.0.1:27124`.

### Marketplace layout

```text
.cursor-plugin/marketplace.json   ← required for Cursor marketplace import
plugins/obsidian-bridge/          ← the installable plugin
  .cursor-plugin/plugin.json
  mcp.json
  skills/ rules/ assets/ dist/
```

## What the agent can do

- Capture to daily notes
- Create, append, and patch notes
- Search the vault and browse tags
- Open notes in the Obsidian UI
- Run Obsidian commands when you explicitly ask
- Keep vault graphs readable (hub-and-spoke / MOC linking)

## Plugin components

| Piece | Role |
| --- | --- |
| MCP server | Vault tools over Local REST API |
| `obsidian-setup` skill | Three-step connect flow |
| `obsidian-notes` skill | Capture / organize habits |
| `obsidian-hub-spoke-graph` skill | Index/hub/leaf linking rules |
| Vault safety + hub-spoke rules | Always-on guardrails |

## Develop

```bash
npm install
npm run ci
```

Useful scripts:

- `npm run build` — compile to `dist/` and sync into the plugin
- `npm test` — Vitest suite
- `npm run typecheck` — max-strict TypeScript
- `npm run lint` — ESLint

See [docs/setup.md](docs/setup.md), [docs/architecture.md](docs/architecture.md), and [docs/tools.md](docs/tools.md).

## Security

Your API key stays in Cursor plugin variables / local environment. It is never committed and never logged. The bridge only calls a localhost endpoint you control. See [SECURITY.md](SECURITY.md).

## Author

[Danylo Kravchenko](https://github.com/dkdottk) · [dkdottk@gmail.com](mailto:dkdottk@gmail.com)

## License

[AGPL-3.0-only](LICENSE) — free to use, study, modify, and share.

If you distribute a modified version, or run a modified version as a network service, you must offer the corresponding source under AGPL-3.0. See the [LICENSE](LICENSE) for full terms.