start_process

Instructions

Implementation Reference

• src/interactive_process_mcp/server.py:12-55 (handler)

  The primary MCP tool handler for 'start_process' using @mcp.tool() decorator. Accepts typed parameters (command, args, mode, name, cwd, env, timeout, rows, cols), creates a session via SessionManager.create(), waits briefly, reads initial output, and returns session_id, pid, and initial_output.

  @mcp.tool()
  def start_process(
      command: str,
      args: list[str] | None = None,
      mode: str = "pty",
      name: str | None = None,
      cwd: str | None = None,
      env: dict[str, str] | None = None,
      timeout: float = 10.0,
      rows: int = 24,
      cols: int = 80,
  ) -> dict:
      """Start an interactive process and return its session info.
  
      Args:
          command: The command to execute.
          args: Command arguments.
          mode: I/O mode — "pty" (pseudo-terminal) or "pipe". Default "pty".
          name: Optional human-readable session name.
          cwd: Working directory for the process.
          env: Environment variables (dict of string key-value pairs).
          timeout: Process startup timeout in seconds.
          rows: PTY row count (pty mode only).
          cols: PTY column count (pty mode only).
      """
      session_id = _mgr.create(
          command=command,
          args=args or [],
          mode=mode,
          name=name,
          cwd=cwd,
          env=env,
          timeout=timeout,
          rows=rows,
          cols=cols,
      )
      time.sleep(0.1)
      session = _mgr.get(session_id)
      initial = session.read_output(timeout=0.5, strip_ansi_flag=True)
      return {
          "session_id": session_id,
          "pid": session.pid,
          "initial_output": initial,
      }

• src/interactive_process_mcp/tools.py:16-35 (handler)

  An alternative handler for 'start_process' defined inside create_tools() as a closure. Accepts a raw args dict, delegates to SessionManager.create(), and returns session_id, pid, and initial_output. This is used by the test suite.

  def start_process(args: dict) -> dict:
      session_id = mgr.create(
          command=args["command"],
          args=args.get("args", []),
          mode=args.get("mode", "pty"),
          name=args.get("name"),
          cwd=args.get("cwd"),
          env=args.get("env"),
          timeout=args.get("timeout", 10),
          rows=args.get("rows", 24),
          cols=args.get("cols", 80),
      )
      session = mgr.get(session_id)
      time.sleep(0.1)
      initial = session.read_output(timeout=0.5, strip_ansi_flag=True)
      return {
          "session_id": session_id,
          "pid": session.pid,
          "initial_output": initial,
      }

• src/interactive_process_mcp/tools.py:92-101 (registration)

  Registration of 'start_process' (and other tools) as a tuple list returned by create_tools(). The string 'start_process' maps to the start_process closure defined at line 16.

  return [
      ("start_process", start_process),
      ("send_input", send_input),
      ("read_output", read_output),
      ("send_and_read", send_and_read),
      ("list_sessions", list_sessions),
      ("terminate_process", terminate_process),
      ("resize_pty", resize_pty),
      ("get_session_info", get_session_info),
  ]

• src/interactive_process_mcp/server.py:12-12 (registration)

  Registration via the @mcp.tool() decorator on the start_process function in server.py, which registers it with the FastMCP framework.

  @mcp.tool()

• src/interactive_process_mcp/session_manager.py:7-17 (helper)

  SessionManager.create() is the helper method called by both handlers to create and start a new Session, storing it in a thread-safe dict and returning the session ID.

  class SessionManager:
      def __init__(self):
          self._sessions: dict[str, Session] = {}
          self._lock = threading.Lock()
  
      def create(self, command: str, **kwargs) -> str:
          session = Session(command=command, **kwargs)
          session.start()
          with self._lock:
              self._sessions[session.id] = session
          return session.id