Skip to content

Commit a2d06ec

Browse files
sridharavinashsridharavinash
authored
Merge branch 'main' into bug/docker-compose--links-deprecated-#107
2 parents e574a79 + 81e5174 commit a2d06ec

File tree

11 files changed

+1580
-11
lines changed

11 files changed

+1580
-11
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,4 @@ build/*
44
.mcpregistry*
55
**/bin
66
cmd/registry/registry
7+
publisher

‎docs/README.md‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# Official Registry Documentation
22

3+
## Project Documentation
4+
5+
[`design_principles.md`](./design_principles.md) - Core constraints and principles guiding the registry design
6+
7+
[`faq.md`](./faq.md) - Frequently asked questions about the MCP Registry
8+
9+
[`roadmap.md`](./roadmap.md) - High-level roadmap for the MCP Registry development
10+
11+
[`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
12+
13+
## API & Technical Specifications
14+
315
[`openapi.yaml`](./openapi.yaml) - OpenAPI specification for the official registry API
16+
417
[`api_examples.md`](./api_examples.md) - Examples of what data will actually look like coming from the official registry API
5-
[`MCP Developers Summit 2025 - Registry Talk Slides.pdf`](./MCP%20Developers%20Summit%202025%20-%20Registry%20Talk%20Slides.pdf) - Slides from a talk given at the MCP Developers Summit on May 23, 2025, with an up-to-date vision of how we are thinking about the official registry.
18+
19+
[`architecture.md`](./architecture.md) - Technical architecture, deployment strategies, and data flows

‎docs/architecture.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# MCP Registry Architecture
2+
3+
This document describes the technical architecture of the MCP Registry, including system components, deployment strategies, and data flows.
4+
5+
## System Overview
6+
7+
The MCP Registry is designed as a lightweight metadata service that bridges MCP server creators with consumers (MCP clients and aggregators).
8+
9+
```mermaid
10+
graph TB
11+
subgraph "Server Maintainers"
12+
CLI[CLI Tool]
13+
end
14+
15+
subgraph "MCP Registry"
16+
API[REST API<br/>Go]
17+
DB[(MongoDB or PostgreSQL)]
18+
CDN[CDN Cache]
19+
end
20+
21+
subgraph "Intermediaries"
22+
MKT[Marketplaces]
23+
AGG[Aggregators]
24+
end
25+
26+
subgraph "End Consumers"
27+
MC[MCP Client Host Apps<br/>e.g. Claude Desktop]
28+
end
29+
30+
subgraph "External Services"
31+
NPM[npm Registry]
32+
PYPI[PyPI Registry]
33+
DOCKER[Docker Hub]
34+
DNS[DNS Services]
35+
GH[GitHub OAuth]
36+
end
37+
38+
CLI --> |Publish| API
39+
API --> DB
40+
API --> CDN
41+
CDN --> |Daily ETL| MKT
42+
CDN --> |Daily ETL| AGG
43+
MKT --> MC
44+
AGG --> MC
45+
API -.-> |Auth| GH
46+
API -.-> |Verify| DNS
47+
API -.-> |Reference| NPM
48+
API -.-> |Reference| PYPI
49+
API -.-> |Reference| DOCKER
50+
```
51+
52+
## Core Components
53+
54+
### REST API (Go)
55+
56+
The main application server implemented in Go, providing:
57+
- Public read endpoints for server discovery
58+
- Authenticated write endpoints for server publication
59+
- GitHub OAuth integration (extensible to other providers)
60+
- DNS verification system (optional for custom namespaces)
61+
62+
### Database (MongoDB or PostgreSQL)
63+
64+
Primary data store for:
65+
- Versioned server metadata (server.json contents)
66+
- User authentication state
67+
- DNS verification records
68+
69+
### CDN Layer
70+
71+
Critical for scalability:
72+
- Caches all public read endpoints
73+
- Reduces load on origin servers
74+
- Enables global distribution
75+
- Designed for daily consumer polling patterns
76+
77+
### CLI Tool
78+
79+
Developer interface for:
80+
- Server publication workflow
81+
- GitHub OAuth flow
82+
- DNS verification
83+
84+
## Deployment Architecture
85+
86+
### Kubernetes Deployment (Helm)
87+
88+
The registry is designed to run on Kubernetes using Helm charts:
89+
90+
```mermaid
91+
graph TB
92+
subgraph "Kubernetes Cluster"
93+
subgraph "Namespace: mcp-registry"
94+
subgraph "Registry Service"
95+
LB[Load Balancer<br/>:80]
96+
RS[Registry Service<br/>:8080]
97+
RP1[Registry Pod 1]
98+
RP2[Registry Pod 2]
99+
RP3[Registry Pod N]
100+
end
101+
102+
subgraph "Database Service"
103+
DBS[DB Service<br/>:27017]
104+
SS[StatefulSet]
105+
PV[Persistent Volume]
106+
end
107+
108+
subgraph "Secrets"
109+
GHS[GitHub OAuth Secret]
110+
end
111+
end
112+
end
113+
114+
LB --> RS
115+
RS --> RP1
116+
RS --> RP2
117+
RS --> RP3
118+
RP1 --> DBS
119+
RP2 --> DBS
120+
RP3 --> DBS
121+
DBS --> SS
122+
SS --> PV
123+
RP1 -.-> GHS
124+
RP2 -.-> GHS
125+
RP3 -.-> GHS
126+
```
127+
128+
## Data Flow Patterns
129+
130+
### 1. Server Publication Flow
131+
132+
```mermaid
133+
sequenceDiagram
134+
participant Dev as Developer
135+
participant CLI as CLI Tool
136+
participant API as Registry API
137+
participant DB as Database
138+
participant GH as GitHub
139+
participant DNS as DNS Provider
140+
141+
Dev->>CLI: mcp publish server.json
142+
CLI->>CLI: Validate server.json
143+
CLI->>GH: OAuth flow
144+
GH-->>CLI: Access token
145+
CLI->>API: POST /servers
146+
API->>GH: Verify token
147+
API->>DNS: Verify domain (if applicable)
148+
API->>DB: Store metadata
149+
API-->>CLI: Success
150+
CLI-->>Dev: Published!
151+
```
152+
153+
### 2. Consumer Discovery Flow
154+
155+
```mermaid
156+
sequenceDiagram
157+
participant Client as MCP Client Host App
158+
participant INT as Intermediary<br/>(Marketplace/Aggregator)
159+
participant CDN as CDN Cache
160+
participant API as Registry API
161+
participant DB as Database
162+
163+
Note over INT,CDN: Daily ETL Process
164+
INT->>CDN: GET /servers
165+
alt Cache Hit
166+
CDN-->>INT: Cached response
167+
else Cache Miss
168+
CDN->>API: GET /servers
169+
API->>DB: Query servers
170+
DB-->>API: Server list
171+
API-->>CDN: Response + cache headers
172+
CDN-->>INT: Response
173+
end
174+
INT->>INT: Process & enhance data
175+
INT->>INT: Store in local cache
176+
177+
Note over Client,INT: Real-time Client Access
178+
Client->>INT: Request server list
179+
INT-->>Client: Curated/enhanced data
180+
```
181+
182+
### 3. DNS Verification Flow
183+
184+
```mermaid
185+
sequenceDiagram
186+
participant User as User
187+
participant CLI as CLI Tool
188+
participant API as Registry API
189+
participant DNS as DNS Provider
190+
participant DB as Database
191+
192+
User->>CLI: mcp verify-domain example.com
193+
CLI->>API: POST /verify-domain
194+
API->>API: Generate verification token
195+
API->>DB: Store pending verification
196+
API-->>CLI: TXT record: mcp-verify=abc123
197+
CLI-->>User: Add TXT record to DNS
198+
User->>DNS: Configure TXT record
199+
User->>CLI: Confirm added
200+
CLI->>API: POST /verify-domain/check
201+
API->>DNS: Query TXT records
202+
DNS-->>API: TXT records
203+
API->>API: Validate token
204+
API->>DB: Store verification
205+
API-->>CLI: Domain verified
206+
CLI-->>User: Success!
207+
```

‎docs/design_principles.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# MCP Registry Design Principles
2+
3+
These are the core constraints that guide the design of the MCP Registry. They are not exhaustive, but they are the most important principles that we will use to evaluate design decisions.
4+
5+
## 1. Single Source of Truth
6+
7+
The registry serves as the authoritative metadata repository for publicly-available MCP servers, both locally-run and remote, open source and closed source. Server creators publish once, and all consumers (MCP clients, aggregators, etc.) reference the same canonical data.
8+
9+
## 2. Minimal Operational Burden
10+
11+
- Design for low maintenance and operational overhead
12+
- Delegate complexity to existing services where possible (GitHub for auth, npm/PyPI for packages)
13+
- Avoid features that require constant human intervention or moderation
14+
- Build for reasonable downtime tolerance (24h acceptable) by having consumers cache data for their end-users
15+
16+
## 3. Vendor Neutrality
17+
18+
- No preferential treatment for specific servers or organizations
19+
- No built-in ranking, curation, or quality judgments
20+
- Let consumers (MCP clients, aggregators) make their own curation decisions
21+
22+
## 4. Meets Industry Security Standards
23+
24+
- Leverage existing package registries (npm, PyPI, Docker Hub, etc.) for source code distribution, obviating the need to reinvent source code security
25+
- Use mechanisms like DNS verification, OAuth to provide base layer of authentication and trust
26+
- Implement rate limiting, field validation, and blacklisting to prevent abuse
27+
28+
## 6. Reusable, Extensible Shapes; Not Infrastructure
29+
30+
- API shapes (OpenAPI, server.json) designed for reuse
31+
- Enable private/internal registries using same formats
32+
- Don't mandate infrastructure reuse - focus on interface compatibility
33+
34+
## 7. Progressive Enhancement
35+
36+
- Start with MVP that provides immediate value
37+
- Build foundation that supports future features
38+
- Don't over-engineer for hypothetical needs
39+
- Each milestone should be independently valuable

0 commit comments

Comments
 (0)