docs: comprehensive README improvements for better getting started experience

- Add complete prerequisites section (macOS, DEVONthink Pro, Node.js, Claude)
- Add three installation options (npm global, npx, local development)
- Add Claude Desktop configuration section with file location and all config options
- Add comprehensive Claude Code section with CLI setup and scope configuration
- Add detailed troubleshooting including real-world issues (tsc not found, restart requirements)
- Fix dependency installation documentation to prevent TypeScript build errors
- Improve verification and testing instructions for both Claude Desktop and Code

Author: deadmanoz

README.md

@@ -120,7 +120,35 @@ Returns:
 }
 ```
 
-## Usage with Claude
+## Getting Started
+
+### Prerequisites
+
+1. **DEVONthink Pro** - The DEVONthink application must be installed and running
+2. **Node.js** (v18 or later) - Required to run the MCP server
+3. **Claude Desktop or Claude Code** - To use the MCP server
+
+### Installation
+
+#### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g mcp-server-devonthink
+```
+
+Then add to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "devonthink": {
+      "command": "mcp-server-devonthink"
+    }
+  }
+}
+```
+
+#### Option 2: Use via npx
 
 Add to your Claude configuration:
 
@@ -135,6 +163,187 @@ Add to your Claude configuration:
 }
 ```
 
+#### Option 3: Local Development Setup
+
+If you want to modify or contribute to this project:
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/dvcrn/mcp-server-devonthink.git
+   cd mcp-server-devonthink
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+   *Note: The project specifies Yarn as the package manager, but npm works fine for installation.*
+
+   **Important**: You must run `npm install` before building, as it installs TypeScript (`tsc`) and other build tools.
+
+3. **Build the project:**
+   ```bash
+   npm run build
+   # or use the justfile if you have just installed
+   just build
+   ```
+
+4. **Test the server:**
+   ```bash
+   node dist/index.js
+   ```
+
+   The server should start without errors. Press Ctrl+C to stop.
+
+5. **Add to Claude configuration:**
+   ```json
+   {
+     "mcpServers": {
+       "devonthink": {
+         "command": "node",
+         "args": ["/path/to/mcp-server-devonthink/dist/index.js"]
+       }
+     }
+   }
+   ```
+
+### Claude Configuration
+
+Your Claude Desktop configuration file is located at:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Create or update this file with the MCP server configuration. Choose the configuration that matches your installation method:
+
+**Option 1: Global npm installation**
+```json
+{
+  "mcpServers": {
+    "devonthink": {
+      "command": "mcp-server-devonthink"
+    }
+  }
+}
+```
+
+**Option 2: Using npx**
+```json
+{
+  "mcpServers": {
+    "devonthink": {
+      "command": "npx",
+      "args": ["-y", "mcp-server-devonthink"]
+    }
+  }
+}
+```
+
+**Option 3: Local development setup**
+```json
+{
+  "mcpServers": {
+    "devonthink": {
+      "command": "node",
+      "args": ["/path/to/mcp-server-devonthink/dist/index.js"]
+    }
+  }
+}
+```
+*Replace `/path/to/mcp-server-devonthink` with your actual project directory path.*
+
+## Usage with Claude Desktop
+
+1. **Start DEVONthink** - Ensure DEVONthink Pro is running
+2. **Restart Claude Desktop** - After updating the configuration
+3. **Test the connection** - In Claude, try asking: "Is DEVONthink running?"
+
+If everything is set up correctly, Claude should be able to use the `is_running` tool and confirm that DEVONthink is active.
+
+## Usage with Claude Code
+
+Claude Code users can install this MCP server using the command-line interface. Based on testing experience, here's the complete setup process:
+
+### Prerequisites
+
+- Ensure Claude Code CLI is installed and working (`claude --version`)
+- DEVONthink Pro must be running
+
+### Installation
+
+Choose the installation method that matches your setup:
+
+**Option 1: Global npm installation**
+```bash
+npm install -g mcp-server-devonthink
+claude mcp add devonthink -- mcp-server-devonthink
+```
+
+**Option 2: Using npx (no installation required)**
+```bash
+claude mcp add devonthink -- npx -y mcp-server-devonthink
+```
+
+**Option 3: Local development setup**
+```bash
+# After cloning and building the project locally
+claude mcp add devonthink -- node /path/to/mcp-server-devonthink/dist/index.js
+```
+
+### Scope Configuration
+
+By default, MCP servers are added with **local scope** (only available in the current project directory). For global availability:
+
+```bash
+claude mcp add devonthink --scope user -- node /path/to/mcp-server-devonthink/dist/index.js
+```
+
+### Verification & Testing
+
+1. **Check server status:**
+   ```bash
+   claude mcp list
+   ```
+   You should see: `devonthink: ✓ Connected`
+
+2. **Test in Claude Code:**
+   - Use `/mcp` command to verify server connection
+   - Try asking: "Is DEVONthink running?"
+   - Test with: "List my open databases"
+
+### Management Commands
+
+- **List servers:** `claude mcp list`
+- **Get server details:** `claude mcp get devonthink`
+- **Remove server:** `claude mcp remove devonthink`
+
+### Important Notes
+
+- **Restart Required**: If `/mcp` shows "No MCP servers configured" after adding the server, you may need to completely quit and restart Claude Code
+- **Scope Matters**: Local scope servers only work in the directory where they were configured
+- **User Scope**: Use `--scope user` to make the server available in all your projects
+
+### Troubleshooting
+
+#### Build Errors
+- **"tsc: command not found"** - Run `npm install` to install TypeScript and other dependencies
+- **Permission errors** - The build process makes the dist/index.js file executable automatically
+
+#### Claude Desktop Connection Issues
+- **Server not found** - Verify the path in your Claude Desktop configuration
+- **DEVONthink not responding** - Ensure DEVONthink Pro (not DEVONthink Personal) is installed and running
+- **Permission errors** - macOS may require granting accessibility permissions to Claude Desktop
+
+#### Claude Code Connection Issues
+- **"/mcp shows no servers"** - Try completely quitting and restarting Claude Code
+- **"Server not connected"** - Run `claude mcp list` to verify CLI shows server as connected
+- **Local vs User scope** - If server only works in specific directories, reconfigure with `--scope user`
+- **CLI vs IDE mismatch** - The CLI and running Claude Code process may use different configurations
+
+#### Optional Tools
+
+- **just** - Task runner for convenient build commands (install with `brew install just`)
+- **Yarn** - Alternative package manager (the project was originally developed with Yarn)
+
 ## Implementation Details
 
 - Uses JXA (JavaScript for Automation) to control DEVONthink via AppleScript APIs