Repository navigation
Big docs tidy up in preparation for launch - #364
Conversation
🏠 Remote-Dev: homespace
🏠 Remote-Dev: homespace
|
@claude please review |
|
Claude finished @domdomegg's task —— View job Documentation Reorganization ReviewThis is a comprehensive documentation restructuring that significantly improves organization and usability. Overall strongly approve with minor suggestions below. Detailed Review✅ Excellent Structural ImprovementsDiátaxis Framework Adoption: The new structure properly follows the Diátaxis documentation framework:
Logical Information Architecture: The "I want to..." approach in Content Consolidation: Merging tutorials and guides was the right call - the registry is indeed more of an occasional-use tool than a learnable skill requiring separate tutorial paths. ✅ Strong Content QualityNew Content Additions:
Content Depth: The explanations section properly separates conceptual understanding from task execution, making complex topics like namespacing and ecosystem vision more accessible. ✅ Clean Migration ExecutionFile Organization:
Link Updates: Cross-references appear properly updated with relative paths that maintain structure (e.g., 🔍 Minor Suggestions
✅ Technical ImplementationIntegration Updates: Tool validation scripts properly updated ( Test Compatibility: Integration tests maintained compatibility with restructured content. SummaryThis reorganization transforms scattered documentation into a coherent, user-friendly knowledge base. The Diátaxis framework application is textbook-perfect, and the new content fills important gaps (especially around CI/CD and ecosystem understanding). The migration execution is clean with proper link updates and no apparent broken references. Recommendation: Approve and merge. This sets an excellent foundation for launch documentation. |
|
Requesting review from @tadasant or @rdimitrov :) |
|
|
||
| This document describes the technical architecture of the MCP Registry, including system components, deployment strategies, and data flows. | ||
|
|
||
| ## System Overview | ||
|
|
||
| The MCP Registry is designed as a lightweight metadata service that bridges MCP server creators with consumers (MCP clients and aggregators). | ||
|
|
||
| ```mermaid |
There was a problem hiding this comment.
Deleted this because it's covered in ecosystem-vision already
| @@ -1,51 +0,0 @@ | |||
| { | |||
There was a problem hiding this comment.
Deleted as already covered by our docs + schemas at https://registry.modelcontextprotocol.io/docs
| @@ -1,34 +0,0 @@ | |||
| # Repository References in server.json | |||
There was a problem hiding this comment.
moved inline into schema definitions
- Resolved conflicts in generic-server-json.md by merging new examples - Updated validation tool to expect 12 examples instead of 10 - Enhanced repository field descriptions in server.schema.json with detailed explanations - Integrated repository_references.md content into schema documentation - Added comprehensive descriptions for repository.id field including GitHub CLI command :house: Remote-Dev: homespace
b4d1626 to
7232527
Compare
rdimitrov
left a comment
rdimitrov
left a comment
There was a problem hiding this comment.
+1 👍 That's quite a nice improvement on the docs 💯
| - **`GET /v0/servers`** - List all servers with pagination | ||
| - **`GET /v0/servers/{id}`** - Get full server details including packages and configuration |
There was a problem hiding this comment.
Should we cover the publish endpoint too (maybe not here, perhaps in the guide for publishing a server)?
There was a problem hiding this comment.
I think in this file we can focus on the read-only endpoints. But making sure it's covered somewhere is good: this is covered in reference.
| # Build publisher from source (requires Go) | ||
| git clone https://github.com/modelcontextprotocol/registry publisher-repo | ||
| cd publisher-repo | ||
| make publisher | ||
| cp cmd/publisher/bin/mcp-publisher ../mcp-publisher | ||
| cd .. | ||
| chmod +x mcp-publisher |
There was a problem hiding this comment.
For future: This can be either packaged as a github action or have a curl one liner script that installs it
There was a problem hiding this comment.
Yeah, once #358 is sorted we should update this :)
3 participants
Motivation and Context
Docs currently don't have very clear organisation, and don't explain core flows.
This fixes #89 (although we still might want to push these to
https://modelcontextprotocol.io/docs/), based on the plan there.One minor change from that plan is that I merged tutorials and guides, because they ended up basically being duplicates which I thought would be annoying for us to keep in sync. Additionally in the Diátaxis framework, tutorials and guides are separated by whether they are focused on acquisition of skills (e.g. in a learning environment) or application of skills (e.g. in a work environment). I expect the registry to be something that will be used occasionally in a work environment, rather than a fundamental 'learnable' skill so I think it's reasonable not to have tutorials and fold these into guides.
How Has This Been Tested?
npx markdown-link-check .to check all the links workBreaking Changes
Links to old docs will break, but I don't think there are any. All internal links have been checked and updated.
Types of changes