From fc934b4917827b183a387f4f34720f2e8f79a6c5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 15 Nov 2025 17:11:28 +0000
Subject: [PATCH] docs: add troubleshooting guide for MCP SuperAssistant path
 issues (#38)

Added comprehensive troubleshooting documentation for users experiencing path resolution errors with MCP SuperAssistant and other MCP clients.

**New Troubleshooting Section:**
- Explains the ENOENT spawn error and its root cause
- Provides clear solution using absolute paths instead of relative/tilde paths
- Includes special guidance for iCloud Drive paths on macOS
- Step-by-step instructions to find vault's absolute path

**Key Information:**
- Some MCP clients (like MCP SuperAssistant) don't properly expand `~` or handle relative paths
- Solution is to use fully qualified absolute paths in the MCP client configuration
- Includes platform-specific examples for macOS, Linux, and Windows

This addresses the compatibility issue reported in #38 where MCP SuperAssistant couldn't spawn the server binary due to path resolution failures.

Fixes #38
---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index 38c71a8..91104b4 100644
--- a/README.md
+++ b/README.md
@@ -99,6 +99,36 @@ If you encounter issues:
    - **Connection errors**: Verify Local REST API plugin is configured
    - **Permission errors**: Try reinstalling the server
 
+### MCP SuperAssistant and Other MCP Clients
+
+If you're using MCP SuperAssistant or another MCP client and see errors like "ENOENT" or "spawn ... failed":
+
+**Problem**: Some MCP clients don't properly resolve relative paths or tilde (`~`) in the server binary path.
+
+**Solution**: Use an absolute path in your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-mcp-tools": {
+      "command": "/Users/YourUsername/Documents/YourVault/.obsidian/plugins/obsidian-mcp-tools/bin/mcp-server",
+      "env": {
+        "OBSIDIAN_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**For iCloud Drive paths on macOS**, expand the full path:
+- Bad: `~/Library/Mobile Documents/iCloud~md~obsidian/...`
+- Good: `/Users/YourUsername/Library/Mobile Documents/iCloud~md~obsidian/Documents/YourVault/.obsidian/plugins/obsidian-mcp-tools/bin/mcp-server`
+
+**To find your vault's absolute path**:
+1. Open Terminal (macOS/Linux) or Command Prompt (Windows)
+2. Navigate to your vault directory
+3. Run `pwd` (macOS/Linux) or `cd` (Windows) to see the full path
+
 ## Security
 
 ### Binary Distribution