feat: Add Pip Server Management MCP tools

Implement checkPythonEnvironment and startPipServer MCP tools:

- checkPythonEnvironment: Checks if Python environment supports Deephaven pip server
- startPipServer: Starts a managed Deephaven pip server

Key changes:
- Created MCP tools following established patterns
- Added pipServerController dependency to McpServer
- Wired dependency through McpController and ExtensionController
- Full test coverage with 10 passing tests
- Includes helpful hints for missing dependencies (#copilot-worktree-2026-01)

Author: bmingles

src/controllers/ExtensionController.ts

@@ -427,7 +427,8 @@ export class ExtensionController implements IDisposable {
       this._extensionInfo.mcpVersion,
       this._serverManager,
       this._pythonDiagnostics,
-      this._pythonWorkspace
+      this._pythonWorkspace,
+      this._pipServerController
     );
 
     this._context.subscriptions.push(this._mcpController);

src/controllers/McpController.ts

@@ -2,7 +2,12 @@ import * as vscode from 'vscode';
 import { ControllerBase } from './ControllerBase';
 import { McpServer } from '../mcp';
 import { McpServerDefinitionProvider } from '../providers';
-import type { IServerManager, IConfigService, McpVersion } from '../types';
+import type {
+  IServerManager,
+  IConfigService,
+  McpVersion,
+  PipServerController,
+} from '../types';
 import type { FilteredWorkspace } from '../services';
 import { isWindsurf, Logger } from '../util';
 import {
@@ -24,6 +29,7 @@ export class McpController extends ControllerBase {
   private _serverManager: IServerManager;
   private _pythonDiagnostics: vscode.DiagnosticCollection;
   private _pythonWorkspace: FilteredWorkspace;
+  private _pipServerController: PipServerController | null;
 
   private _mcpServer: McpServer | null = null;
   private _mcpServerDefinitionProvider: McpServerDefinitionProvider | null =
@@ -36,7 +42,8 @@ export class McpController extends ControllerBase {
     mcpVersion: McpVersion,
     serverManager: IServerManager,
     pythonDiagnostics: vscode.DiagnosticCollection,
-    pythonWorkspace: FilteredWorkspace
+    pythonWorkspace: FilteredWorkspace,
+    pipServerController: PipServerController | null
   ) {
     super();
 
@@ -46,6 +53,7 @@ export class McpController extends ControllerBase {
     this._serverManager = serverManager;
     this._pythonDiagnostics = pythonDiagnostics;
     this._pythonWorkspace = pythonWorkspace;
+    this._pipServerController = pipServerController;
 
     // Register copy MCP URL command
     this.registerCommand(COPY_MCP_URL_CMD, this.copyUrl, this);
@@ -101,7 +109,8 @@ export class McpController extends ControllerBase {
       this._mcpServer = new McpServer(
         this._pythonDiagnostics,
         this._pythonWorkspace,
-        this._serverManager
+        this._serverManager,
+        this._pipServerController
       );
       this.disposables.push(this._mcpServer);
 

src/mcp/McpServer.ts

@@ -2,13 +2,20 @@ import * as vscode from 'vscode';
 import { McpServer as SdkMcpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import * as http from 'http';
-import type { IServerManager, McpTool, McpToolSpec } from '../types';
+import type {
+  IServerManager,
+  McpTool,
+  McpToolSpec,
+  PipServerController,
+} from '../types';
 import { MCP_SERVER_NAME } from '../common';
 import {
+  createCheckPythonEnvTool,
   createListConnectionsTool,
   createListServersTool,
   createRunCodeFromUriTool,
   createRunCodeTool,
+  createStartPipServerTool,
 } from './tools';
 import { withResolvers } from '../util';
 import { DisposableBase, type FilteredWorkspace } from '../services';
@@ -26,17 +33,20 @@ export class McpServer extends DisposableBase {
   readonly pythonDiagnostics: vscode.DiagnosticCollection;
   readonly pythonWorkspace: FilteredWorkspace;
   readonly serverManager: IServerManager;
+  readonly pipServerController: PipServerController | null;
 
   constructor(
     pythonDiagnostics: vscode.DiagnosticCollection,
     pythonWorkspace: FilteredWorkspace,
-    serverManager: IServerManager
+    serverManager: IServerManager,
+    pipServerController: PipServerController | null
   ) {
     super();
 
     this.pythonDiagnostics = pythonDiagnostics;
     this.pythonWorkspace = pythonWorkspace;
     this.serverManager = serverManager;
+    this.pipServerController = pipServerController;
 
     // Create an MCP server
     this.server = new SdkMcpServer({
@@ -49,6 +59,8 @@ export class McpServer extends DisposableBase {
     this.registerTool(createRunCodeFromUriTool(this));
     this.registerTool(createListConnectionsTool(this));
     this.registerTool(createListServersTool(this));
+    this.registerTool(createCheckPythonEnvTool(this));
+    this.registerTool(createStartPipServerTool(this));
   }
 
   private registerTool<Spec extends McpToolSpec>({

src/mcp/tools/checkPythonEnvironment.spec.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createCheckPythonEnvTool } from './checkPythonEnvironment';
+import type { PipServerController } from '../../types';
+import { McpToolResponse } from '../utils/mcpUtils';
+
+vi.mock('vscode');
+
+const MOCK_EXECUTION_TIME_MS = 100;
+
+const EXPECTED_AVAILABLE = {
+  success: true,
+  message: 'Python environment is available',
+  details: {
+    isAvailable: true,
+    interpreterPath: '/path/to/python',
+  },
+  executionTimeMs: MOCK_EXECUTION_TIME_MS,
+} as const;
+
+const EXPECTED_NOT_AVAILABLE = {
+  success: true,
+  message: 'Python environment is not available',
+  details: {
+    isAvailable: false,
+  },
+  executionTimeMs: MOCK_EXECUTION_TIME_MS,
+} as const;
+
+const EXPECTED_CONTROLLER_NOT_AVAILABLE = {
+  success: false,
+  message: 'PipServerController not available',
+  executionTimeMs: MOCK_EXECUTION_TIME_MS,
+} as const;
+
+const EXPECTED_CHECK_ERROR = {
+  success: false,
+  message: 'Failed to check Python environment: Check failed',
+  executionTimeMs: MOCK_EXECUTION_TIME_MS,
+} as const;
+
+describe('checkPythonEnvironment', () => {
+  const mockPipServerController = {
+    checkPipInstall: vi.fn(),
+  } as unknown as PipServerController;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    vi.spyOn(McpToolResponse.prototype, 'getElapsedTimeMs').mockReturnValue(
+      MOCK_EXECUTION_TIME_MS
+    );
+  });
+
+  it('should return correct tool spec', () => {
+    const tool = createCheckPythonEnvTool({
+      pipServerController: mockPipServerController,
+    });
+
+    expect(tool.name).toBe('checkPythonEnvironment');
+    expect(tool.spec.title).toBe('Check Python Environment');
+    expect(tool.spec.description).toBe(
+      'Check if the Python environment supports starting a Deephaven pip server.'
+    );
+  });
+
+  it('should return error when pipServerController is null', async () => {
+    const tool = createCheckPythonEnvTool({ pipServerController: null });
+    const result = await tool.handler({});
+
+    expect(result.structuredContent).toEqual(EXPECTED_CONTROLLER_NOT_AVAILABLE);
+  });
+
+  it('should return success when Python environment is available', async () => {
+    vi.mocked(mockPipServerController.checkPipInstall).mockResolvedValue({
+      isAvailable: true,
+      interpreterPath: '/path/to/python',
+    });
+
+    const tool = createCheckPythonEnvTool({
+      pipServerController: mockPipServerController,
+    });
+    const result = await tool.handler({});
+
+    expect(mockPipServerController.checkPipInstall).toHaveBeenCalledOnce();
+    expect(result.structuredContent).toEqual(EXPECTED_AVAILABLE);
+  });
+
+  it('should return success when Python environment is not available', async () => {
+    vi.mocked(mockPipServerController.checkPipInstall).mockResolvedValue({
+      isAvailable: false,
+    });
+
+    const tool = createCheckPythonEnvTool({
+      pipServerController: mockPipServerController,
+    });
+    const result = await tool.handler({});
+
+    expect(mockPipServerController.checkPipInstall).toHaveBeenCalledOnce();
+    expect(result.structuredContent).toEqual(EXPECTED_NOT_AVAILABLE);
+  });
+
+  it('should handle errors from checkPipInstall', async () => {
+    const error = new Error('Check failed');
+    vi.mocked(mockPipServerController.checkPipInstall).mockRejectedValue(error);
+
+    const tool = createCheckPythonEnvTool({
+      pipServerController: mockPipServerController,
+    });
+    const result = await tool.handler({});
+
+    expect(result.structuredContent).toEqual(EXPECTED_CHECK_ERROR);
+  });
+});

src/mcp/tools/checkPythonEnvironment.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+import type {
+  McpTool,
+  McpToolHandlerResult,
+  PipServerController,
+} from '../../types';
+import { McpToolResponse } from '../utils';
+
+const spec = {
+  title: 'Check Python Environment',
+  description:
+    'Check if the Python environment supports starting a Deephaven pip server.',
+  inputSchema: {},
+  outputSchema: {
+    success: z.boolean(),
+    message: z.string(),
+    executionTimeMs: z.number().describe('Execution time in milliseconds'),
+    details: z
+      .object({
+        isAvailable: z.boolean(),
+        interpreterPath: z.string().optional(),
+      })
+      .optional(),
+  },
+} as const;
+
+type Spec = typeof spec;
+type HandlerResult = McpToolHandlerResult<Spec>;
+type CheckPythonEnvTool = McpTool<Spec>;
+
+export function createCheckPythonEnvTool({
+  pipServerController,
+}: {
+  pipServerController: PipServerController | null;
+}): CheckPythonEnvTool {
+  return {
+    name: 'checkPythonEnvironment',
+    spec,
+    handler: async (): Promise<HandlerResult> => {
+      const response = new McpToolResponse();
+
+      if (pipServerController == null) {
+        return response.error('PipServerController not available');
+      }
+
+      try {
+        const result = await pipServerController.checkPipInstall();
+
+        if (result.isAvailable) {
+          return response.success('Python environment is available', {
+            isAvailable: true,
+            interpreterPath: result.interpreterPath,
+          });
+        }
+
+        return response.success('Python environment is not available', {
+          isAvailable: false,
+        });
+      } catch (error) {
+        return response.error('Failed to check Python environment', error);
+      }
+    },
+  };
+}

src/mcp/tools/index.ts

@@ -1,4 +1,6 @@
+export * from './checkPythonEnvironment';
 export * from './listConnections';
 export * from './listServers';
 export * from './runCode';
 export * from './runCodeFromUri';
+export * from './startPipServer';