Shell Server

Instructions

Implementation Reference

• server.py:13-55 (handler)

  The terminal function is the handler for the 'terminal' tool, executing shell commands via subprocess.run.

  def terminal(
      command: Annotated[
          str,
          Field(
              description=(
                  "The shell command to execute. Runs via /bin/sh -c on Unix or cmd /c "
                  "on Windows. Pipes, redirects, and shell built-ins are supported. "
                  "Commands time out after 30 seconds."
              )
          ),
      ],
  ) -> str:
      """Run a shell command and return its output.
  
      Returns a single string containing stdout, and stderr when present.
      Non-zero exit codes are reported at the end of the output so the caller
      can detect failures without parsing exit status separately.
      """
      try:
          result = subprocess.run(
              command,
              shell=True,
              capture_output=True,
              text=True,
              timeout=30,
          )
      except subprocess.TimeoutExpired:
          return "Error: command timed out after 30 seconds."
      except Exception as exc:  # noqa: BLE001
          return f"Error: failed to execute command — {exc}"
  
      parts: list[str] = []
  
      if result.stdout:
          parts.append(result.stdout.rstrip())
  
      if result.stderr:
          parts.append(f"STDERR:\n{result.stderr.rstrip()}")
  
      if result.returncode != 0:
          parts.append(f"Exit code: {result.returncode}")
  
      return "\n".join(parts) if parts else "(no output)"

• server.py:12-12 (registration)

  Registration of the 'terminal' tool using the FastMCP decorator.

  @mcp.tool()