Skip to content

Commit b005e9c

Browse files
tadasanttadasant
authored
OpenAPI spec for official registry API (#3)
First (incomplete) cut of OpenAPI spec for registry API. To be continued in separate issues.
1 parent d3b607b commit b005e9c

File tree

2 files changed

+728
-0
lines changed

2 files changed

+728
-0
lines changed

‎api/README.md

Lines changed: 383 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,383 @@
1+
# Examples
2+
3+
## /v0/servers
4+
5+
### Request
6+
7+
```http
8+
GET /v0/servers?limit=5000&offset=0
9+
```
10+
11+
### Response
12+
13+
```json
14+
{
15+
"servers": [
16+
{
17+
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
18+
"name": "@modelcontextprotocol/servers/src/filesystem",
19+
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
20+
"repository": {
21+
"url": "https://github.com/modelcontextprotocol/servers",
22+
"source": "github",
23+
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
24+
},
25+
"version_detail": {
26+
"version": "1.0.2",
27+
"release_date": "2023-06-15T10:30:00Z",
28+
"is_latest": true
29+
}
30+
}
31+
],
32+
"next": "https://registry.modelcontextprotocol.io/servers?offset=50",
33+
"total_count": 1
34+
}
35+
```
36+
37+
## /v0/servers/:id
38+
39+
### Request
40+
41+
```http
42+
GET /v0/servers/a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1?version=0.0.3
43+
```
44+
45+
### Response
46+
47+
```json
48+
{
49+
"id": "a5e8a7f0-d4e4-4a1d-b12f-2896a23fd4f1",
50+
"name": "@modelcontextprotocol/servers/src/filesystem",
51+
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations.",
52+
"repository": {
53+
"url": "https://github.com/modelcontextprotocol/servers",
54+
"source": "github",
55+
"id": "b94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
56+
},
57+
"version_detail": {
58+
"version": "1.0.2",
59+
"release_date": "2023-06-15T10:30:00Z",
60+
"is_latest": true
61+
},
62+
"package_canonical": "npm",
63+
"packages": [
64+
{
65+
"registry_name": "npm",
66+
"name": "@modelcontextprotocol/server-filesystem",
67+
"version": "1.0.2",
68+
"command": {
69+
"name": "npx",
70+
"subcommands": [],
71+
"positional_arguments": [
72+
{
73+
"position": 0,
74+
"name": "package",
75+
"description": "NPM package name",
76+
"default_value": "@modelcontextprotocol/server-filesystem",
77+
"is_required": true,
78+
"is_editable": false,
79+
"is_repeatable": false,
80+
"choices": []
81+
},
82+
{
83+
"position": 1,
84+
"name": "path",
85+
"description": "Path to access",
86+
"default_value": "/Users/username/Desktop",
87+
"is_required": true,
88+
"is_editable": true,
89+
"is_repeatable": true,
90+
"choices": []
91+
}
92+
],
93+
"named_arguments": [
94+
{
95+
"short_flag": "-y",
96+
"requires_value": false,
97+
"is_required": false,
98+
"is_editable": false,
99+
"description": "Skip prompts and automatically answer yes",
100+
"choices": []
101+
}
102+
]
103+
},
104+
"environment_variables": [
105+
{
106+
"name": "LOG_LEVEL",
107+
"description": "Logging level (debug, info, warn, error)",
108+
"required": false,
109+
"default_value": "info"
110+
}
111+
]
112+
},
113+
{
114+
"name": "docker",
115+
"package_name": "mcp/filesystem",
116+
"version": "1.0.2",
117+
"command": {
118+
"name": "docker",
119+
"subcommands": [
120+
{
121+
"name": "run",
122+
"description": "Run the Docker container",
123+
"is_required": true,
124+
"subcommands": [],
125+
"positional_arguments": [],
126+
"named_arguments": [
127+
{
128+
"short_flag": "-i",
129+
"requires_value": false,
130+
"is_required": true,
131+
"is_editable": false,
132+
"description": "Run in interactive mode"
133+
},
134+
{
135+
"long_flag": "--rm",
136+
"requires_value": false,
137+
"is_required": true,
138+
"is_editable": false,
139+
"description": "Remove container when it exits"
140+
},
141+
{
142+
"long_flag": "--mount",
143+
"requires_value": true,
144+
"is_required": true,
145+
"is_repeatable": true,
146+
"is_editable": true,
147+
"description": "Mount a volume into the container",
148+
"default_value": "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
149+
"choices": []
150+
}
151+
]
152+
}
153+
],
154+
"positional_arguments": [
155+
{
156+
"position": 0,
157+
"name": "image",
158+
"description": "Docker image name",
159+
"default_value": "mcp/filesystem",
160+
"is_required": true,
161+
"is_editable": false,
162+
"is_repeatable": false,
163+
"choices": []
164+
},
165+
{
166+
"position": 1,
167+
"name": "root_path",
168+
"description": "Root path for filesystem access",
169+
"default_value": "/projects",
170+
"is_required": true,
171+
"is_editable": false,
172+
"is_repeatable": false,
173+
"choices": []
174+
}
175+
],
176+
"named_arguments": []
177+
},
178+
"environment_variables": [
179+
{
180+
"name": "LOG_LEVEL",
181+
"description": "Logging level (debug, info, warn, error)",
182+
"required": false,
183+
"default_value": "info"
184+
}
185+
]
186+
}
187+
],
188+
"remotes": [
189+
{
190+
"transport_type": "sse",
191+
"url": "https://mcp-fs.example.com/sse"
192+
}
193+
]
194+
}
195+
```
196+
197+
### Server Configuration Examples
198+
199+
#### Local Server with npx
200+
201+
API Response:
202+
```json
203+
{
204+
"id": "brave-search-12345",
205+
"name": "@modelcontextprotocol/server-brave-search",
206+
"description": "MCP server for Brave Search API integration",
207+
"repository": {
208+
"url": "https://github.com/modelcontextprotocol/servers",
209+
"source": "github",
210+
"id": "abc123de-f456-7890-ghij-klmnopqrstuv"
211+
},
212+
"version_detail": {
213+
"version": "1.0.2",
214+
"release_date": "2023-06-15T10:30:00Z",
215+
"is_latest": true
216+
},
217+
"package_canonical": "npm",
218+
"packages": [
219+
{
220+
"registry_name": "npm",
221+
"name": "@modelcontextprotocol/server-brave-search",
222+
"version": "1.0.2",
223+
"command": {
224+
"name": "npx",
225+
"subcommands": [],
226+
"positional_arguments": [],
227+
"named_arguments": [
228+
{
229+
"short_flag": "-y",
230+
"requires_value": false,
231+
"is_required": false,
232+
"description": "Skip prompts"
233+
}
234+
]
235+
},
236+
"environment_variables": [
237+
{
238+
"name": "BRAVE_API_KEY",
239+
"description": "Brave Search API Key",
240+
"required": true,
241+
"default_value": ""
242+
}
243+
]
244+
}
245+
]
246+
}
247+
```
248+
249+
claude_desktop_config.json:
250+
```json
251+
{
252+
"brave-search": {
253+
"command": "npx",
254+
"args": [
255+
"-y",
256+
"@modelcontextprotocol/server-brave-search"
257+
],
258+
"env": {
259+
"BRAVE_API_KEY": "YOUR_API_KEY_HERE"
260+
}
261+
}
262+
}
263+
```
264+
265+
#### Local Server with Docker
266+
267+
API Response:
268+
```json
269+
{
270+
"id": "filesystem-67890",
271+
"name": "@modelcontextprotocol/servers/src/filesystem",
272+
"description": "Node.js server implementing Model Context Protocol (MCP) for filesystem operations",
273+
"repository": {
274+
"url": "https://github.com/modelcontextprotocol/servers",
275+
"source": "github",
276+
"id": "d94b5f7e-c7c6-d760-2c78-a5e9b8a5b8c9"
277+
},
278+
"version_detail": {
279+
"version": "1.0.2",
280+
"release_date": "2023-06-15T10:30:00Z",
281+
"is_latest": true
282+
},
283+
"package_canonical": "docker",
284+
"packages": [
285+
{
286+
"registry_name": "docker",
287+
"name": "mcp/filesystem",
288+
"version": "1.0.2",
289+
"command": {
290+
"name": "docker",
291+
"subcommands": [
292+
{
293+
"name": "run",
294+
"description": "Run the Docker container",
295+
"is_required": true,
296+
"named_arguments": [
297+
{
298+
"short_flag": "-i",
299+
"requires_value": false,
300+
"is_required": true,
301+
"description": "Run in interactive mode"
302+
},
303+
{
304+
"long_flag": "--rm",
305+
"requires_value": false,
306+
"is_required": true,
307+
"description": "Remove container when it exits"
308+
},
309+
{
310+
"long_flag": "--mount",
311+
"requires_value": true,
312+
"is_required": true,
313+
"is_repeatable": true,
314+
"description": "Mount a volume into the container"
315+
}
316+
]
317+
}
318+
],
319+
"positional_arguments": [
320+
{
321+
"position": 0,
322+
"name": "image",
323+
"description": "Docker image name",
324+
"default_value": "mcp/filesystem"
325+
},
326+
{
327+
"position": 1,
328+
"name": "root_path",
329+
"description": "Root path for filesystem access",
330+
"default_value": "/projects"
331+
}
332+
]
333+
}
334+
}
335+
]
336+
}
337+
```
338+
339+
claude_desktop_config.json:
340+
```json
341+
{
342+
"filesystem": {
343+
"command": "docker",
344+
"args": [
345+
"run",
346+
"-i",
347+
"--rm",
348+
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
349+
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
350+
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
351+
"mcp/filesystem",
352+
"/projects"
353+
]
354+
}
355+
}
356+
```
357+
358+
#### Remote Server
359+
360+
API Response:
361+
```json
362+
{
363+
"id": "remote-fs-54321",
364+
"name": "Remote Brave Search Server",
365+
"description": "Cloud-hosted MCP Brave Search server",
366+
"repository": {
367+
"url": "https://github.com/example/remote-fs",
368+
"source": "github",
369+
"id": "xyz789ab-cdef-0123-4567-890ghijklmno"
370+
},
371+
"version_detail": {
372+
"version": "1.0.2",
373+
"release_date": "2023-06-15T10:30:00Z",
374+
"is_latest": true
375+
},
376+
"remotes": [
377+
{
378+
"transport_type": "sse",
379+
"url": "https://mcp-fs.example.com/sse"
380+
}
381+
]
382+
}
383+
```

0 commit comments

Comments
 (0)