SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:1340-1438 (handler)

  The handler function for 'ssh_docker_deploy' tool. It validates input using DockerDeploySchema, constructs Docker commands (docker-compose up, docker build, or docker run) based on deploymentType, executes them remotely via SSH in the specified working directory, and returns the command output including stdout, stderr, and exit code.

  private async handleDockerDeploy(args: unknown) {
    const params = DockerDeploySchema.parse(args);
    
    const context = connectionContexts.get(params.connectionId);
    if (!context) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Connection ID '${params.connectionId}' not found`
      );
    }
  
    try {
      // Set working directory for this operation
      const workingDir = params.workingDirectory;
      
      let command = '';
      let envPrefix = '';
      
      // Build environment variables prefix
      if (params.envVars) {
        const envVarStrings = Object.entries(params.envVars).map(([key, value]) => `${key}="${value}"`);
        envPrefix = envVarStrings.join(' ') + ' ';
      }
      
      switch (params.deploymentType) {
        case 'compose':
          command = `${envPrefix}docker-compose`;
          if (params.composeFile && params.composeFile !== 'docker-compose.yml') {
            command += ` -f ${params.composeFile}`;
          }
          command += ' up';
          if (params.detached) {
            command += ' -d';
          }
          break;
          
        case 'build':
          if (!params.imageName) {
            throw new McpError(
              ErrorCode.InvalidParams,
              'imageName is required for build deployment type'
            );
          }
          command = `${envPrefix}docker build`;
          if (params.buildArgs) {
            Object.entries(params.buildArgs).forEach(([key, value]) => {
              command += ` --build-arg ${key}="${value}"`;
            });
          }
          command += ` -t ${params.imageName} .`;
          break;
          
        case 'run':
          if (!params.imageName) {
            throw new McpError(
              ErrorCode.InvalidParams,
              'imageName is required for run deployment type'
            );
          }
          command = `${envPrefix}docker run`;
          if (params.detached) {
            command += ' -d';
          }
          if (params.containerName) {
            command += ` --name ${params.containerName}`;
          }
          if (params.ports) {
            params.ports.forEach(port => {
              command += ` -p ${port}`;
            });
          }
          if (params.volumes) {
            params.volumes.forEach(volume => {
              command += ` -v ${volume}`;
            });
          }
          command += ` ${params.imageName}`;
          break;
      }
      
      const result = await context.ssh.execCommand(command, {
        cwd: workingDir,
      });
      
      return {
        content: [
          {
            type: 'text',
            text: `Docker ${params.deploymentType} deployment:\nCommand: ${command}\nExit Code: ${result.code}\n\nSTDOUT:\n${result.stdout}\n\nSTDERR:\n${result.stderr}`,
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Docker deployment failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  }

• src/index.ts:157-169 (schema)

  Zod schema defining the input parameters and validation for the ssh_docker_deploy tool.

  const DockerDeploySchema = z.object({
    connectionId: z.string().describe('SSH connection ID'),
    workingDirectory: z.string().describe('Directory containing docker-compose.yml or Dockerfile'),
    deploymentType: z.enum(['compose', 'build', 'run']).describe('Type of Docker deployment'),
    imageName: z.string().optional().describe('Docker image name (for build/run)'),
    containerName: z.string().optional().describe('Container name (for run)'),
    composeFile: z.string().default('docker-compose.yml').describe('Docker compose file name'),
    buildArgs: z.record(z.string()).optional().describe('Build arguments for Docker build'),
    envVars: z.record(z.string()).optional().describe('Environment variables'),
    ports: z.array(z.string()).optional().describe('Port mappings (e.g., ["8080:80", "3000:3000"])'),
    volumes: z.array(z.string()).optional().describe('Volume mappings (e.g., ["/host/path:/container/path"])'),
    detached: z.boolean().default(true).describe('Run in detached mode')
  });

• src/index.ts:443-463 (registration)

  Tool registration in the ListTools response, defining name, description, and inputSchema mirroring the Zod schema.

  {
    name: 'ssh_docker_deploy',
    description: 'Deploy Docker containers with working directory context',
    inputSchema: {
      type: 'object',
      properties: {
        connectionId: { type: 'string', description: 'SSH connection ID' },
        workingDirectory: { type: 'string', description: 'Directory containing docker-compose.yml or Dockerfile' },
        deploymentType: { type: 'string', enum: ['compose', 'build', 'run'], description: 'Type of Docker deployment' },
        imageName: { type: 'string', description: 'Docker image name (for build/run)' },
        containerName: { type: 'string', description: 'Container name (for run)' },
        composeFile: { type: 'string', default: 'docker-compose.yml', description: 'Docker compose file name' },
        buildArgs: { type: 'object', description: 'Build arguments for Docker build' },
        envVars: { type: 'object', description: 'Environment variables' },
        ports: { type: 'array', items: { type: 'string' }, description: 'Port mappings (e.g., ["8080:80", "3000:3000"])' },
        volumes: { type: 'array', items: { type: 'string' }, description: 'Volume mappings (e.g., ["/host/path:/container/path"])' },
        detached: { type: 'boolean', default: true, description: 'Run in detached mode' }
      },
      required: ['connectionId', 'workingDirectory', 'deploymentType']
    },
  },

• src/index.ts:517-518 (registration)

  Dispatch case in the CallToolRequest handler that routes to the handleDockerDeploy function.

  case 'ssh_docker_deploy':
    return await this.handleDockerDeploy(args);