Status: Proposed
Target: MCPB Specification v0.4+
Submitted by: datHere, Inc. (qsv MCP Server maintainers), proposal drafted by @claude
Date: 2026-01-07

Problem Statement

Currently, all Desktop Extensions (.mcpb) that have filesystem capabilities trigger a generic warning during installation:

⚠️ Installing will grant access to everything on your computer.

This warning appears regardless of whether the extension has restricted filesystem access. This creates two problems:

1. User Trust & Adoption Barrier

The warning is overly alarming for extensions with legitimately restricted scope, potentially deterring users from installing safe, useful extensions.

Example: The qsv Data Wrangling extension only accesses files in user-selected directories (e.g., ~/Downloads and ~/Documents), yet shows the same warning as an extension that might access the entire filesystem.

2. Inaccurate Security Information

The warning provides no granularity about actual filesystem access scope. Users cannot distinguish between:

• Extensions with unrestricted filesystem access (genuinely concerning)
• Extensions with user-selected directory access (reasonable and safe)
• Extensions with read-only access (minimal risk)
• Extensions with specific file type restrictions (targeted scope)

Current Workarounds

Extension developers are forced to use workarounds that don't solve the core issue:

1. Disclaimers in Description

{
  "description": "Despite the generic warning, will only access APPROVED DIRECTORIES on your computer."
}

Limitation: Easy to miss, not machine-readable, no enforcement

2. Directory Type User Config

{
  "user_config": {
    "allowed_dirs": {
      "type": "directory",
      "multiple": true,
      "description": "Extension access is restricted to these directories only."
    }
  }
}

Limitation: Provides better UX but doesn't change the installation warning

3. Detailed Documentation

Extensive security documentation explaining actual restrictions.

Limitation: Requires users to read external docs before installation

Proposed Solution

Add a new filesystem_access field to the MCPB manifest specification that declares filesystem permissions declaratively.

Minimal Implementation

{
  "manifest_version": "0.4",
  "name": "my-extension",
  "filesystem_access": {
    "scope": "user_selected_directories",
    "sources": ["${user_config.working_dir}", "${user_config.allowed_dirs}"]
  }
}

Full Specification

{
  "filesystem_access": {
    "scope": "user_selected_directories" | "unrestricted" | "none",
    "sources": ["array of user_config references"],
    "permissions": "read" | "write" | "read-write",
    "file_types": ["csv", "xlsx", "json", "txt", "*"],
    "max_file_size_mb": 100,
    "description": "Human-readable explanation of access needs"
  }
}

Field Definitions

scope (required)

• "none": Extension has no filesystem access

  • Warning: None
  • Use case: Pure API/network extensions

• "user_selected_directories": Access limited to directories user explicitly selects in config

  • Warning: "Installing will grant access to directories you select during setup"
  • Use case: File processing tools (qsv, image converters, etc.)

• "unrestricted": Extension can access entire filesystem

  • Warning: "Installing will grant access to everything on your computer"
  • Use case: System utilities, backup tools, full IDE integrations

sources (optional, required if scope = "user_selected_directories")

• Array of references to user_config fields of type directory
• Validates that declared directories match actual config
• Example: ["${user_config.working_dir}", "${user_config.allowed_dirs}"]

permissions (optional, default: "read-write")

• "read": Read-only filesystem access
• "write": Write-only access (rare)
• "read-write": Full read and write access

file_types (optional, default: ["*"])

• Array of file extensions the extension works with
• Informational only (not enforced, but shown to users)
• Use "*" for all file types
• Example: ["csv", "tsv", "xlsx", "ods", "json", "jsonl"]

max_file_size_mb (optional)

• Informational hint about practical file size limits
• Helps users understand extension capabilities
• Not enforced, but displayed in extension details

description (optional)

• Human-readable explanation of why filesystem access is needed
• Shown alongside the installation warning
• Example: "Processes CSV, Excel, and JSONL files locally on your machine"

Implementation Impact

For Claude Desktop

1. Warning Customization

   function getInstallationWarning(manifest) {
     if (!manifest.filesystem_access || manifest.filesystem_access.scope === "none") {
       return null; // No filesystem warning
     }
   
     if (manifest.filesystem_access.scope === "user_selected_directories") {
       return {
         level: "info",
         message: `Installing will grant access to directories you select during setup`,
         details: manifest.filesystem_access.description
       };
     }
   
     return {
       level: "warning",
       message: "Installing will grant access to everything on your computer",
       details: manifest.filesystem_access.description
     };
   }

2. Permission Validation

   • Validate sources references exist in user_config
   • Check that referenced fields are type directory or file
   • Reject manifests with invalid declarations

3. UI Enhancements

   • Show scope, permissions, and file types in extension details
   • Display "Restricted Access" badge for user-selected scopes
   • Provide expandable "What can this extension access?" section

For Extension Developers

1. Explicit Declaration

   {
     "filesystem_access": {
       "scope": "user_selected_directories",
       "sources": ["${user_config.data_dir}"],
       "permissions": "read",
       "file_types": ["csv", "tsv"],
       "description": "Analyzes CSV files in your selected directory"
     }
   }

2. Backward Compatibility

   • If filesystem_access is omitted, assume scope: "unrestricted" (current behavior)
   • Existing extensions continue to work unchanged
   • Gradual adoption as developers add declarations

3. Validation Benefits

   • Extensions can be validated at package time
   • Marketplace can categorize by access scope
   • Users can filter by permission requirements

Use Cases & Examples

Case 1: Data Processing Tool (qsv)

Need: Process user's CSV/Excel files without uploading
Scope: User-selected directories only

{
  "filesystem_access": {
    "scope": "user_selected_directories",
    "sources": ["${user_config.working_dir}", "${user_config.allowed_dirs}"],
    "permissions": "read-write",
    "file_types": ["csv", "tsv", "ssv", "xlsx", "ods", "json", "jsonl"],
    "max_file_size_mb": 1000,
    "description": "Processes tabular data files in your selected directories. All processing happens locally - no data is uploaded."
  }
}

Warning shown: ℹ️ "Installing will grant access to directories you select during setup"

Case 2: Read-Only Documentation Browser

Need: Search and display local markdown files
Scope: User-selected documentation directory

{
  "filesystem_access": {
    "scope": "user_selected_directories",
    "sources": ["${user_config.docs_dir}"],
    "permissions": "read",
    "file_types": ["md", "markdown", "txt"],
    "description": "Searches and displays documentation files. Read-only access."
  }
}

Warning shown: ℹ️ "Installing will grant read-only access to directories you select during setup"

Case 3: API-Only Extension

Need: No filesystem access, only network requests
Scope: None

{
  "filesystem_access": {
    "scope": "none",
    "description": "Fetches data from external APIs. No local file access."
  }
}

Warning shown: None (or minimal network access warning)

Case 4: System Backup Utility

Need: Full filesystem access for comprehensive backups
Scope: Unrestricted

{
  "filesystem_access": {
    "scope": "unrestricted",
    "permissions": "read",
    "description": "Creates backups of your entire system. Requires full filesystem read access."
  }
}

Warning shown: ⚠️ "Installing will grant access to everything on your computer"

Benefits

1. Improved User Trust

• Accurate warnings match actual extension capabilities
• Users can make informed decisions
• Reduces false alarms for safe extensions

2. Better Security Transparency

• Machine-readable security declarations
• Marketplace can display security badges
• Easier security audits and reviews

3. Developer Experience

• Clear guidelines for filesystem access
• Validation errors catch misconfigurations
• Competitive advantage for restricted-access extensions

4. Ecosystem Health

• Encourages principle of least privilege
• Safer default behaviors
• Community trust in extension marketplace

Alternative Approaches Considered

Alternative 1: Per-Tool Permissions

Declare permissions at the tool level instead of extension level:

{
  "tools": [
    {
      "name": "process_csv",
      "filesystem_access": {
        "scope": "user_selected_directories",
        "permissions": "read-write"
      }
    }
  ]
}

Pros: More granular control
Cons: Complex for users, hard to explain, over-engineered for most use cases

Alternative 2: Runtime Permission Prompts

Prompt users each time extension accesses filesystem:

Pros: Maximum control
Cons: Friction, poor UX, not suitable for batch operations

Alternative 3: Sandboxed Execution

Run extensions in containers with filesystem mounts:

Pros: Enforced isolation
Cons: High implementation cost, platform-specific, performance overhead

Recommendation: Start with declarative approach (proposed solution), can add runtime prompts or sandboxing later

Migration Path

Phase 1: Specification Update (MCPB v0.4)

• Add filesystem_access field to manifest schema
• Make it optional (backward compatible)
• Document in MANIFEST.md

Phase 2: Claude Desktop Support

• Implement warning customization
• Add UI for permission display
• Validate manifests at installation time

Phase 3: Developer Adoption

• Update documentation with examples
• Encourage adoption through:
  • Marketplace "Verified Restricted Access" badges
  • Featured placement for properly declared extensions
  • Security audit requirements for unrestricted scope

Phase 4: Eventual Enforcement

• After adoption period (6-12 months), make field required
• Extensions without declaration default to scope: "unrestricted"
• Deprecation warnings for undeclared extensions

Open Questions

1. Should permissions be runtime-enforced?

   • Current proposal: Informational only
   • Future: Could enforce with OS-level sandboxing

2. How to handle permission escalation?

   • If extension updates to require more access, re-prompt user?
   • Require explicit user approval for scope changes?

3. File type restrictions?

   • Currently informational
   • Should Claude Desktop filter file picker by declared types?

4. Directory validation?

   • Should Claude Desktop validate paths are actually directories?
   • How to handle symlinks, mounted volumes?

5. Network + Filesystem combination?

   • Separate network_access field?
   • Combined capabilities object?

Success Metrics

User Trust

• Target: 50% reduction in user complaints about "scary" warnings
• Measure: Support tickets, forum discussions, app store reviews

Developer Adoption

• Target: 70% of new extensions declare filesystem_access within 6 months
• Measure: Marketplace analytics

Security Improvements

• Target: 90% of data-processing extensions use user_selected_directories scope
• Measure: Manifest analysis of published extensions

References

• MCPB Specification: https://github.com/modelcontextprotocol/mcpb/blob/main/MANIFEST.md
• MCP Filesystem Server: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
• Chrome Extension Permissions: https://developer.chrome.com/docs/extensions/reference/permissions/
• VS Code Extension Capabilities: https://code.visualstudio.com/api/extension-capabilities/overview
• Electron Security: https://www.electronjs.org/docs/latest/tutorial/security

Contact

Maintainer: Joel Natividad (datHere, Inc.)
Extension: qsv Data Wrangling MCP Server
Repository: https://github.com/dathere/qsv
Email: info@dathere.com

Appendix: Complete Example Manifest

{
  "manifest_version": "0.4",
  "name": "qsv-data-wrangling",
  "version": "13.0.0",
  "description": "Comprehensive data-wrangling toolkit for CSV, Excel, and JSONL files. Process local files without uploading.",

  "author": {
    "name": "datHere, Inc.",
    "url": "https://dathere.com"
  },

  "repository": {
    "type": "git",
    "url": "https://github.com/dathere/qsv"
  },

  "license": "MIT",

  "server": {
    "type": "node",
    "entry_point": "server/mcp-server.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/server/mcp-server.js"],
      "env": {
        "QSV_MCP_WORKING_DIR": "${user_config.working_dir}",
        "QSV_MCP_ALLOWED_DIRS": "${user_config.allowed_dirs}"
      }
    }
  },

  "user_config": {
    "working_dir": {
      "type": "directory",
      "title": "Working Directory",
      "description": "Primary directory for qsv operations",
      "required": true,
      "default": "${DOWNLOADS}"
    },
    "allowed_dirs": {
      "type": "directory",
      "title": "Additional Allowed Directories",
      "description": "Extra directories qsv can access",
      "required": false,
      "multiple": true
    }
  },

  "filesystem_access": {
    "scope": "user_selected_directories",
    "sources": ["${user_config.working_dir}", "${user_config.allowed_dirs}"],
    "permissions": "read-write",
    "file_types": ["csv", "tsv", "ssv", "xlsx", "ods", "json", "jsonl"],
    "max_file_size_mb": 1000,
    "description": "Processes tabular data files in your selected directories. All processing happens locally - no data is uploaded to any server."
  },

  "tools": [
    {
      "name": "qsv_stats",
      "description": "Calculate statistics for CSV columns"
    }
  ],

  "tools_generated": true,

  "compatibility": {
    "platforms": ["darwin", "win32", "linux"]
  }
}