Vscode Internal Command MCP Server

🚀 VSCode Internal Command MCP Server

A VSCode extension based on the FastMCP framework that transforms VSCode into an MCP (Model Context Protocol) server. It enables external clients to execute VSCode internal commands via HTTP Streaming and Server-Sent Events (SSE).

✨ Features

• 🌐 HTTP Streaming Support: Utilizes the text/event-stream protocol for real-time communication.
• 🔧 VSCode Command Execution: Remotely execute any VSCode internal command.
• 📊 Workspace Information Query: Retrieve the current workspace status and file information.
• ⚡ Asynchronous Background Execution: Supports asynchronous command execution without blocking the user interface.
• ⏰ Configurable Delay: Allows setting a delay for command execution.
• 🛡️ Security Control: Features a configurable command whitelist mechanism.
• 📡 Real-time Status Monitoring: Displays the server's running status in the status bar.
• 🔗 Standard MCP Protocol: Fully compliant with the Model Context Protocol specification.
• ⚡ High Performance: Based on the FastMCP framework, supporting concurrent requests and session management.
• 🩺 Health Check: Includes a built-in health check endpoint.

📦 Installation

1. Clone the Project

git clone https://github.com/bestk/vscode-internal-command-mcp-server
cd vscode-internal-command-mcp-server

2. Install Dependencies

npm install

3. Compile the Project

npm run compile

4. Install in VSCode

• Press F5 to launch the extension development host.
• Or package it as a .vsix file for installation.

⚙️ Configuration

Configure the server parameters in the VSCode settings:

{
    "vscode-internal-command-mcp-server.port": 8080,
    "vscode-internal-command-mcp-server.host": "localhost",
    "vscode-internal-command-mcp-server.autoStart": true,
    "vscode-internal-command-mcp-server.asyncExecution": true,
    "vscode-internal-command-mcp-server.executionDelay": 1000,
    "vscode-internal-command-mcp-server.showAsyncNotifications": false,
    "vscode-internal-command-mcp-server.allowedCommands": [
        "editor.action.formatDocument",
        "workbench.action.files.save",
        "editor.action.clipboardCopyAction"
    ]
}

Configuration Details

🚀 Usage

Start the Server

1. Automatic Start: The server starts automatically when the extension is activated (if autoStart is true).
2. Manual Start:
   • Command Palette: VSCode Internal Command MCP Server: Start Server
   • Or click the 🚀 VSCode internal command MCP button in the status bar.

Server Addresses

• MCP Endpoint: http://localhost:8080/mcp
• Health Check: http://localhost:8080/health

Status Monitoring

• Status Bar Display: 🚀 VSCode internal command MCP 🟢 (Running) / 🚀 VSCode internal command MCP 🔴 (Stopped)
• Command Palette: VSCode Internal Command MCP Server: Show Status to view detailed status.

🛠️ Available Tools (MCP Tools)

1. execute_vscode_command

Execute a VSCode internal command.

Parameters:

{
  command: string;      // VSCode command ID
  arguments?: string[]; // Command arguments (optional)
}

Example of Asynchronous Execution Response:

{
    "success": true,
    "async": true,
    "taskId": "bg_task_1_1756952250790",
    "message": "The command 'composer.cancelComposerStep' has been submitted for background execution and will be executed after 1000ms.",
    "command": "composer.cancelComposerStep",
    "arguments": [],
    "executionDelay": 1000,
    "queueLength": 1,
    "taskStats": {
        "total": 1,
        "pending": 1,
        "running": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0
    }
}

2. list_vscode_commands

List all available VSCode commands.

Parameters: None

Return: A list of commands (the first 20, with an ellipsis if there are more).

3. get_workspace_info

Get information about the current workspace.

Parameters: None

Return:

{
    name: string; // Workspace name
    folders: Array<{
        // Workspace folders
        name: string;
        uri: string;
    }>;
    activeEditor: string; // File path of the current active editor
}

🔌 Client Connection

Use the Official MCP SDK

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:8080/mcp'), {
    requestInit: {
        headers: {
            'Content-Type': 'application/json',
            Accept: 'application/json, text/event-stream',
        },
    },
});

const client = new Client({
    name: 'vscode-mcp-client',
    version: '1.0.0',
});

// Connect and use
await client.connect(transport);

// Call a tool
const result = await client.callTool({
    name: 'execute_vscode_command',
    arguments: {
        command: 'editor.action.formatDocument',
    },
});

console.log('Command result:', result);

Use Cursor

Configure the MCP server in Cursor:

{
    "mcpServers": {
        "vscode-internal-commands": {
            "url": "http://localhost:8080/mcp",
            "transport": "http"
        }
    }
}

Test with curl

# Health check
curl http://localhost:8080/health

# List tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Execute a command
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "execute_vscode_command",
      "arguments": {
        "command": "workbench.action.files.save"
      }
    }
  }'

🏗️ Technical Architecture

Core Components

┌─────────────────────────┐
│   VSCode Extension      │
├─────────────────────────┤
│   FastMcpServer         │ ← Based on the FastMCP framework
├─────────────────────────┤
│   ServerManager         │ ← Server management and status
├─────────────────────────┤
│   CommandExecutor       │ ← VSCode command executor
├─────────────────────────┤
│ BackgroundTaskExecutor  │ ← Background task executor
├─────────────────────────┤
│   TaskProvider          │ ← VS Code task provider
└─────────────────────────┘

Technology Stack

• Framework: FastMCP - A TypeScript MCP server framework.
• Protocol: Model Context Protocol (MCP)
• Transport: HTTP Streaming with Server-Sent Events (SSE)
• Validation: Zod Schema validation
• Platform: VSCode Extension API
• Asynchronous Execution: Background task queue based on setInterval

Network Protocol

• Transport Type: httpStream
• Content Type: text/event-stream
• Supported Protocol: HTTP/1.1
• CORS: Enabled by default

Asynchronous Execution Mechanism

• Task Queue: An in-memory queue based on the Map data structure.
• Executor: Uses setInterval to periodically check for tasks to be executed.
• Status Management: Supports pending, running, completed, failed, and cancelled states.
• Delayed Execution: Allows configuring a delay for tasks to execute after a specified time.
• Notification System: Optional notification upon execution completion.

🔧 Development

Project Structure

vscode-internal-command-mcp-server/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── fastMcpServer.ts         # FastMCP server implementation
│   ├── serverManager.ts         # Server manager
│   ├── commandExecutor.ts       # VSCode command executor
│   ├── backgroundTaskExecutor.ts # Background task executor
│   └── taskProvider.ts          # VS Code task provider
├── out/                         # Compiled output
├── package.json                 # Extension configuration and dependencies
├── tsconfig.json               # TypeScript configuration
└── README.md                   # Project documentation

Development Commands

# Compile in development mode
npm run compile

# Compile in watch mode
npm run watch

# Start development
code . # Open VSCode and press F5 to start debugging

Debugging

1. Open the project in VSCode.
2. Press F5 to launch the extension development host.
3. Test the extension's functionality in the new window.
4. View the output in the debug console.

🧪 Testing

Use the Built-in Testing Tool

1. After starting the server, use the command: VSCode Internal Command MCP Server: Test MCP Tools.
2. Select the tool to test.
3. Enter the necessary parameters.
4. View the execution result.

Use the FastMCP CLI

# Test with the FastMCP development tool
npx fastmcp dev src/fastMcpServer.ts

# Check with the MCP Inspector
npx fastmcp inspect src/fastMcpServer.ts

🛡️ Security Considerations

Command Whitelist

For security reasons, it is recommended to configure the allowedCommands whitelist:

{
    "vscode-internal-command-mcp-server.allowedCommands": [
        "editor.action.formatDocument",
        "workbench.action.files.save",
        "workbench.action.files.saveAll",
        "editor.action.clipboardCopyAction",
        "editor.action.clipboardPasteAction"
    ]
}

Network Security

• By default, it only listens on localhost to prevent external access.
• CORS is supported, but it is recommended to configure appropriate origin restrictions in a production environment.
• All command executions occur within the VSCode security context.

Asynchronous Execution Security

• The task queue is managed in memory and is automatically cleared when the extension is closed.
• Supports task cancellation and status monitoring.
• Provides detailed error information when execution fails.

📝 Release Notes

v0.0.2 (Current Version)

• ✅ Refactored the asynchronous execution mechanism using a background task queue.
• ✅ Fixed the configuration refresh issue to ensure that configuration changes take effect immediately.
• ✅ Optimized task status management and monitoring.
• ✅ Improved error handling and logging.
• ✅ Simplified the code structure and removed redundant components.

v0.0.1

• ✅ Implemented an MCP server based on the FastMCP framework.
• ✅ Supported HTTP Streaming and SSE.
• ✅ Implemented three core tools: command execution, command listing, and workspace information retrieval.
• ✅ Integrated with the status bar for real-time monitoring.
• ✅ Added a health check endpoint.
• ✅ Implemented Zod Schema parameter validation.
• ✅ Supported TypeScript 5.9+.

🤝 Contribution

Welcome to submit issues and pull requests!

Development Guide

1. Fork the project.
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push the branch: git push origin feature/amazing-feature
5. Create a pull request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastMCP - An excellent TypeScript MCP framework.
• Model Context Protocol - A standard protocol specification.
• VSCode Extension API - A powerful extension platform.

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page.
2. Create a new issue.
3. Refer to the FastMCP documentation: https://github.com/punkpeye/fastmcp

🚀 Transform VSCode into your MCP server and unlock endless possibilities!