mcp-server-kubernetes

Instructions

Implementation Reference

• src/tools/port_forward.ts:75-119 (handler)

  The core handler function `startPortForward` that spawns the `kubectl port-forward` process, tracks it via KubernetesManager, and handles success/error responses.

  export async function startPortForward(
    k8sManager: KubernetesManager,
    input: {
      resourceType: string;
      resourceName: string;
      localPort: number;
      targetPort: number;
      namespace?: string;
    }
  ): Promise<{ content: { success: boolean; message: string }[] }> {
    let command = `kubectl port-forward`;
    if (input.namespace) {
      command += ` -n ${input.namespace}`;
    }
    command += ` ${input.resourceType}/${input.resourceName} ${input.localPort}:${input.targetPort}`;
  
    try {
      const result = await executeKubectlCommandAsync(command);
      // Track the port-forward process
      k8sManager.trackPortForward({
        id: `${input.resourceType}-${input.resourceName}-${input.localPort}`,
        server: {
          stop: async () => {
            try {
              process.kill(result.pid);
            } catch (error) {
              console.error(
                `Failed to stop port-forward process ${result.pid}:`,
                error
              );
            }
          },
        },
        resourceType: input.resourceType,
        name: input.resourceName,
        namespace: input.namespace || "default",
        ports: [{ local: input.localPort, remote: input.targetPort }],
      });
      return {
        content: [{ success: result.success, message: result.message }],
      };
    } catch (error: any) {
      throw new Error(`Failed to execute port-forward: ${error.message}`);
    }
  }

• src/tools/port_forward.ts:56-73 (schema)

  Tool schema defining name, description, annotations, and input schema for the `port_forward` tool.

  export const PortForwardSchema = {
    name: "port_forward",
    description: "Forward a local port to a port on a Kubernetes resource",
    annotations: {
      title: "Port Forward",
    },
    inputSchema: {
      type: "object",
      properties: {
        resourceType: { type: "string" },
        resourceName: { type: "string" },
        localPort: { type: "number" },
        targetPort: { type: "number" },
        namespace: { type: "string" },
      },
      required: ["resourceType", "resourceName", "localPort", "targetPort"],
    },
  };

• src/index.ts:480-491 (registration)

  Registration and dispatch logic in the main tool handler switch statement, mapping 'port_forward' calls to the startPortForward function.

  case "port_forward": {
    return await startPortForward(
      k8sManager,
      input as {
        resourceType: string;
        resourceName: string;
        localPort: number;
        targetPort: number;
        context?: string;
      }
    );
  }

• src/index.ts:129-130 (registration)

  Inclusion of PortForwardSchema in the allTools array for tool listing and filtering.

  PortForwardSchema,
  StopPortForwardSchema,

• src/tools/port_forward.ts:6-54 (helper)

  Helper function to execute kubectl port-forward using child_process.spawn, detect success via 'Forwarding from' message, and capture PID and errors.

  async function executeKubectlCommandAsync(
    command: string
  ): Promise<{ success: boolean; message: string; pid: number }> {
    return new Promise((resolve, reject) => {
      const [cmd, ...args] = command.split(" ");
      const process = spawn(cmd, args);
  
      let output = "";
      let errorOutput = "";
  
      process.stdout.on("data", (data) => {
        output += data.toString();
        if (output.includes("Forwarding from")) {
          resolve({
            success: true,
            message: "port-forwarding was successful",
            pid: process.pid!,
          });
        }
      });
  
      process.stderr.on("data", (data) => {
        errorOutput += data.toString();
      });
  
      process.on("error", (error) => {
        reject(new Error(`Failed to execute port-forward: ${error.message}`));
      });
  
      process.on("close", (code) => {
        if (code !== 0) {
          reject(
            new Error(
              `Port-forward process exited with code ${code}. Error: ${errorOutput}`
            )
          );
        }
      });
  
      // Set a timeout to reject if we don't see the success message
      setTimeout(() => {
        if (!output.includes("Forwarding from")) {
          reject(
            new Error("port-forwarding failed - no success message received")
          );
        }
      }, 5000);
    });
  }