Add `readmeUrl` property in the repository

[sandy081]

Add readmeUrl property in the repository to show the details of the mcp server while browsing in the client like below

cc @digitarald

[tadasant]

Makes sense that we would want something like this. I'd define the requirement as "a reference to a URL that provides additional context about the MCP server".

I think we should make this more generic than "readmeUrl". For example, I would want Zapier to list this URL for their server entry.

It also makes me think: can we get rid of the repository.url field if we add this? What's the purpose of the repository URL (if we already have the repository.id)? Previously, I was thinking you might want to "click to read more" by clicking into the repository, but replacing that with a generic descriptionUrl (more generic form of readmeUrl) would keep things simple: only one URL to provide and manage for us. Maybe we just call it url at the server level.

Introducing this does open us up to more spam/security problems (we are not otherwise storing or exposing any free-form URL's). But I think it's probably worth the trade-off.

[sandy081]

Generally, a cautious user would like to go through the repository before installing an extension which shares similar experience with VS Code extensions. I would retain the repo url unless you do not think so,

[tadasant]

Yeah ok fair enough, the notion of source code URL is meaningfully different than Server.url. I'd be ok with keeping Server.repository.url in place alongside adding a new optional Server.url.

[digitarald]

I’d frame the requirement as: "a resource URL that clients can fetch a Markdown document from, which can be previewed within the client (or linked to if direct fetching isn’t possible)."

This approach allows users to view detailed information about the MCP server without leaving the editor. While linking to an external homepage is useful for deeper exploration, not having a dedicated README or similar document limits the amount of information the registry can display directly in the client.

I support keeping repository.url: Open source repositories add value for security and transparency, allowing users to review the source code and verify the provenance of releases.

As for naming, readmeUrl could be generalized to something like learnMore or docs if needed, but referencing a README isn’t too limiting in what users should put in.

[tadasant]

How would we handle versioning alongside guidance to render the markdown like that?

If some MCP client user pins their usage of the com.github/github MCP server to 0.1.5, and GitHub does a major refactor of the server as they go to 1.0.0, including a README overhaul that has drifted very significantly from the early versions, I'm not sure how you could render a README with the appropriate information.

(my alternative pitch would be: in general, we don't advise MCP clients to try rendering rich markdown data. We recommend you just render just the name + description, and otherwise link out for more information)

[tadasant]

I also worry a bit about the spam vector the practice of rendering a whole markdown file can open up. Having a URL field with guidance to render it is basically the same as having an infinite-length free-form input, where someone can stuff as many SEO backlinks, badges, images, etc. as they please.

I don't want to discourage you from doing it if you feel it is the right set of trade-offs for VS Code specifically, but I am hesitant about enshrining the practice as a standard way of doing things.

[connor4312]

How would we handle versioning alongside guidance to render the markdown like that?

How npm and pypi do it is that the readme is that of the latest version of the package, and older versions (which can be specifically requested) always have their individual readme data.

I also worry a bit about the spam vector the practice of rendering a whole markdown file can open up. Having a URL field with guidance to render it is basically the same as having an infinite-length free-form input, where someone can stuff as many SEO backlinks, badges, images, etc. as they please.

I think, as with rendering any external HTML/markdown content, the client should use an appropriate set of sanitizers and validators when building the representation. E.g. links with rel=nofollow to avoid SEO spam and such.

[tadasant]

I think we may start running into this kind of "minimum data" vs. "nice to have data" conflict in a number of places as we consider how various MCP client apps and third party registries might want to present and organize servers.

I was just conversing with @toby on an idea for how to solve this systematically, and maybe this thread is a good first use case (though other active threads would benefit from this as well): can we start splitting the decision of "what data should we have in the official MCP Registry" vs. "what schema should we define so as to empower MCP client apps and marketplaces to stay schema-compliant but surface opinionated data"?

This is similar to how many discussions regarding the MCP specification go. There are many good ideas, but not all of them need to be encoded into the ecosystem-wide standard. MCP solves this by leaving objects open-ended and extensible, so anyone can go ahead and extend it to suit their use cases.

Taking the suggestion for readmeUrl from this lens:

• I view readmeUrl as an opinionated denormalization of repository.url that only makes sense for IDE MCP Clients
• Separately from the idea of a README, I think it would be appropriate to include a generic url field in the top level of the Server shape
• As part of our meta-specification, we make it clear that the Registry API allows for arbitrary additional top level fields on the Server object
• So when VS Code does ETL on the Registry API to populate its "VS Code MCP Marketplace", you can include a step to append a readmeUrl field. Your logic would probably be something like "if Server.url is a markdown file, use that. else if Repository.url is a GH URL, take the root README.md". Adding this field would not break compliance with our spec (nor compatibility with any SDK's or integrations that you may have written to be able to interface with the Registry API)

[jonathanhefner]

This is similar to how many discussions regarding the MCP specification go. There are many good ideas, but not all of them need to be encoded into the ecosystem-wide standard. MCP solves this by leaving objects open-ended and extensible, so anyone can go ahead and extend it to suit their use cases.

• As part of our meta-specification, we make it clear that the Registry API allows for arbitrary additional top level fields on the Server object

I think allowing extension is a good idea, but allowing arbitrary top-level fields could make evolution of the official schema more difficult. If a popular marketplace "claims" a field using a particular format or semantics, there will be friction if we try to add that field to the official schema using a different format.

Instead, we could add something like a Server.vendor object, and restrict extensibility to that.

[tadasant]

Moving this discussion to https://github.com/modelcontextprotocol/registry/issues/81