feat: add embeddedResourceProps for annotations

[liady]

Description

This PR addresses #98, by adding an embeddedResourceProps optional key to createUIResource(), which is being spread to the top-level of the created embedded resource.
This allows the consumer to define annotations, for example, on the top level - which matches the spec - https://modelcontextprotocol.io/specification/2025-06-18/schema#embeddedresource.

Usage

This kind of function call:

const resource = createUIResource({
  uri: 'ui://test-url' as const,
  content: { type: 'externalUrl', iframeUrl: 'https://example.com' },
  encoding: 'text' as const,

  // resource level metadata and props, as before
  uiMetadata: { 'preferred-frame-size': ['100px', '100px']},
  metadata: { 'arbitrary-metadata': 'some-resource-level-metadata' },
  resourceProps: { 'other-prop': 'resource-level-prop' },

  // (NEW) embedded resource top-level props
  embeddedResourceProps: {
    annotations: {
      audience: ['user'],
    },
  },
});

will generate:

{
  type: 'resource',
  resource: {
    uri: 'ui://test-url',
    mimeType: 'text/uri-list',
    text: 'https://example.com',
    // resource level metadata, as before
    _meta: {
      'arbitrary-metadata': 'some-resource-level-metadata',
      'ui-preferred-frame-size': ['100px', '100px'],
    },
   'other-prop': 'resource-level-prop',
  },
  // embedded resource (top-level) annotations
  annotations: {
    audience: ['user'],
  },
}

[cloudflare-workers-and-pages]

Deploying mcp-ui with    Cloudflare Pages

Latest commit:	44c1437
Status:	✅  Deploy successful!
Preview URL:	https://63ef5fa0.mcp-ui.pages.dev
Branch Preview URL:	https://feat-embedded-resource-props.mcp-ui.pages.dev

View logs

[aharvard]

Oh, this reminds me... can you double-check that the client package getUIResourceMetadata() is extracting properties correctly? I saw some TS errors, but did not have time to dig in.

[aharvard]

I have a nit about naming:

• uiMetadata
• metadata
• resourceProps
• embeddedResourceProps

I am confused about which to use for what. I recall we had some discussion around reserved properties and arbitrary properties. I think we still need that! But, I wonder if it would be clearer to have literal properties for _meta and annotations... then keep uiMetadata as is or maybe name it something close.

[liady]

Yes, so:

Metadata handling
uiMetadata - reserved for mcp-ui props
metadata - populates the _meta property on the resource (for any other arbitraray metadata)

Props handling
resourceProps - are being spread as-is on the resource level
embeddedResourceProps - are being spread as-is on the embedded resource level (top-level) - good for annotations

Note: In general - resourceProps shouldn't be used for _meta at all

[aharvard]

Gotcha. This explanation helps. Please don't over-index on my personal preference; we might want to open this up to the community for other opinions. But I do feel like the current approach is hard to understand and easy to get them mixed up.

I did not realize there is a distinction between "resource" and "embedded resource" from a tool response POV. I thought that tools return embedded resources, not resources.

I think it could be simpler if we avoided specific terms and conformed to the MCP spec. So I am curious to learn if there are any reasons why we might not be able to simplify down to two properties.

createUIResource({
  ...
  _meta: {
    // users may use the reserved keys
    // or supply their own properties
    // automatically placed at the top-level for mental-model alignment with annotations 
  }
  annotations: {
    // MCP compliant and is automatically placed at the expected top-level
  }
}

The TL;DR is

1. Use _meta and parse for reserved keys
2. support annotations as opposed to being open-ended on resourceProps and embeddedResourceProps
3. extract key/value pairs and place on top-level of the raw response object

[liady]

Note that according to the spec there are two _meta fields - one on the embedded resource (top level), and one on the actual resource.
mcp-ui "cares" only about the one on the inner resource (and not on the top level), since this is what's being passed to it, and this is where the actual UI definitions lie.
So the uiMetadata should be there (on the inner resource _meta field)

However the annotations field is on the top level. So we have to make a distinction between the top level props and the inner resource props.

[aharvard]

That's a good point. Would you entertain the idea of renaming the properties for metadata to better align with the mental model of resourceProps and embeddedResourceProps? I think I have these conversions right:

1. top level: metadata could become embeddedResourceMeta
2. resource level: uiMetadata could become resourceMeta

So if a server author wants to define stuff at the top level, they can use:

• embeddedResourceMeta
• embeddedResourceProps

And if they want to define stuff at the resources level, they can use:

• resourceMeta
• resourceProps

[liady]

@aharvard maybe we'll open an issue with this proposal? We should probably consider this for the next major

[liady]

@aharvard about getUIResourceMetadata - are you passing it the whole embedded resource or just the actual resource?

✅ This is correct (passing only the resource, the same object which you pass to <UIResourceRenderer />):

getUIResourceMetadata({
  uri: 'ui://example/demo',
  mimeType: 'text/html',
  text: '<div>Hello</div>',
  _meta: {
    'mcpui.dev/ui-preferred-frame-size': ['800px', '600px'],
    author: 'Development Team'
  }
})

❌ This is incorrect (passing the whole embedded resource):

getUIResourceMetadata({ // wrong, should pass only the resource
  type: 'resource',
  resource: {
    uri: 'ui://example/demo',
    mimeType: 'text/html',
    text: '<div>Hello</div>',
    _meta: {
      'mcpui.dev/ui-preferred-frame-size': ['800px', '600px'],
      author: 'Development Team'
    }
  }
})

If you feel that passing it the entire embedded resource makes sense, let me know. Since the actualResource object is the only thing UIResourceRenderer "cares" about, then getUIResourceMetadata() also expects to receive this object.

We can also open a spearate ticket for this discussion.

[aharvard]

are you passing it the whole embedded resource or just the actual resource?

@liady, oh! I am passing the WHOLE resource! I think that's because I got used to passing the whole thing for the resource prop.

Currently working on a PoC outside of Goose and have this code:

I could destructure and pass just the resource but that does not feel very ergonomic... my mental model to simply deal with the top-level content item in the model message parts.

[liady]

@aharvard you should pass to getUIResourceMetadata() exactly what you pass to UIResourceRenderer - so c.resource in your case is indeed the correct argument. I wonder which TS errors do you see?

[aharvard]

My apologies, you are right! Let's table this for now, and I can open another issue when/if I see the errors again. My current hunch about the errors I saw is that they are due to user error.

[liady]

Merging this for now, since the key names change will require a breaking change (so we should consider them for the next major)