Add docs: design principles, FAQ, roadmap, architecture #134

tadasant · 2025-06-12T17:34:45Z

Adding more up-to-date documentation to address #131:

We are starting to get a lot of repeat questions that we have answers to scattered throughout docs and issues. The designs in the #11 are starting to grow stale, so we should have a better running document somewhere in version control.

This PR adds:

design_principles.md - Core constraints and principles guiding the registry design
faq.md - Frequently asked questions about the MCP Registry
roadmap.md - High-level roadmap for the MCP Registry development
architecture.md - Technical architecture, deployment strategies, and data flows

connor4312 · 2025-06-12T17:46:59Z

docs/faq.md

+
+### Is open source required?
+
+Locally-run servers are required to be open source. Remote servers are not.


Is this actually the case? I could easily publish an npm package containing a closed-source binary.

Good point, you're right, we don't have a reasonable means to enforce that. Will rephrase such that open source is encouraged but not required.

docs/roadmap.md

Co-authored-by: Connor Peet <[email protected]>

jonathanhefner

This looks great! Very helpful to someone who hasn't closely followed all of the discussions. 😅

docs/architecture.md

jonathanhefner · 2025-06-13T14:47:52Z

docs/design_principles.md

+
+## 1. Single Source of Truth
+
+The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run (open source) and remote (open or closed source). Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.


Pursuant to #134 (comment), you might want to omit "open source" here as well.

docs/faq.md

jonathanhefner · 2025-06-13T15:09:38Z

docs/roadmap.md

+
+## Non-Goals / Out of Scope
+
+These items are explicitly not planned:
+


Is this section an editing artifact, or is it WIP?

Oops, just a typo, thanks.

docs/roadmap.md

Co-authored-by: Jonathan Hefner <[email protected]>

toby · 2025-06-13T23:01:36Z

docs/design_principles.md

+- Design for low maintenance and operational overhead
+- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI for packages)
+- Avoid features that require constant human intervention or moderation
+- Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users


I think it's good to encourage caching of data but I'm hoping we can have a better SLA than 24 hours of downtime since publishers won't be able to publish new servers during that time.

My biggest concern about sub-24h is that anything under 24h necessitates on on-call schedule. If we frame it as 24h, then we can rely on volunteers coming online once a day.

I know it's not great for productivity if publication is offline for 24h, but maybe we start with a 24h SLA and once we get a sense for adoption + other maintenance needs, we could then seek to create a permanent operational position that is funded/sponsored by someone?

toby · 2025-06-13T23:03:59Z

docs/faq.md

+### How is spam prevented?
+
+- GitHub authentication requirement
+- Rate limiting (e.g., one new server per user per day)


We'll probably want a bit higher of a limit. I could imagine a company publishing at least a few servers in day.

Fair, if we make it 10/day that probably does enough to still discourage mass spam and likely won't severely impact a company trying to launch a set of servers.

Noted here #21 too

toby · 2025-06-13T23:04:46Z

docs/faq.md

+### How often should I poll the registry?
+
+Recommended polling frequency:
+- `/servers` endpoint: once per day


We can probably go a bit higher too. Since there won't be millions of registries, I'd say maybe once an hour? We can cache on our end as well.

That's fair, I think once per hour would be fine

toby · 2025-06-13T23:05:22Z

docs/faq.md

+
+### What's the expected reliability?
+
+- 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available.


Same as above re: trying to improve this for the benefit of publishers.

To discuss in https://github.com/modelcontextprotocol/registry/pull/134/files#r2146246641

tadasant · 2025-06-13T23:23:53Z

Thanks for the feedback everyone! I'm about to head out for a week of OOO, so will be circling back to address when I'm back.

patrick-rodgers · 2025-06-19T20:15:58Z

docs/design_principles.md

+- Avoid features that require constant human intervention or moderation
+- Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users
+
+## 3. Vendor Neutrality


No interest in blocking anyone from building and publishing a server - but say we released an in-service MCP server for OneDrive, how would that be differentiated from the 100 other implementation that have OneDrive in the name/description/access OD files? Substitute OneDrive for GDrive or any other service. This is the app store problem of a bunch of very similar things being very confusing for users.

Say I am a consumer, I know nothing of tech, and I search for "OneDrive" in MCP registry and get 100 results - how would I make a choice?

I think that amounts to a curation problem, which would be the purview of aggregators rather than the registry itself. We do plan to track download counts (#95), so perhaps aggregators could sort by those numbers. Aggregators can also implement their own ratings systems to recommend the most popular (and presumably official) servers. And I suppose paid placement is another option. 💀

(I am not on the registry team, just focused on it because I'm lighting up NuGet based MCP servers)
Agreed that this mostly goes to the clients that read the data and "project" the data into whatever UX they want.
Additionally, the server name is a reverse DNS name so the official OneDrive MCP server could perhaps have a name like com.microsoft.onedrive/mcp or something like that. This would mean that the owner of microsoft.com is publishing this OneDrive MCP server. I am not sure when non-GitHub package names will come in. Maybe for the first release per #100.

Then from the registry standpoint the plan is to externalize the risk.

It would be worth thinking through the implications of that approach, where without some indicator of official releases the consumer (think non-tech person - what's DNS? what's a github package?) is potentially placing their content at risk.

Anyone should be able to build/publish servers, while also having a way to mark official releases would be nice.

Anyone should be able to build/publish servers, while also having a way to mark official releases would be nice.

How would the registry determine which packages are official and which are not? How would disputes be handled?

npm has the organization model, which isn't flawless but groups things in a user understandable way.

Say I am a consumer, I know nothing of tech, and I search for "OneDrive" in MCP registry and get 100 results - how would I make a choice? ... (think non-tech person - what's DNS? what's a github package?) is potentially placing their content at risk.

I don't expect consumers to use the Registry API. They should only interface with MCP clients and their Registry mirrors, which they are responsible for augmenting and curating to the level of sophistication that matches their target persona. I don't think we can solve trust at the right level of granularity for all MCP uses through to the end-consumers, so the only scaleable way to approach this is to federate out to the clients, who own the end-user UI's and can present them as they see fit (after augmenting them with their own notions of trust and curation/filtering).

Co-authored-by: Jonathan Hefner <[email protected]>

tadasant · 2025-06-25T21:40:20Z

Sorry for the long delay while I was OOO, back on now.

I took a pass at addressing comments. The only notable sticking point is the SLA @toby. Happy to continue discussing if we're still not aligned, maybe we land this PR and carve that out to discuss separately?

tadasant added 2 commits June 12, 2025 10:30

Docs

de19891

Add more links

c4df27a

tadasant requested review from toby, alexhancock and connor4312 June 12, 2025 17:34

connor4312 reviewed Jun 12, 2025

View reviewed changes

docs/roadmap.md Outdated Show resolved Hide resolved

tadasant mentioned this pull request Jun 13, 2025

Server Detail should provide a well-defined method to automate server execution #123

Open

Update docs/roadmap.md

03ee012

Co-authored-by: Connor Peet <[email protected]>

jonathanhefner reviewed Jun 13, 2025

View reviewed changes

toby and others added 2 commits June 13, 2025 16:59

Apply suggestion from @jonathanhefner

8a3f97a

Co-authored-by: Jonathan Hefner <[email protected]>

Apply suggestion from @jonathanhefner

98566f7

Co-authored-by: Jonathan Hefner <[email protected]>

toby reviewed Jun 13, 2025

View reviewed changes

patrick-rodgers reviewed Jun 19, 2025

View reviewed changes

tadasant and others added 7 commits June 25, 2025 14:18

Update docs/roadmap.md

aa2053f

Co-authored-by: Jonathan Hefner <[email protected]>

Open source

f356eda

Open source FAQ

1eed56b

Typosquatting

ecdcce4

10/day

060cfe7

Per hour

81da0ab

Rogue section

9ff5378

tadasant requested review from toby, jonathanhefner, connor4312 and joelverhagen June 25, 2025 21:39

jonathanhefner approved these changes Jun 25, 2025

View reviewed changes


		### Is open source required?

		Locally-run servers are required to be open source. Remote servers are not.


		## 1. Single Source of Truth

		The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run (open source) and remote (open or closed source). Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.


		## Non-Goals / Out of Scope

		These items are explicitly not planned:


		### What's the expected reliability?

		- 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available.

Add docs: design principles, FAQ, roadmap, architecture #134

Are you sure you want to change the base?

Add docs: design principles, FAQ, roadmap, architecture #134

Conversation

tadasant commented Jun 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tadasant Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tadasant commented Jun 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tadasant commented Jun 25, 2025

Uh oh!

Uh oh!

tadasant Jun 25, 2025 •

edited

Loading