Cut-Copy-Paste Clipboard Server

# Path Access Control The MCP Cut-Copy-Paste Clipboard Server includes a filesystem sandboxing feature that allows you to restrict which paths the server can access. This mitigates security risks when running the server with remote AI agents. ## Overview By default, the server allows access to **all** filesystem paths that the user running the server has permissions to access. You can restrict this by creating an allowlist file that specifies which paths are allowed. ## Configuration ### Allowlist File Location The allowlist file is located at: ``` ~/.mcp-clipboard/paths.allow ``` ### Default Behavior - If the file does not exist, **all paths are allowed** (wildcard `*`) - If the file exists but is empty, **all paths are allowed** - If the file exists with patterns, only matching paths are allowed ## Pattern Syntax The `paths.allow` file uses `.gitignore`-style glob patterns: ### Basic Patterns ``` # Allow a specific directory and all subdirectories /home/user/my-project/** # Allow multiple projects /home/user/project1/** /home/user/project2/** # Allow files matching a pattern anywhere **/*.ts **/*.js ``` ### Absolute vs Relative Patterns - **Absolute patterns** start with `/` and match from the filesystem root: ``` /home/user/projects/** ``` - **Relative patterns** are automatically converted to match anywhere in the filesystem: ``` *.ts → **/*.ts src/**/*.js → **/src/**/*.js ``` ### Negation Patterns Use `!` prefix to exclude paths that were previously allowed: ``` # Allow project directory /home/user/project/** # But exclude specific subdirectories !**/node_modules/** !**/.git/** !**/dist/** !**/build/** ``` ### Comments and Empty Lines ``` # This is a comment # Comments start with # /home/user/project/** # Inline comments not supported # Empty lines are ignored ``` ## Pattern Evaluation Patterns are evaluated **top-to-bottom**, with later patterns overriding earlier ones: ``` # First allow entire project /home/user/project/** # Then deny node_modules !**/node_modules/** # Then re-allow a specific node_modules directory /home/user/project/node_modules/special/** ``` In this example: - `/home/user/project/src/index.ts` → ✅ Allowed (matches first rule) - `/home/user/project/node_modules/lib.js` → ❌ Denied (matches negation rule) - `/home/user/project/node_modules/special/file.js` → ✅ Allowed (matches final rule) ## Common Use Cases ### Workspace-Only Access Restrict the server to only access your current project: ``` # paths.allow /home/user/my-current-project/** ``` ### Multiple Projects Allow access to several specific projects: ``` # paths.allow /home/user/project1/** /home/user/project2/** /home/user/project3/** ``` ### Project with Exclusions Allow a project but exclude build artifacts and dependencies: ``` # paths.allow /home/user/project/** !**/node_modules/** !**/.git/** !**/dist/** !**/build/** !**/coverage/** !**/.DS_Store ``` ### Source Files Only Only allow access to source code files: ``` # paths.allow /home/user/projects/**/*.ts /home/user/projects/**/*.js /home/user/projects/**/*.py /home/user/projects/**/*.java # Exclude test files !**/*.test.ts !**/*.spec.js ``` ### Development vs Production For local development, allow broad access: ``` # paths.allow (development) * ``` For production or when working with untrusted agents, restrict access: ``` # paths.allow (production) /var/app/src/** !**/secrets/** !**/.env ``` ## Security Best Practices ### 1. **Principle of Least Privilege** Only allow access to directories that the AI agent actually needs: ``` # Good: Specific project directory /home/user/current-work/** # Bad: Entire home directory /home/user/** ``` ### 2. **Always Exclude Sensitive Directories** Even when allowing broad access, explicitly deny sensitive paths: ``` /home/user/projects/** !**/.ssh/** !**/.aws/** !**/.env !**/secrets/** !**/credentials/** ``` ### 3. **Review Patterns Regularly** Periodically review your `paths.allow` file to ensure it still matches your needs: ```bash cat ~/.mcp-clipboard/paths.allow ``` ### 4. **Test Your Configuration** After updating `paths.allow`, test that it works as expected: ```bash # Try to access an allowed file mcp-clipboard copy_lines --file /allowed/path/file.txt --start 1 --end 10 # Try to access a denied file (should fail) mcp-clipboard copy_lines --file /blocked/path/file.txt --start 1 --end 10 ``` ### 5. **Use Absolute Paths** For maximum security, use absolute paths in your allowlist: ``` # Good: Absolute path /home/user/project/** # Acceptable but less specific: Relative pattern project/** ``` ## Error Messages When access is denied, you'll see an error like: ``` Error: Copy failed: Access denied: path not in allowlist: /path/to/blocked/file.txt ``` This indicates that the file path doesn't match any allowed patterns in your `paths.allow` file. ## Reloading Configuration Currently, the server reads the `paths.allow` file on startup. To reload after making changes: 1. Restart the MCP server 2. The new patterns will be applied immediately ## Implementation Details - **Pattern matching** uses the `minimatch` library for robust glob support - **Path resolution** converts all paths to absolute before matching - **Defense in depth** validates paths at both the `FileHandler` and `ClipboardTools` layers - **Default safe** If file read fails, defaults to allow-all (with console warning) ## Examples ### Example 1: Single Project ``` # ~/.mcp-clipboard/paths.allow /Users/alice/coding/my-app/** ``` Result: - ✅ `/Users/alice/coding/my-app/src/index.ts` - ✅ `/Users/alice/coding/my-app/README.md` - ❌ `/Users/alice/coding/other-app/file.ts` - ❌ `/etc/passwd` ### Example 2: Multiple Projects with Exclusions ``` # ~/.mcp-clipboard/paths.allow /Users/alice/coding/** !**/node_modules/** !**/.git/** !**/dist/** ``` Result: - ✅ `/Users/alice/coding/app1/src/index.ts` - ✅ `/Users/alice/coding/app2/main.py` - ❌ `/Users/alice/coding/app1/node_modules/lib.js` - ❌ `/Users/alice/coding/app1/.git/config` ### Example 3: TypeScript/JavaScript Only ``` # ~/.mcp-clipboard/paths.allow **/*.ts **/*.tsx **/*.js **/*.jsx !**/*.test.ts !**/*.spec.js !**/node_modules/** ``` Result: - ✅ `/any/path/component.tsx` - ✅ `/any/path/script.js` - ❌ `/any/path/component.test.ts` - ❌ `/any/path/README.md` ## Troubleshooting ### Issue: "Access denied" but path should be allowed **Solution:** Check pattern syntax and order: 1. Verify the path is absolute: ```bash readlink -f /path/to/file ``` 2. Check pattern matching: ```bash cat ~/.mcp-clipboard/paths.allow ``` 3. Ensure no negation pattern is overriding: ``` # Wrong order !**/blocked/** /home/user/project/** # Correct order /home/user/project/** !**/blocked/** ``` ### Issue: All paths denied unexpectedly **Solution:** The file might have no valid patterns. Add at least one allow pattern or delete the file to allow all paths. ### Issue: Patterns not working after update **Solution:** Restart the MCP server to reload the configuration. ## Migration Guide If you're upgrading from a version without path access control: 1. **No action required** - The default behavior allows all paths 2. **To restrict access** - Create `~/.mcp-clipboard/paths.allow` with your desired patterns 3. **Test thoroughly** - Ensure your AI workflows still work with the new restrictions ## Related Documentation - [Security Report](SECURITY_REPORT.md) - Overall security posture - [Release Security Audit](RELEASE_SECURITY_AUDIT.md) - Security findings and mitigations - [Architecture](ARCHITECTURE.md) - System design and components