Terminal Control MCP

Instructions

Implementation Reference

• src/terminal_control_mcp/server.py:97-127 (handler)

  The handler function decorated with @mcp.tool(), implementing the terminal_capture tool. It retrieves the XTermSession for the given session_id, calls capture_screenshot() on it, and returns the base64 image data and metadata.

  @mcp.tool()
  async def terminal_capture(session_id: str) -> Dict[str, Any]:
      """Capture terminal screen as PNG screenshot
  
      Args:
          session_id: ID of the terminal session
  
      Returns:
          Dictionary with base64-encoded PNG image and metadata
      """
      if session_id not in sessions:
          return {"status": "error", "error": f"Session {session_id} not found"}
  
      session = sessions[session_id]
  
      try:
          screenshot_data = await session.capture_screenshot()
  
          logger.info(f"Captured screenshot for session {session_id}")
          return {
              "session_id": session_id,
              "status": "captured",
              "image_data": screenshot_data["image_data"],
              "metadata": screenshot_data["metadata"],
          }
  
      except Exception as e:
          logger.error(
              f"Failed to capture screenshot for session {session_id}: {e}"
          )
          return {"status": "error", "error": str(e)}

• src/terminal_control_mcp/server.py:97-97 (registration)

  The @mcp.tool() decorator registers the terminal_capture function as an MCP tool.

  @mcp.tool()

• src/terminal_control_mcp/server.py:99-105 (schema)

  Docstring defining the input schema (session_id: str) and output schema (dict with session_id, status, image_data, metadata).

  """Capture terminal screen as PNG screenshot
  
  Args:
      session_id: ID of the terminal session
  
  Returns:
      Dictionary with base64-encoded PNG image and metadata