┌─────────────────────────────────────────────────────────┐
│                 Obsidian Vault (iCloud)                  │
│  ├── Notes/*.md                                         │
│  ├── .obsidian-search/semantic-search.db  ← vectors     │
│  └── .obsidian/plugins/obsidian-semantic-search/         │
└─────────────────────────────────────────────────────────┘
          ▲ reads / writes          ▲ plugin installed here
          │                         │
┌─────────┴─────────────────────────┴───────────────────┐
│             Python Backend  (local process)             │
│  FastAPI  :51234  ◄─── Obsidian plugin (HTTP)          │
│  FastMCP  stdio   ◄─── Claude Desktop / LLMs           │
│                                                        │
│  nomic-embed-text-v1.5  (sentence-transformers + MPS)  │
│  CrossEncoder reranker  (ms-marco-MiniLM-L-6-v2)       │
└────────────────────────────────────────────────────────┘

obsidian-mcp/
├── packages/
│   ├── backend/                  # Python — FastAPI + FastMCP server
│   │   └── src/obsidian_search/
│   │       ├── config.py         # pydantic-settings (VAULT_PATH, port, …)
│   │       ├── models.py         # Chunk, SearchResult, IndexStatus, …
│   │       ├── ingestion/        # chunker_markdown, chunker_pdf, chunker_web
│   │       ├── embedding/        # nomic-embed-text-v1.5 singleton
│   │       ├── store/            # sqlite-vec CRUD + ANN search
│   │       ├── search/           # searcher + CrossEncoder reranker
│   │       ├── watcher/          # watchdog FSEventsObserver
│   │       ├── api/              # FastAPI routes (/search, /ingest/*, /status)
│   │       └── mcp/              # FastMCP tools for Claude
│   └── obsidian-plugin/          # TypeScript — Obsidian plugin
│       └── src/
│           ├── main.ts           # Plugin entry, commands, file save hook
│           ├── settings.ts       # Settings tab (server URL, top-k, …)
│           ├── api-client.ts     # Typed fetch() wrapper
│           ├── search-modal.ts   # SuggestModal with debounced search
│           └── types.ts          # Shared interfaces
├── docs/
│   ├── userflows.md              # Mermaid diagrams for all user flows
│   └── branch-protection.md     # GitHub branch protection setup guide
├── .github/workflows/ci.yml      # Lint + typecheck + tests gate
└── PLAN.md                       # Architecture decisions and implementation plan

git clone https://github.com/unnitin/obsidian-mcp.git
cd obsidian-mcp
uv sync --all-extras

cp .env.example .env
# Edit .env and set VAULT_PATH to the absolute path of your Obsidian vault

ls "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/"

VAULT_PATH=/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName

./scripts/start-backend.sh

./scripts/build-plugin.sh

ls "$HOME/Library/Mobile Documents/iCloud~md~obsidian/Documents/"

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName

sudo pmset -c sleep 0 disksleep 0

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.obsidian-search.backend</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/yourname/.local/bin/uv</string>
    <string>run</string>
    <string>--project</string>
    <string>/Users/yourname/obsidian-mcp/packages/backend</string>
    <string>obsidian-search-api</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
    <key>VAULT_PATH</key>
    <string>/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVaultName</string>
    <key>HOME</key>
    <string>/Users/yourname</string>
    <key>OBSIDIAN_SEARCH_HOST</key>
    <string>0.0.0.0</string>
  </dict>

  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>

  <key>StandardOutPath</key>
  <string>/tmp/obsidian-search.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/obsidian-search.err</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.obsidian-search.backend.plist

launchctl list | grep obsidian-search
curl http://localhost:51234/health
tail -f /tmp/obsidian-search.log

# Find the Mac mini's IP
# On the Mac mini:
ipconfig getifaddr en0

# On your other Mac, set the plugin server URL to:
# http://192.168.x.x:51234

{
  "mcpServers": {
    "obsidian-search": {
      "command": "uv",
      "args": [
        "run",
        "--project", "/path/to/obsidian-mcp/packages/backend",
        "python", "-m", "obsidian_search.mcp.server"
      ],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

"What did I write about the CAP theorem?"
"Summarise my notes on async Rust"
"Index this article for me: https://..."
"How many documents are in my vault index?"

uv run pytest packages/backend/tests/ -v

uv run pytest packages/backend/tests/ --cov=packages/backend/src --cov-report=term-missing

uv run ruff check packages/backend/
uv run ruff format packages/backend/

uv run mypy packages/backend/src/