setup

Vault PKM Setup

You are configuring the Vault PKM plugin. Walk the user through these steps:

Step 1: Vault Path

Ask the user for their Obsidian vault path. Validate that:

• The path exists and is a directory
• It contains at least one .md file
• Suggest ~/Documents/PKM as a default

If the path is valid, add it to ~/.claude/settings.json under the env block:

{
  "env": {
    "VAULT_PATH": "/absolute/path/to/vault"
  }
}

Read the file first, merge with existing env vars (don't overwrite other settings), and write back. Verify the MCP server can connect after setting it.

Step 2: OpenAI API Key (Optional)

Ask if they want semantic search features (vault_semantic_search, vault_suggest_links). If yes:

• NEVER ask the user to type their API key in the chat — it would be stored in conversation history
• Tell them to open ~/.claude/settings.json in their text editor (outside of Claude Code) and add VAULT_PKM_OPENAI_KEY to the env block:

  {
    "env": {
      "VAULT_PATH": "/path/to/vault",
      "VAULT_PKM_OPENAI_KEY": "sk-your-key-here"
    }
  }
  

• Explain the variable is named VAULT_PKM_OPENAI_KEY (not OPENAI_API_KEY) to avoid conflicts with project-scoped OpenAI keys. Users upgrading from earlier releases can keep OBSIDIAN_PKM_OPENAI_KEY — it still works as a deprecated fallback — but should rename it at their convenience.
• Explain they can get a key from https://platform.openai.com/api-keys
• Explain this enables 2 additional tools (semantic search + link suggestions) but is completely optional
• Tell them to restart Claude Code after saving the file

Step 3: Tool Permissions

Ask the user if they want to auto-approve all PKM vault tools (so they don't get prompted for each tool call). If yes, add this to the permissions.allow array in ~/.claude/settings.json:

mcp__plugin_vault-pkm_vault-pkm__*

Read the file first, merge with existing permissions (don't overwrite), and write back. This allows all vault_read, vault_write, vault_search, etc. tools to run without per-call confirmation.