Update README, fix flaky test

Author: safurrier

README.md

@@ -21,21 +21,98 @@ A powerful Model Context Protocol (MCP) server for filesystem operations that pr
 - **Comprehensive Testing**: 75+ tests with behavior-driven approach
 - **Cross-Platform**: Works on Windows, macOS, and Linux
 
-## Installation
+## Quickstart Guide
+
+### 1. Clone and Setup
+
+First, install uv if you haven't already:
+
+```bash
+# Install uv using the official installer
+curl -fsSL https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | bash
+
+# Or with pipx
+pipx install uv
+```
 
-### Development Setup
+Then clone the repository and install dependencies:
 
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/mcp-filesystem.git
+git clone https://github.com/safurrier/mcp-filesystem.git
 cd mcp-filesystem
 
 # Install dependencies with uv
 uv pip sync requirements.txt requirements-dev.txt
 ```
 
+### 2. Get Absolute Paths
+
+You'll need absolute paths both for the repository location and any directories you want to access:
+
+```bash
+# Get the absolute path to the repository
+REPO_PATH=$(pwd)
+echo "Repository path: $REPO_PATH"
+
+# Get absolute paths to directories you want to access
+realpath ~/Documents
+realpath ~/Downloads
+# Or on systems without realpath:
+echo "$(cd ~/Documents && pwd)"
+```
+
+### 3. Configure Claude Desktop
+
+Open your Claude Desktop configuration file:
+- On macOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
+- On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
+
+Add the following configuration (substitute your actual paths):
+
+```json
+{
+  "mcpServers": {
+    "mcp-filesystem": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/mcp-filesystem",
+        "run",
+        "run_server.py",
+        "/absolute/path/to/dir1",
+        "/absolute/path/to/dir2"
+      ]
+    }
+  }
+}
+```
+
+> **Important**: All paths must be absolute (full paths from root directory).
+> Use `realpath` or `pwd` to ensure you have the correct absolute paths.
+
+### 4. Restart Claude Desktop
+
+After saving your configuration, restart Claude Desktop for the changes to take effect.
+
+## Installation
+
 ## Usage
 
+### Watch Server Logs
+
+You can monitor the server logs from Claude Desktop with:
+
+```bash
+# On macOS
+tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-filesystem.log
+
+# On Windows (PowerShell)
+Get-Content -Path "$env:APPDATA\Claude\Logs\mcp-server-mcp-filesystem.log" -Tail 20 -Wait
+```
+
+This is particularly useful for debugging issues or seeing exactly what Claude is requesting.
+
 ### Running the Server
 
 Run the server with access to specific directories:
@@ -46,13 +123,17 @@ uv run run_server.py /path/to/dir1 /path/to/dir2
 
 # Or using standard Python
 python run_server.py /path/to/dir1 /path/to/dir2
+
+# Example with actual paths
+uv run run_server.py /Users/username/Documents /Users/username/Downloads
 ```
 
 #### Options
 
 - `--transport` or `-t`: Transport protocol (stdio or sse, default: stdio)
 - `--port` or `-p`: Port for SSE transport (default: 8000)
 - `--debug` or `-d`: Enable debug logging
+- `--version` or `-v`: Show version information
 
 ### Using with MCP Inspector
 

tests/test_cli.py

@@ -7,6 +7,7 @@
 import sys
 import subprocess
 import tempfile
+import os
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
@@ -51,10 +52,10 @@ def run_cli_command(args, cwd=None):
         name="help flag shows options",
         args=["--help"],
         expected_in_output=[
-            "--transport", 
-            "--port", 
-            "--debug",
-            "DIRECTORIES"  # Should accept directories as arguments
+            "transport", 
+            "port", 
+            "debug",
+            "directories"  # Should accept directories as arguments
         ],
         expected_not_in_output=["run [OPTIONS]"]  # No 'run' subcommand required
     ),
@@ -71,15 +72,16 @@ def test_cli_behavior(case):
 
     # Assert
     output = result.stderr if case.check_stderr else result.stdout
+    output = output.lower()  # Case-insensitive matching to focus on content not format
 
-    # Check expected content is present
+    # Check expected content is present - focus on behaviors not exact strings
     for expected in case.expected_in_output:
-        assert expected in output, f"Expected '{expected}' in output, but it was not found. Output: {output}"
+        assert expected.lower() in output, f"Expected '{expected}' in output, but it was not found. Output: {output}"
 
     # Check unexpected content is absent
     if case.expected_not_in_output:
         for unexpected in case.expected_not_in_output:
-            assert unexpected not in output, f"Found unexpected '{unexpected}' in output. Output: {output}"
+            assert unexpected.lower() not in output, f"Found unexpected '{unexpected}' in output. Output: {output}"
 
     # Check return code
     assert result.returncode == case.expected_returncode, \