Proposal: render method for an McpServer

[geelen]

Motivation and Context

Currently, the design of the McpServer makes it easy to define servers whose resources/tools/prompts are static and known ahead of time:

const server = new McpServer({ name: '...', version: '1.0.0' })

// Attach prompts/resources/tools to the server before opening to connections
server.resource(`counter`, `mcp://resource/counter`, (uri) => {
  return { contents: [{ uri: uri.href, text: String(1) }] }
})
server.tool('add', { a: z.number(), b: z.number() }, async ({ a, b }) => ({
  content: [{ type: 'text', text: String(a + b) }],
}))
server.prompt('review-code', { code: z.string() }, ({ code }) => ({
  messages: [{ role: 'user', content: { type: 'text', text: `Please review this code:\n\n${code}` } }],
}))

// Connect to transport
await server.connect(transport)

There's nothing stopping you from adding tools/prompts/resources after connecting, but it also doesn't broadcast list_changed events if you were to do so. So there's not really a good way to make a "dynamic" McpServer without dropping down a level and building your own abstraction using a Server.

I've been looking for a neat API which can make these servers dynamic without needing a complete restructure of the class. This is the best I've come up with: adding the concept of a render function where the output is diffed to the previous version to emit change events:

const server = new McpServer(
  {
    name: '...',
    version: '1.0.0',
  },
  {
    // This function describes the total surface area of the McpServer. 
    // Nothing can be added outside of it
    render: ({ resource, tool, prompt }) => {
      resource(`counter`, `mcp://resource/counter`, /* ... */)
      tool('add', { a: z.number(), b: z.number() }, , /* ... */)
      prompt('review-code', { code: z.string() }, /* ... */)
    },
  },
)

// Call render at least once before connecting
server.render()
// Connect as normal
await server.connect(transport)

// Rerunning render recalculates the whole McpServer, and emits events if anything change
server.render()

As written, the render() function could observe some external state to choose to hide/show/tweak aspects of the server, but I think it makes more sense if render takes an argument:

type RenderArgs = {
  state: 'loading' | 'loaded'
  userTier: 'free' | 'paid'
}

const server = new McpServer<RenderArgs>(
  {
    name: '...',
    version: '1.0.0',
  },
  {
    render: ({ resource, tool, prompt }, args) => {
      prompt('review-code', { code: z.string() }, /* ... */)

      if (args.state === 'loading') return

      resource(`counter`, `mcp://resource/counter`, /* ... */)

      if (args.userTier === 'paid') {
        tool('add', { a: z.number(), b: z.number() }, , /* ... */)
      }
    },
  },
)

server.render({ state: 'loading' })
server.connect(transport)

const user = await loadUser()
// Emits relevant update events automatically
server.render({ state: 'loaded', userTier: user.tier })

This feels like the most natural way to take the current API and make it dynamic, though there's plenty of alternatives.

Anyway, I thought I'd raise this as a draft PR to see if there was any interest in the API itself, before I finish it off. Currently it needs a smarter diffing algorithm (currently only looks for things being added/removed, but a change of description should probably fire an event too), as well as some tests.

How Has This Been Tested?

Draft PR, untested as yet

Breaking Changes

None

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

[irvinebroque]

So React-y with render!

[jspahrsummers]

I think something like this has potential, but IMO there's a bit of an impedance mismatch between the render/React style of doing things and the "Express-style" API we have here.

There was some exploration of a "JSX for MCP servers" which maybe would fit more naturally, but folks might have allergic reaction to that.

Note also that it is possible to add everything with the higher-level API right now, and then emit list_changed events directly using the underlying Server—nothing prohibits calling those in combination.

[geelen]

Oh I missed #116 entirely! Thanks for the link, I will continue the discussion tehre. I think it makes sense to break this PR into two pieces then.

First:

• Make .tool(), .resource() and .prompt() automatically emit list changed events if their transport is connected (this feels like a good default).
• Add remove[Tool|Resource|Prompt]() methods (as well as update methods?), otherwise you have no way of changing/removing something after its set. We could instead change the .tool et al method to allow overwriting or passing null as an argument to delete but I feel like an explicit API makes more sense. Emit list changed events as appropriate here too.

Then, in a follow-up PR, use these new primitives to build a ReactiveMcpServer class that manages an internal McpServer and adds this render()-style method, potentially with a JSX version too.

[geelen]

Step one complete, PR is ready for review: #247

Will update this PR once I have time and mark it as non-draft when it's worth you taking another look @jspahrsummers