From de7f2b02f685281766ed0b57b24e42d5b1da960f Mon Sep 17 00:00:00 2001 From: "david.delagneau" Date: Mon, 27 Apr 2026 09:54:27 -0600 Subject: [PATCH] feat: integrate Obsidian MCP server via opencode config and add migration strategy documentation --- agent-memory/maps/tooling.md | 3 +- .../workflows/obsidian-mcp-migration.md | 274 ++++++++++++++++++ opencode.json | 13 + 3 files changed, 289 insertions(+), 1 deletion(-) create mode 100644 agent-memory/workflows/obsidian-mcp-migration.md diff --git a/agent-memory/maps/tooling.md b/agent-memory/maps/tooling.md index 95990f1..75951e9 100644 --- a/agent-memory/maps/tooling.md +++ b/agent-memory/maps/tooling.md @@ -1,7 +1,7 @@ --- type: agent-map domain: tooling -updated: 2026-04-17 +updated: 2026-04-27 tags: - map - tooling @@ -61,5 +61,6 @@ Commands, prompts, skills, workflows, and automation surfaces that make the work - Project-agnostic memory scripts: `scripts/memory/` - Current Obsidian adapter: `scripts/obsidian/` +- Obsidian MCP migration plan: `agent-memory/workflows/obsidian-mcp-migration.md` - Project knowledge vault: `project-knowledge/` - Agent operating memory: `agent-memory/` diff --git a/agent-memory/workflows/obsidian-mcp-migration.md b/agent-memory/workflows/obsidian-mcp-migration.md new file mode 100644 index 0000000..b25b4a6 --- /dev/null +++ b/agent-memory/workflows/obsidian-mcp-migration.md @@ -0,0 +1,274 @@ +--- +type: agent-workflow +status: in-progress +updated: 2026-04-27 +tags: [obsidian, mcp, migration, memory] +--- + +# Obsidian MCP Migration Plan + +## Goal + +Replace the current Obsidian CLI-backed adapter path with an Obsidian MCP-first integration while preserving the workspace memory model: + +- `project-knowledge/` remains the canonical source of truth +- `scripts/memory/` remains the stable workspace memory contract +- direct Markdown edits remain the safe fallback for precise curation +- Obsidian stays an adapter/navigation layer, not a second memory store + +--- + +## Current State + +Current access path: + +```text +agent -> scripts/memory/memory.sh -> scripts/obsidian/cli.sh -> obsidian CLI -> vault +``` + +Current Obsidian-specific helper scripts: + +- `scripts/obsidian/cli.sh` +- `scripts/obsidian/open.sh` +- `scripts/obsidian/search.sh` +- `scripts/obsidian/daily.sh` +- `scripts/obsidian/uri.sh` + +Current memory-interface features that rely on Obsidian CLI when available: + +- note creation from templates +- search with context +- Base queries +- selected health/navigation checks + +Phase 1 integration status as of 2026-04-27: + +- OpenCode project config now declares a local MCP server named `obsidian`. +- The configured command is `/opt/homebrew/bin/uvx mcp-obsidian`. +- The Obsidian Local REST API endpoint is reachable at `https://127.0.0.1:27124/` and reports plugin version `3.6.1` with Obsidian `1.12.7`. +- The server currently depends on the caller providing `OBSIDIAN_API_KEY` through the shell environment; do not commit this secret. + +--- + +## Target State + +Preferred access path: + +```text +agent -> memory interface rules -> Obsidian MCP -> vault +``` + +The migration should change the adapter, not the memory model. + +--- + +## Non-Goals + +- Do not move canonical memory out of Markdown +- Do not encode promotion rules into the MCP layer +- Do not make `project-knowledge/` depend on Obsidian-only storage +- Do not remove direct Markdown editing as a fallback +- Do not delete the current scripts until MCP coverage is validated in real use + +--- + +## Capability Mapping + +### Move to Obsidian MCP + +- vault search +- search with context +- Base queries +- backlinks / links / orphans / unresolved checks +- property read/write operations +- template-based note creation if supported cleanly by the MCP + +### Keep as workspace logic + +- note type routing (`work-item`, `person`, `decision`, etc.) +- memory promotion rules +- evidence vs canonical-memory separation +- workspace-specific health expectations +- fallback to direct Markdown operations +- metadata expectations for work items, daily notes, people, decisions, and context notes + +--- + +## Phased Rollout + +## Phase 1 - Validate MCP Coverage + +Confirm the selected Obsidian MCP supports the operations the workspace already depends on. + +Required coverage: + +- read file contents +- create note from path and optionally template +- search vault +- query Bases or equivalent structured views +- read and write frontmatter/properties +- list backlinks/links or equivalent relationship data + +Current Phase 1 checklist: + +- [x] Confirm Obsidian Local REST API plugin is reachable locally. +- [x] Install `uv` / `uvx` runtime for `mcp-obsidian`. +- [x] Add OpenCode MCP config using `OBSIDIAN_API_KEY` environment substitution. +- [x] Export `OBSIDIAN_API_KEY` in the shell that launches OpenCode. +- [x] Restart OpenCode and confirm `opencode mcp list` shows `obsidian` connected. +- [x] Validate read/search tools against `project-knowledge/` notes. +- [x] Validate write/append/delete behavior on a disposable test note before touching canonical memory. +- [ ] Determine whether Bases/properties/backlinks/template behavior needs to remain on the existing CLI/direct-Markdown path. + +Phase 1 validation results: + +- `list_files_in_vault` works and returns the expected top-level project-knowledge folders. +- `list_files_in_dir` works for folders such as `01-current`. +- `get_file_contents` works for canonical notes such as `01-current/current-work.md`. +- `simple_search` works and returns scored/contextual matches across the vault. +- `append_content` can create and append to a disposable note. +- `delete_file` can delete a disposable note. +- `patch_content` with `target_type=heading` failed against a disposable note with `invalid-target`; treat heading-targeted patching as not yet validated. + +Decision rule: + +- If MCP cannot cover create/search/properties/Base-query well enough, keep the current CLI path as a partial adapter instead of forcing a full replacement. + +--- + +## Phase 2 - Switch Documentation To MCP-First + +Update behavior and architecture docs so they describe: + +- Obsidian MCP as the preferred adapter when available +- `scripts/memory/` as the stable workspace contract +- direct Markdown editing as the safe fallback +- the CLI path as legacy or transitional + +Primary files to update: + +- `AGENTS.md` +- `.opencode/agents/fidelity.md` +- `.opencode/agents/workspace.md` +- `README.md` +- `profiles/fidelity/profile.md` +- `core/README.md` +- `core/integrations/memory-vault-model.md` +- `core/integrations/obsidian-model.md` +- `agent-memory/integrations/memory-interface.md` +- `agent-memory/integrations/obsidian.md` +- `agent-memory/memory/context-maintenance.md` +- `agent-memory/workflows/workspace-architecture.md` +- `scripts/memory/README.md` +- `.opencode/commands/memory-create.md` +- `.opencode/commands/memory-health.md` + +--- + +## Phase 3 - Deprecate Obsidian CLI Helpers + +Mark these as deprecated in comments/docs before removal: + +- `scripts/obsidian/cli.sh` +- `scripts/obsidian/open.sh` +- `scripts/obsidian/search.sh` +- `scripts/obsidian/daily.sh` +- `scripts/obsidian/uri.sh` + +Notes: + +- human convenience wrappers may be kept longer than agent-facing wrappers +- `scripts/memory/` should not be deleted just because the adapter changes + +--- + +## Phase 4 - Remove Unused Adapter Scripts + +Delete only after: + +- MCP has been used successfully in normal workflows +- no agent instructions still reference the old scripts +- command docs no longer direct users to the old CLI path +- there is no remaining human workflow dependency worth preserving + +Likely delete first: + +- `scripts/obsidian/cli.sh` +- `scripts/obsidian/uri.sh` + +Delete later only if truly unused: + +- `scripts/obsidian/open.sh` +- `scripts/obsidian/search.sh` +- `scripts/obsidian/daily.sh` + +--- + +## Cleanup Matrix + +### Keep + +- `project-knowledge/.obsidian/` +- `project-knowledge/08-bases/*.base` +- `project-knowledge/09-templates/` +- `scripts/memory/` + +### Deprecate then remove + +- `scripts/obsidian/*` agent-facing wrappers that become redundant under MCP + +### Update in place + +- commands that call `bash scripts/memory/memory.sh ...` +- docs that explicitly say "Obsidian CLI" is the preferred adapter +- rules that recommend CLI property edits + +--- + +## Risks + +- over-coupling the workspace to a specific MCP implementation +- deleting the stable memory contract too early +- partial migration that leaves conflicting instructions in docs +- assuming MCP supports templates/Bases/properties exactly like the CLI + +--- + +## Rollback Strategy + +If MCP integration is incomplete or unstable: + +- keep `scripts/memory/` as the default contract +- keep CLI helpers until capability parity exists +- continue direct Markdown edits for precise curation +- treat MCP as additive until it proves reliable in real workflows + +--- + +## Immediate Next Steps + +1. Choose the exact Obsidian MCP implementation and document its supported operations. +2. Build a capability parity checklist against the current CLI-backed flow. +3. Update the workspace docs to MCP-first wording without deleting the CLI path yet. +4. Add deprecation notes to `scripts/obsidian/*` once the new path is active. +5. Remove old scripts only after references and real usage are gone. + +--- + +## Initial Candidate + +- `MarkusPfundstein/mcp-obsidian` + - GitHub: `https://github.com/MarkusPfundstein/mcp-obsidian` + - Integration model: MCP server that talks to Obsidian through the Obsidian Local REST API community plugin. + - Documented tools include file listing, file reads, search, content patching, append, and delete. + - Requires validating whether it covers this workspace's Base-query, property/frontmatter, backlinks, and template workflows well enough to replace the current CLI adapter. + +## Candidate Rejected Or Not Recommended + +- `jacksteamdev/obsidian-mcp-tools` + - GitHub: `https://github.com/jacksteamdev/obsidian-mcp-tools` + - Features documented by the project include vault access, semantic search, and template integration. + - Dependencies include Obsidian Local REST API, and optional/recommended plugins such as Templater and Smart Connections. + - The repository currently carries a prominent "Project Unmaintained" security notice from the maintainer. + - The maintainer specifically recommends migrating to a plugin that implements MCP over HTTP/SSE rather than relying on a downloaded local executable model. + - Do not use this as the primary migration target for this workspace unless no safer maintained option is available and the risk is explicitly accepted. diff --git a/opencode.json b/opencode.json index e124b55..c002310 100644 --- a/opencode.json +++ b/opencode.json @@ -2,6 +2,19 @@ "$schema": "https://opencode.ai/config.json", "default_agent": "fidelity", "share": "manual", + "mcp": { + "obsidian": { + "type": "local", + "command": ["/opt/homebrew/bin/uvx", "mcp-obsidian"], + "enabled": true, + "timeout": 15000, + "environment": { + "OBSIDIAN_API_KEY": "{env:OBSIDIAN_API_KEY}", + "OBSIDIAN_HOST": "127.0.0.1", + "OBSIDIAN_PORT": "27124" + } + } + }, "permission": { "*": "ask", "read": {