# obsidian-vault-mcp

A stdio MCP server for managing feature documentation and bug tracking inside an Obsidian vault, organised by project.

## Setup

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

## Configuration

Set `VAULT_PATH` to the root of your Obsidian vault:

```bash
VAULT_PATH=/path/to/vault node dist/index.js
```

## omp Registration

Add to `~/.omp/agent/mcp.json`:

```json
"obsidian-vault": {
  "command": "node",
  "args": ["/absolute/path/to/obsidian-vault-mcp/dist/index.js"],
  "env": { "VAULT_PATH": "/path/to/your/obsidian/vault" }
}
```

## Tools

| Tool | Description |
|---|---|
| `list_projects` | List all projects in the vault |
| `write_feature_doc` | Write a feature doc under a project (optional `tags`, `links`) |
| `list_features` | List feature docs, optionally filtered by project and/or `tag` |
| `write_bug` | File a new bug under a project (optional `tags`, `blocked_by`, `ticket_type`) |
| `get_next_bug` | Get the highest-priority open bug |
| `get_note` | Read a bug or feature note's full frontmatter and content by path — bug vs. feature is auto-detected from the note's own `type` field |
| `update_note` | Update a bug or feature note in place by path (type auto-detected). `content` replaces the body (omit to leave it unchanged — this also covers a status-only update); `tags`/`links` apply to either kind; `status`/`blocked_by`/`ticket_type` are bug-only and rejected against a feature note |
| `list_bugs` | List bugs filtered by project, status, `tag`, and/or `unblocked` |

### Relational frontmatter fields

Bugs and feature docs both accept optional `tags: string[]` (grouping labels, e.g. `["wf:payments-v2-migration"]`) and `links: string[]` (absolute paths to related vault notes — e.g. pairing a resolved ticket with the note that recorded its answer).

Bugs additionally accept `blocked_by: string[]` (absolute paths to bug notes that must reach a terminal status — `resolved` or `out-of-scope` — before this one is workable) and `ticket_type: string` (descriptive only, e.g. `research`, `grilling`, `task`). `list_bugs` computes an `unblocked` field per bug and supports `unblocked: true` to filter to the frontier (open + not blocked). None of these fields are validated for existence — callers are trusted, matching `shortcut_card`/`shortcut_branch`.

A bug note's file path never changes across status transitions — `update_note` only rewrites frontmatter, never moves the file — so a `blocked_by` reference recorded while the blocker is open stays valid once it resolves. (Earlier versions relocated resolved/out-of-scope bugs into a `Bugs/Resolved/` subfolder; this broke `blocked_by` when the blocker moved out from under an existing reference. `list_bugs` still scans `Bugs/Resolved/` recursively for backward compatibility with any notes relocated before this fix, but no new relocations happen.)

## Vault Layout

```
<vault>/
  Projects/
    <ProjectName>/
      Features/<slug>.md
      Bugs/<slug>.md
```