Add docs: design principles, FAQ, roadmap, architecture #134
Conversation
|
|
||
| ### Is open source required? | ||
|
|
||
| Locally-run servers are required to be open source. Remote servers are not. |
There was a problem hiding this comment.
Is this actually the case? I could easily publish an npm package containing a closed-source binary.
There was a problem hiding this comment.
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.
Co-authored-by: Connor Peet <[email protected]>
|
|
||
| ## 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. |
There was a problem hiding this comment.
Pursuant to #134 (comment), you might want to omit "open source" here as well.
|
|
||
| ### How do I update my server metadata? | ||
|
|
||
| Submit a new `server.json` with an incremented version number. Once published, version metadata is immutable (similar to npm). |
There was a problem hiding this comment.
Is there any place that we specify the version number format? For example, would we support "1.0.0-alpha" => "1.0.0-beta"?
There was a problem hiding this comment.
I had assumed SemVer, but this is a nuanced problem. I imagine folks will want to use the same version string as the underlying package for simplicity. And there is no guarantee of a unified version model for N package ecosystems. For example NuGet is SemVer-ish with case insensitive and a 4th version digit supported.
Perhaps complaint SemVer 2.0.0 for MCP Registry, and build metadata rejected? (1.0.0-alpha but not 1.0.0-alpha+foo which SemVer 2.0.0 supports but adds complexity).
| ### What about typosquatting? | ||
|
|
||
| The registry implements: | ||
| - Automatic blocking of names within a certain edit distance of existing servers |
There was a problem hiding this comment.
Is this planned for the initial release? (#103 is labeled as "not go-live blocker".)
|
|
||
| ## Non-Goals / Out of Scope | ||
|
|
||
| These items are explicitly not planned: | ||
|
|
There was a problem hiding this comment.
Is this section an editing artifact, or is it WIP?
|
|
||
| ## Contributing | ||
|
|
||
| See [../CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to the MCP Registry project. |
There was a problem hiding this comment.
Not sure about the path to CONTRIBUTING.md in the final rendered version of this document, but perhaps:
| See [../CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to the MCP Registry project. | |
| See [CONTRIBUTING.md](../CONTRIBUTING.md) for details on how to contribute to the MCP Registry project. |
Co-authored-by: Jonathan Hefner <[email protected]>
Co-authored-by: Jonathan Hefner <[email protected]>
| - 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 |
There was a problem hiding this comment.
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.
| ### How is spam prevented? | ||
|
|
||
| - GitHub authentication requirement | ||
| - Rate limiting (e.g., one new server per user per day) |
There was a problem hiding this comment.
We'll probably want a bit higher of a limit. I could imagine a company publishing at least a few servers in day.
| ### How often should I poll the registry? | ||
|
|
||
| Recommended polling frequency: | ||
| - `/servers` endpoint: once per day |
There was a problem hiding this comment.
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.
|
|
||
| ### What's the expected reliability? | ||
|
|
||
| - 24-hour+ downtime tolerance is acceptable, so you shouldn't rely on the registry being always available. |
There was a problem hiding this comment.
Same as above re: trying to improve this for the benefit of publishers.
|
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. |
Adding more up-to-date documentation to address #131:
This PR adds:
design_principles.md- Core constraints and principles guiding the registry designfaq.md- Frequently asked questions about the MCP Registryroadmap.md- High-level roadmap for the MCP Registry developmentarchitecture.md- Technical architecture, deployment strategies, and data flows