Merge pull request dvcrn#6 from deadmanoz/feature/improve-readme-documentation

Author: dvcrn

.claude/settings.local.json

@@ -1,2 +1,6 @@
 node_modules
 dist
+
+.roo/
+
+.claude/

.gitignore

@@ -1,4 +1,4 @@
-# Devonthink MCP Server
+# DEVONthink MCP Server
 
 This MCP server provides access to DEVONthink functionality via the Model Context Protocol (MCP). It enables listing, searching, creating, modifying, and managing records and databases in DEVONthink Pro on macOS.
 
@@ -120,7 +120,34 @@ 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
+
+### 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 +162,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

.roo/mcp.json

@@ -1,4 +1,4 @@
-# MicroFn MCP Server - Just Commands
+# DEVONthink MCP Server - Just Commands
 
 # Default recipe to show available commands
 default:

README.md

@@ -88,7 +88,7 @@ const getOpenDatabases = async (): Promise<GetOpenDatabasesResult> => {
 export const getOpenDatabasesTool: Tool = {
   name: "get_open_databases",
   description:
-    "Get a list of all currently open databases in DEVONthink. This tool is useful for discovering available databases and their properties, such as name, path, and encryption status. The returned database names can be used in other tools.\n\nIMPORTANT - Database UUIDs for Claude Codet Operations:\nThe UUID field in the results is ESSENTIAL for database root operations:\n- Use the database UUID as parentGroupUuid in create_record to create at database root\n- Use the database UUID as destinationGroupUuid in move_record to move to database root\n- Use the database UUID as parentGroupUuid in create_from_url to create at database root\n\nExample: Database UUID '5E47D6F2-5E0C-4E30-A6ED-2AC92116C3E1' represents the true root level of that database.",
+    "Get a list of all currently open databases in DEVONthink. This tool is useful for discovering available databases and their properties, such as name, path, and encryption status. The returned database names can be used in other tools.\n\nIMPORTANT - Database UUIDs for Claude Code Operations:\nThe UUID field in the results is ESSENTIAL for database root operations:\n- Use the database UUID as parentGroupUuid in create_record to create at database root\n- Use the database UUID as destinationGroupUuid in move_record to move to database root\n- Use the database UUID as parentGroupUuid in create_from_url to create at database root\n\nExample: Database UUID '5E47D6F2-5E0C-4E30-A6ED-2AC92116C3E1' represents the true root level of that database.",
   inputSchema: zodToJsonSchema(GetOpenDatabasesSchema) as ToolInput,
   run: getOpenDatabases,
 };