[BUG] npx @gleanwork/local-mcp-server fails with EUNSUPPORTEDPROTOCOL for workspace:*

npx @gleanwork/local-mcp-server Fails with EUNSUPPORTEDPROTOCOL

Users are encountering an issue when trying to run the @gleanwork/local-mcp-server package using npx. The command fails with an npm error: EUNSUPPORTEDPROTOCOL and the message "Unsupported URL Type 'workspace:': workspace:*". This prevents the local MCP server from starting, hindering development and testing workflows.

Root Cause

The root cause of this issue lies in how npm (versions 7 and above, and potentially related to npm's handling of workspaces) resolves dependencies when used with npx. The workspace:* protocol is intended for managing dependencies within a monorepo setup. When npx attempts to install @gleanwork/local-mcp-server, it incorrectly interprets or fails to resolve this protocol, leading to the EUNSUPPORTEDPROTOCOL error.

Solution

There are a few potential workarounds to resolve this issue:

1. Specify a Version: Explicitly specify a version number when installing the package. This bypasses the workspace resolution issue. For example:

npx -y gleanwork/local-mcp-server@0.8.0

2. Global Installation: Install the package globally using npm install -g. This might resolve the issue by making the package available system-wide.

npm install -g @gleanwork/local-mcp-server
local-mcp-server

3. Downgrade npm (Not Recommended): Downgrading npm to a version prior to v7 might resolve the issue, but this is generally not recommended due to potential security vulnerabilities and compatibility issues with other packages.
4. Using a Different Package Manager: Consider using pnpm or yarn which handle workspace protocols differently and may not exhibit the same issue.

pnpm dlx @gleanwork/local-mcp-server

MCP Client Configuration Considerations

If you are using the MCP client with a configuration like this:

{
  "mcpServers": {
    "glean": {
      "command": "npx",
      "args": ["-y", "@gleanwork/local-mcp-server"],
      "env": {
        "GLEAN_INSTANCE": "<redacted>",
        "GLEAN_API_TOKEN": "<redacted>"
      }
    }
  }
}

Modify the args array to include the specific version:

{
  "mcpServers": {
    "glean": {
      "command": "npx",
      "args": ["-y", "gleanwork/local-mcp-server@0.8.0"],
      "env": {
        "GLEAN_INSTANCE": "<redacted>",
        "GLEAN_API_TOKEN": "<redacted>"
      }
    }
  }
}

Additional Tips and Considerations

• Always ensure your environment variables (GLEAN_INSTANCE, GLEAN_API_TOKEN, etc.) are correctly set before running the MCP server.
• Keep your Node.js and npm versions up-to-date (while being mindful of potential compatibility issues) to benefit from the latest bug fixes and security patches.
• If the problem persists, consider reporting the issue to the @gleanwork/local-mcp-server maintainers, providing detailed information about your environment and the steps you've taken to reproduce the error.