[MCP Apps] Update viewport type

[martinalong]

Motivation and Context

• Host passing viewport.width and viewport.maxWidth were unnecessary because the width of the app always needs to be 100%
• Host passing viewport.height is unnecessary because the app decides the height
• So all we really need is viewport.maxHeight. Thus, viewport has been simplified to just maxHeight
• As a result, onsizechange can also be updated to onheightchange since we don't do anything with the width change notifications

How Has This Been Tested?

Manually tested with examples

Breaking Changes

Yes, any users using the viewport property will have to update their behavior

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@153

commit: dc226be

[ochafik]

@claude please review this PR in depth, and give your assessment / recommendations wrt/ backwards compatibility

[jonathanhefner]

Agreed this makes much more sense. It makes it easier for MCP Apps to determine their dimensions because one dimension is essentially fixed, and it simplifies the responsibilities of the host application.

[liady]

Yes - we also discussed this earlier in the SEP process, since ChatGPT Apps and MCP-UI were treating this question in different ways.
Eventually it should be very similar to a web page - the host effectively sets the width (and I agree it doesn't have to be communicated to the iframe) - and the UI just responds to it responsively. The UI should be able to dynamically set the outer height, since this is usually the dynamic dimension.

Two points here:

1. We might have different display modes in the future where the dynamic dimension is the width and not necessarily just the height. It might be a good idea to keep the size change event generic in that sense.
2. I agree that when the UI runs in an iframe it can check and be responsive to its dimensions by itself (using media queries or js) so there's no need to communicate the size from the outside. However we just need to remember that this is true as long as it runs inside a web iframe. Again - since this is our only render target right now it's not an issue right.

[martinalong]

@liady for both of those two points, can you give some specific examples where those would be true? I'm having a hard time imagining a situation for both of these

Also for 2, what are you saying is the implication of that? And what is the way that we would account for that future?

[liady]

@martinalong for #1 there are several use cases like rendering the UI in a modal (where it can dynamically expand vertically and horizontally), or in a sidebar where it can affect the width, etc. Since we're not targeting only inlined UIs inside chats - and perhaps more display modes in the future - the horizontal axis size changes inside the UI might still be relevant.

For #2 - there is no concrete example other than rendering the UI not inside an iframe (for example inside a modal that's not an iframe). In that case media queries / js apis won't work. However that's not something we currently allow in the SEP, so it's not an issue. If we'll add render targets that are not web iframes, we can re-introduce passing the host's dimensions in the future.

[martinalong]

@antonpk1 expressed concern over DM about potentially breaking existing WIP apps by updating onsizechange -> onheightchange, so I've reverted that back.

Coincidentally this should also address point 1 that you raised @liady !

[martinalong]

there are several use cases like rendering the UI in a modal (where it can dynamically expand vertically and horizontally), or in a sidebar where it can affect the width, etc. Since we're not targeting only inlined UIs inside chats - and perhaps more display modes in the future - the horizontal axis size changes inside the UI might still be relevant.

Ahh I see what you mean. Like basically any view where the app doesn't have to take up the full width.

Hmm yeah, I was trying to match the OpenAI spec here which just passes maxHeight alone, but I don't think it'll extend well to use cases that. B/c right now, undefined maxHeight = unlimited height in OpenAI's implementation. But maxWidth (by nature of not existing yet) is effectively undefined. Yet undefined in that case means something different: that there is indeed a maxWidth and the app needs to take up the full width available.

We should probably go back to passing viewport for the sake of future extensibility. Let me know if you are on board with this slight update to the type of viewport, and outline of how it would work @liady :

type Viewport = ({ height: number } | { maxHeight?: number }) &
({ width: number } | { maxWidth?: number });

The viewport has two independent dimension pairs:

• Height: Either height (fixed) or maxHeight (flexible), never both
• Width: Either width (fixed) or maxWidth (flexible), never both

These pairs are independent—you can have a fixed height with flexible width, or any other combination.

• Fixed dimensions (height/width): The host controls the size. Set height: 100% (recommended) or use the pixel value directly.
• Flexible dimensions (maxHeight/maxWidth or undefined): The app controls the size, up to the max if specified. If undefined, there is no limit.

Example usage:

if ("height" in hostContext.viewport) { body.style.height = "100%"; } else if (hostContext.viewport.maxHeight) { body.style.maxHeight = `${hostContext.viewport.maxHeight}px`; } // ...and repeat the same for width and maxWidth

For #2 - there is no concrete example other than rendering the UI not inside an iframe (for example inside a modal that's not an iframe). In that case media queries / js apis won't work.

Oh I was imagining apps would be measuring "full width" through just width: 100%, which should still work in that case?

[liady]

@martinalong sounds good, just few points:

• We have the container measurements (height/width) that the host (always) sets - since it's an iframe. They can decide to change it when the inner app size changes (by listening to events), or to keep it fixed.
• The inner app should:
  • Know what the outer dimensions are (for responsive design purposes, media queries, js api, etc)
  • Know when a dimension is fixed and when it can change it, and up to which size.
  • Decide when an inner dimension change requires an outer dimension change, and when not (for example a hortizontal scroll bar in a carousel view is ok)

So for our purposes I think:

• The host should communicate height/width/maxHeight/maxWidth - I think it's ok that they'll be exclusive like you proposed
• These should be constantly updated by the host - so for example if the host changed the iframe fixed dimensions (for any reason) it should (imo) communicate it to the app.
• We should keep it onsizechange and not just onheightchange - since both dimensions can be relevant (even if for now it's mostly the vertical dimension).

Oh I was imagining apps would be measuring "full width" through just width: 100%, which should still work in that case?
There are several mechanisms for responsive design (for example media queries according to the window size or container size) - so a lot of the time it's not just about setting the width, but also responding to the dimensions and changing the entire style according to the size of the app.

So all in all I think that keeping onsizechange and having the Viewport defining dim/maxDim like you proposed (so that the apps will know what they can control and what is fixed) - is flexible enough for our use cases.

[idosal]

Thanks @martinalong!
I agree with @liady's take. It's critical that the spec remains extensible and accounts for different hosts.

[martinalong]

Yep what you said is my understanding of it as well! I'll make the updates

[martinalong]

PTAL @liady@idosal!

[liady]

Not sure we need to add reference implementations here, or just let apps handle it their own way like they handle any browser window. (some apps might want scrolling content like a scrolling carousel).
If we do want - we should make some adjustments -

1. Use document.documentElement everywhere instead of document.body - since this is the element that actually takes the iframe size. It also fixes issues if the HTML has paddings, the body has margins, etc.
2. Use vh/vw units since for the app the iframe is the actual viewport
3. Clarify why we're limiting the app size - if we need the app to at least fill the container it might need to be style.minHeight/minWidth. If we want to force the app to have fixed size no matter what then .width is ok.
   Again - we can also leave it to the internal implementation of the app.

[martinalong]

some apps might want scrolling content like a scrolling carousel

I think it's informative to have an example, even if that example doesn't cover all the ways you can use it!

But overall 1 and 2 sound good to me! Will update

On the topic of minHeight: height/maxHeight to refer to the iframe height, not the app height. Apps can do whatever they want within that height (scroll or not)

[martinalong]

@ochafik I realized that no matter what, we have to make this change (making these fields optional), which is is a minor breaking change

I don't think there's really a way around it if we want to adopt this new shape. Wdyt should be the plan here? I think we may as well just update it to the type i originally proposed and announce the next version will be a breaking change

[martinalong]

@idosal@liady@ochafik ready for review!

We made some final edits. @ochafik and I chatted and landed on this new approach. There are now two properties:

• containerDimensions which represents the dimensions (or maximum dimensions) of the container (the iframe or div) holding the app
  • This is the parameter that apps will use in determining their own size
• viewport, which represents the host's window.innerWidth and window.innerHeight
  • This is more of a "nice to have" that provides additional information that apps can use to make responsive layout decisions

Now, this is no longer a breaking change (since the only values being removed, viewport.maxHeight and viewport.maxWidth, were already optional)

Lmk your thoughts! My personal opinion is that we could do without viewport and be fine b/c:

• Knowing mobile vs desktop already provides a good amount of information about the likely screen size.
• Plus, viewport isn't a perfect measurement of the available height/width because the app likely doesn't get to use all of that viewport.

[liady]

@martinalong sounds good. While apps are able to respond to their sizes inside iframes even without outside information (they can just measure it or use media queries) - containerDimensions is a good future proofing since it'll allow apps to render in divs and not rely on them being in iframes.
Still I imagine that apps that would want to be fully responsive would use container/media queries in the CSS, but it's good to have this information sent in containerDimensions as well.
As for the general host's viewport - I agree that it doesn't hold a lot of added value since apps need to respond to their container size regardless of the window size.
There could be edge cases of breakpoints synchronization, I can see edge cases where the host is already in a "mobile" breakpoint but the app is still displaying a "desktop-like" UI or vise versa - but I don't think it's for us to solve. The app should respond only to its container size.
I'm not sure we need to send the host's viewport since it can get complicated - for example if the host is a slim chat sidebar, but the app is opened in a modal, what is the correct host's viewport size in this case?
I'd recommend we'll stay only with containerDimensions for the immediate styling needs. Unless there's a concrete use case for viewport I'm missing?

[martinalong]

@liady We're adding containerDimensions because measuring the iframe dimensions wouldn't work in the cases where we size the iframe to fit their size (like in the case of height in the inline displayMode). In that case, we would pass maxHeight (to indicate that height is determined by the app's height) as opposed to height (which indicates that height is fixed)

And I'm in agreement that we don't need viewport, but I added it anyways b/c that is the shape that @ochafik and I settled on during our last convo. If @ochafik is ok with removing viewport, we can just remove it!

[liady]

@martinalong exactly, as we discussed in previous conversations - the horizontal axis is usually fixed and the one that's used for responsive design, whereas the vertical axis is the dynamic one and changes with content changes. I believe these will be most of the cases.
Since the iframe is the "window" from the app's perspective, all responsive design methods should work "out of the box" even without containerDimensions. However it's good to pass it anyway since it signals the app which axes are fixed and which can be dynamic from the host's perspective.
@ochafik as for viewport - we can include it but see the possible edge cases in my precious comment - perhaps if it doesn't add any value it would just be an additional complication for the hosts to determine.

[idosal]

Thanks @martinalong!
It seems that containerDimensions fills the use case that viewport was designed for. If we don't have a concrete use case for viewport as an additional field, then I think we should omit it from the MVP.

[martinalong]

Ok sounds like we're all in agreement then. I've removed viewport! @ochafik basically it's the approach I outlined earlier, except we're deprecating viewport and using containerDimensions instead. That shouldn't be a breaking change right? Since viewport was always optional?

[ochafik]

@infoxicator here's the breaking change :-)

[chelojimenez]

Thanks for merging! @ochafik when is this expected to be published to npm?