DEV Community

Cover image for Protocol Launcher Series: Gracefully Launch VS Code from Web Pages and CLI
zhensherlock
zhensherlock

Posted on

Protocol Launcher Series: Gracefully Launch VS Code from Web Pages and CLI

#typescript #webdev #javascript #ai

After introducing one-click configuration for Cherry Studio, let’s look at the editor developers use most often — Visual Studio Code (VS Code).

As developers, we frequently need flows like:

  • Click a file path on an error log page to open that file in local VS Code and jump directly to the error line.
  • Automatically open the generated project directory in VS Code after a CLI tool finishes its work.
  • Guide users to connect to a remote server and open a specific development directory with one click.
  • Provide a button in documentation that opens a related configuration file directly in the editor.

VS Code Protocols and Deep Links

Visual Studio Code offers powerful deep link support, allowing developers to trigger editor actions directly from external apps, web pages, or the command line via the vscode:// protocol.

However, manually assembling these links often involves complex path handling, line and column calculations, and tedious character encoding.

With Protocol Launcher, you can wrap all of this into simple function calls and get elegant app launch behavior.

Core Capabilities: Precise Control and Remote Support

Protocol Launcher provides a dedicated protocol-launcher/vscode module with the following core features:

  1. Open files precisely: Jump to an exact line and column.
  2. Manage workspaces: Open local folders or project directories with one call.
  3. Remote development integration: Trigger remote connections via SSH or other protocols.
  4. Quick system actions: For example, jump to the settings UI in one click.

Quick Start

First, make sure you have installed the package:

npm install protocol-launcher
Enter fullscreen mode Exit fullscreen mode

In your code, you can choose between two import styles:

  • On-demand imports (via subpaths) with tree shaking for smaller bundle size.
  • Full imports (from the root package) with simpler syntax but including all supported app logic. 
// ✅ Recommended: load only the VS Code module on demand
import { openFile, openFolder, openRemote, openSettings, installMCP } from 'protocol-launcher/vscode'

// You can also import from the root package, but this will include all app modules
// import { vscode } from 'protocol-launcher'
Enter fullscreen mode Exit fullscreen mode

Scenario 1: Install an STDIO MCP Service (installMCP)

The following example installs the official server-everything test server, which is ideal for validating VS Code’s MCP capabilities:

import { installMCP } from 'protocol-launcher/vscode'

const url = installMCP({
  name: 'server-everything', // Service name, for display and identification
  type: 'stdio', // Communication type, supports stdio, streamable_http, sse, etc.
  command: 'npx', // Startup command, e.g., npx, docker, etc.
  args: ['-y', '@modelcontextprotocol/server-everything'], // Startup arguments
})
Enter fullscreen mode Exit fullscreen mode

You can bind the generated url to a button or link so users can add an MCP service in VS Code with a single click.

Scenario 2: Install a Streamable HTTP MCP Service (installMCP)

For cloud-hosted MCP services, you can use the streamable_http transport protocol and configure authentication via url and headers:

import { installMCP } from 'protocol-launcher/vscode'

const url = installMCP({
  name: 'QCC Company Info MCP', // Service name, for display and identification
  type: 'streamable_http', // Communication type, supports stdio, streamable_http, sse, etc.
  url: 'https://mcp.qcc.com/basic/stream', // Service URL
  headers: { // Custom headers, for authentication, etc.
    Authorization: 'YOUR_QCC_TOKEN',
  },
})
Enter fullscreen mode Exit fullscreen mode

Scenario 3: Install an SSE MCP Service (installMCP)

If your service pushes results to VS Code via Server-Sent Events (SSE), you can install it using type: 'sse':

import { installMCP } from 'protocol-launcher/vscode'

const url = installMCP({
  name: 'QCC Company Risk MCP', // Service name, for display and identification
  type: 'sse', // Communication type, supports stdio, streamable_http, sse, etc.
  url: 'https://mcp.qcc.com/basic/sse', // Service URL
  headers: { // Custom headers, for authentication, etc.
    Authorization: 'YOUR_QCC_TOKEN',
  },
})
Enter fullscreen mode Exit fullscreen mode

Scenario 4: Open a File Precisely (openFile)

You can specify the file path, line, and column, and even decide whether to open it in a new window. This is especially useful for error monitoring systems or log analysis tools:

import { openFile } from 'protocol-launcher/vscode'

const url = openFile({
  path: '/Users/dev/project/src/index.ts', // Absolute path to the file
  line: 42, // Optional: jump to line 42
  column: 10, // Optional: jump to column 10
  openInNewWindow: true, // Optional: whether to open in a new window
})
Enter fullscreen mode Exit fullscreen mode

Scenario 5: Open a Folder or Workspace (openFolder)

After a scaffolding tool or automation script finishes running, you can automatically open the project directory for the user:

import { openFolder } from 'protocol-launcher/vscode'

const url = openFolder({
  path: '/Users/dev/project', // Absolute path to the folder
  openInNewWindow: false, // Optional: whether to open in a new window
})
Enter fullscreen mode Exit fullscreen mode

Scenario 6: Remote Development Connection (openRemote)

If you want to guide users to develop on a remote server, you can generate an SSH remote development link directly. This greatly simplifies configuring remote environments:

import { openRemote } from 'protocol-launcher/vscode'

const url = openRemote({
  type: 'ssh-remote', // Remote type, supports ssh-remote, wsl, dev-container
  host: 'root@172.18.105.209:22', // Remote host identifier, e.g., root@IP or SSH Alias
  path: '/code/my-project', // Path inside the remote environment
})
Enter fullscreen mode Exit fullscreen mode

Scenario 7: One-Click Settings (openSettings)

If you’re building a VS Code extension or related tool, you can use this link to guide users to the settings interface:

import { openSettings } from 'protocol-launcher/vscode'

const url = openSettings()
Enter fullscreen mode Exit fullscreen mode

Why Protocol Launcher?

  1. Automatic encoding and Unicode support: Whether it’s Chinese paths, special symbols, or complex CJK characters, the library handles them internally to ensure generated URLs are valid and never garbled when launching the app. You no longer need to manually call encodeURIComponent.
  2. Type safety and parameter hints: TypeScript IntelliSense shows which parameters are optional and which are required (for example, line must be a number). This is especially important when composing complex remote connection links.
  3. Cross-platform compatibility: Generated links follow VS Code’s official specifications and behave consistently across macOS, Windows, and Linux, hiding low-level protocol differences.
  4. Extreme tree shaking: The modular design supports tree shaking to minimize bundle size:
    • Recommended: Use subpath imports (such as import { openFile } from 'protocol-launcher/vscode') so that the bundler only includes VS Code–related code instead of logic for all other apps.
    • Full import: For simple scripts or demos, you can import from the root package (such as import { vscode } from 'protocol-launcher'), but this will include all supported application modules. For production, subpath imports are recommended.

Conclusion

VS Code’s deep link support is already very powerful, and Protocol Launcher makes it even easier and more robust to use. Whether in web pages or command-line tools, it is a great way to launch the editor.

🔗 Related Links

Top comments (0)