opamcp 1.0.4 → 1.0.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +246 -67
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,135 +1,314 @@
|
|
|
1
1
|
# opamcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP (Model Context Protocol) server for OpenAPI specification exploration.
|
|
4
4
|
|
|
5
|
-
OpenAPI
|
|
6
|
-
더 이상 "이 API 어떻게 쓰는 거야?" 라고 물을 때마다 스펙 문서 전체를 붙여넣지 않아도 됩니다.
|
|
5
|
+
Enables AI assistants to query OpenAPI specifications on-demand, eliminating the need to load entire spec documents into context.
|
|
7
6
|
|
|
8
|
-
##
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **On-demand querying** — Fetch only the relevant portions of an OpenAPI spec
|
|
10
|
+
- **Schema resolution** — Automatically resolves `$ref` references
|
|
11
|
+
- **Search capabilities** — Find endpoints by keyword, path, or tag
|
|
12
|
+
- **Zero configuration** — Single command setup with any OpenAPI spec URL
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
9
15
|
|
|
10
16
|
```bash
|
|
11
|
-
npx -y opamcp@latest
|
|
17
|
+
npx -y opamcp@latest <openapi-spec-url>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
### Claude Desktop
|
|
23
|
+
|
|
24
|
+
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"mcpServers": {
|
|
29
|
+
"my-api": {
|
|
30
|
+
"command": "npx",
|
|
31
|
+
"args": [
|
|
32
|
+
"-y",
|
|
33
|
+
"opamcp@latest",
|
|
34
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
35
|
+
]
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
}
|
|
12
39
|
```
|
|
13
40
|
|
|
14
|
-
|
|
41
|
+
### Cursor
|
|
15
42
|
|
|
16
|
-
|
|
43
|
+
Add to your MCP settings (`.cursor/mcp.json`):
|
|
17
44
|
|
|
18
45
|
```json
|
|
19
46
|
{
|
|
20
47
|
"mcpServers": {
|
|
21
48
|
"my-api": {
|
|
22
49
|
"command": "npx",
|
|
23
|
-
"args": [
|
|
50
|
+
"args": [
|
|
51
|
+
"-y",
|
|
52
|
+
"opamcp@latest",
|
|
53
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
54
|
+
]
|
|
24
55
|
}
|
|
25
56
|
}
|
|
26
57
|
}
|
|
27
58
|
```
|
|
28
59
|
|
|
29
|
-
##
|
|
60
|
+
## Available Tools
|
|
61
|
+
|
|
62
|
+
| Tool | Description |
|
|
63
|
+
| ---------------------- | ------------------------------------------------- |
|
|
64
|
+
| `get_api_info` | Retrieve API metadata (title, version, servers) |
|
|
65
|
+
| `list_tags` | List all available tags with descriptions |
|
|
66
|
+
| `list_endpoints` | List all endpoints with methods and summaries |
|
|
67
|
+
| `get_endpoints_by_tag` | Filter endpoints by specific tag |
|
|
68
|
+
| `get_endpoint_detail` | Get full endpoint specification including schemas |
|
|
69
|
+
| `list_schemas` | List all schema definitions |
|
|
70
|
+
| `get_schema` | Get detailed schema with resolved references |
|
|
71
|
+
| `search_endpoints` | Search endpoints by keyword |
|
|
72
|
+
| `refresh_spec` | Reload the OpenAPI specification |
|
|
73
|
+
|
|
74
|
+
## Supported Formats
|
|
75
|
+
|
|
76
|
+
| Format | Status |
|
|
77
|
+
| ------------- | --------- |
|
|
78
|
+
| OpenAPI 3.0.x | Supported |
|
|
79
|
+
| OpenAPI 3.1.x | Supported |
|
|
80
|
+
| Swagger 2.0 | Partial |
|
|
81
|
+
| JSON | Supported |
|
|
82
|
+
| YAML | Supported |
|
|
83
|
+
|
|
84
|
+
## Configuration
|
|
85
|
+
|
|
86
|
+
### Local Files
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npx -y opamcp@latest file:///path/to/openapi.json
|
|
90
|
+
```
|
|
30
91
|
|
|
31
|
-
|
|
32
|
-
| ---------------------- | --------------------------------- |
|
|
33
|
-
| `get_api_info` | API가 뭐하는 녀석인지 한눈에 파악 |
|
|
34
|
-
| `list_tags` | API 그룹(태그) 목록 보기 |
|
|
35
|
-
| `list_endpoints` | 전체 엔드포인트 훑어보기 |
|
|
36
|
-
| `get_endpoints_by_tag` | 특정 태그의 엔드포인트만 보기 |
|
|
37
|
-
| `get_endpoint_detail` | 엔드포인트 하나 깊게 파보기 |
|
|
38
|
-
| `list_schemas` | 어떤 데이터 타입들이 있는지 보기 |
|
|
39
|
-
| `get_schema` | 특정 스키마 정의 자세히 보기 |
|
|
40
|
-
| `search_endpoints` | 키워드로 엔드포인트 검색 |
|
|
41
|
-
| `refresh_spec` | 스펙 변경됐으면 새로고침 |
|
|
92
|
+
### Multiple APIs
|
|
42
93
|
|
|
43
|
-
|
|
94
|
+
Configure multiple servers in your MCP settings:
|
|
44
95
|
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"mcpServers": {
|
|
99
|
+
"petstore": {
|
|
100
|
+
"command": "npx",
|
|
101
|
+
"args": [
|
|
102
|
+
"-y",
|
|
103
|
+
"opamcp@latest",
|
|
104
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
105
|
+
]
|
|
106
|
+
},
|
|
107
|
+
"stripe": {
|
|
108
|
+
"command": "npx",
|
|
109
|
+
"args": [
|
|
110
|
+
"-y",
|
|
111
|
+
"opamcp@latest",
|
|
112
|
+
"https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
|
|
113
|
+
]
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
45
117
|
```
|
|
46
|
-
나: "이 API 뭐야?"
|
|
47
|
-
AI: (get_api_info 호출) "아, 펫샵 API네요. 반려동물 관리하는..."
|
|
48
118
|
|
|
49
|
-
|
|
50
|
-
|
|
119
|
+
## Development
|
|
120
|
+
|
|
121
|
+
### Prerequisites
|
|
122
|
+
|
|
123
|
+
- [Bun](https://bun.sh) runtime
|
|
124
|
+
|
|
125
|
+
### Setup
|
|
51
126
|
|
|
52
|
-
|
|
53
|
-
|
|
127
|
+
```bash
|
|
128
|
+
git clone https://github.com/your-username/opamcp.git
|
|
129
|
+
cd opamcp
|
|
130
|
+
bun install
|
|
54
131
|
```
|
|
55
132
|
|
|
56
|
-
|
|
133
|
+
### Commands
|
|
57
134
|
|
|
58
135
|
```bash
|
|
59
|
-
bun
|
|
60
|
-
bun run
|
|
61
|
-
bun run build # 빌드
|
|
136
|
+
bun run dev <url> # Start development server
|
|
137
|
+
bun run build # Build for production
|
|
62
138
|
```
|
|
63
139
|
|
|
64
|
-
|
|
140
|
+
### Project Structure
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
opamcp/
|
|
144
|
+
├── index.ts # MCP server entry point
|
|
145
|
+
├── parser.ts # OpenAPI specification parser
|
|
146
|
+
├── types.ts # TypeScript type definitions
|
|
147
|
+
└── tools/ # Tool implementations
|
|
148
|
+
├── get-api-info.ts
|
|
149
|
+
├── get-endpoint-detail.ts
|
|
150
|
+
├── get-endpoints-by-tag.ts
|
|
151
|
+
├── get-schema.ts
|
|
152
|
+
├── list-endpoints.ts
|
|
153
|
+
├── list-schemas.ts
|
|
154
|
+
├── list-tags.ts
|
|
155
|
+
├── refresh-spec.ts
|
|
156
|
+
└── search-endpoints.ts
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Contributing
|
|
160
|
+
|
|
161
|
+
Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
|
|
65
162
|
|
|
66
|
-
|
|
163
|
+
## License
|
|
164
|
+
|
|
165
|
+
[MIT](LICENSE)
|
|
67
166
|
|
|
68
167
|
---
|
|
69
168
|
|
|
70
|
-
#
|
|
169
|
+
# 한국어
|
|
71
170
|
|
|
72
|
-
|
|
171
|
+
OpenAPI 스펙 탐색을 위한 MCP (Model Context Protocol) 서버입니다.
|
|
73
172
|
|
|
74
|
-
|
|
75
|
-
No more pasting entire spec documents every time someone asks "how do I use this API?"
|
|
173
|
+
AI 어시스턴트가 OpenAPI 스펙을 필요에 따라 조회할 수 있도록 하여, 전체 스펙 문서를 컨텍스트에 로드할 필요를 없앱니다.
|
|
76
174
|
|
|
77
|
-
##
|
|
175
|
+
## 주요 기능
|
|
176
|
+
|
|
177
|
+
- **온디맨드 조회** — OpenAPI 스펙의 필요한 부분만 가져옴
|
|
178
|
+
- **스키마 참조 해석** — `$ref` 참조를 자동으로 해석
|
|
179
|
+
- **검색 기능** — 키워드, 경로, 태그로 엔드포인트 검색
|
|
180
|
+
- **설정 불필요** — OpenAPI 스펙 URL 하나로 즉시 시작
|
|
181
|
+
|
|
182
|
+
## 설치
|
|
78
183
|
|
|
79
184
|
```bash
|
|
80
|
-
npx -y opamcp@latest
|
|
185
|
+
npx -y opamcp@latest <openapi-spec-url>
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## 빠른 시작
|
|
189
|
+
|
|
190
|
+
### Claude Desktop
|
|
191
|
+
|
|
192
|
+
Claude Desktop 설정 파일(`claude_desktop_config.json`)에 추가:
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"mcpServers": {
|
|
197
|
+
"my-api": {
|
|
198
|
+
"command": "npx",
|
|
199
|
+
"args": [
|
|
200
|
+
"-y",
|
|
201
|
+
"opamcp@latest",
|
|
202
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
203
|
+
]
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
}
|
|
81
207
|
```
|
|
82
208
|
|
|
83
|
-
|
|
209
|
+
### Cursor
|
|
84
210
|
|
|
85
|
-
|
|
211
|
+
MCP 설정 파일(`.cursor/mcp.json`)에 추가:
|
|
86
212
|
|
|
87
213
|
```json
|
|
88
214
|
{
|
|
89
215
|
"mcpServers": {
|
|
90
216
|
"my-api": {
|
|
91
217
|
"command": "npx",
|
|
92
|
-
"args": [
|
|
218
|
+
"args": [
|
|
219
|
+
"-y",
|
|
220
|
+
"opamcp@latest",
|
|
221
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
222
|
+
]
|
|
93
223
|
}
|
|
94
224
|
}
|
|
95
225
|
}
|
|
96
226
|
```
|
|
97
227
|
|
|
98
|
-
##
|
|
228
|
+
## 사용 가능한 도구
|
|
229
|
+
|
|
230
|
+
| 도구 | 설명 |
|
|
231
|
+
| ---------------------- | ----------------------------------------- |
|
|
232
|
+
| `get_api_info` | API 메타데이터 조회 (제목, 버전, 서버) |
|
|
233
|
+
| `list_tags` | 사용 가능한 모든 태그 및 설명 조회 |
|
|
234
|
+
| `list_endpoints` | 모든 엔드포인트 목록 조회 |
|
|
235
|
+
| `get_endpoints_by_tag` | 특정 태그로 엔드포인트 필터링 |
|
|
236
|
+
| `get_endpoint_detail` | 스키마를 포함한 엔드포인트 상세 스펙 조회 |
|
|
237
|
+
| `list_schemas` | 모든 스키마 정의 목록 조회 |
|
|
238
|
+
| `get_schema` | 참조가 해석된 상세 스키마 조회 |
|
|
239
|
+
| `search_endpoints` | 키워드로 엔드포인트 검색 |
|
|
240
|
+
| `refresh_spec` | OpenAPI 스펙 새로고침 |
|
|
241
|
+
|
|
242
|
+
## 지원 형식
|
|
243
|
+
|
|
244
|
+
| 형식 | 지원 상태 |
|
|
245
|
+
| ------------- | --------- |
|
|
246
|
+
| OpenAPI 3.0.x | 지원 |
|
|
247
|
+
| OpenAPI 3.1.x | 지원 |
|
|
248
|
+
| Swagger 2.0 | 부분 지원 |
|
|
249
|
+
| JSON | 지원 |
|
|
250
|
+
| YAML | 지원 |
|
|
251
|
+
|
|
252
|
+
## 설정
|
|
99
253
|
|
|
100
|
-
|
|
101
|
-
| ---------------------- | -------------------------------------- |
|
|
102
|
-
| `get_api_info` | Get the gist of what this API is about |
|
|
103
|
-
| `list_tags` | See how the API is organized |
|
|
104
|
-
| `list_endpoints` | Browse all endpoints |
|
|
105
|
-
| `get_endpoints_by_tag` | Filter endpoints by tag |
|
|
106
|
-
| `get_endpoint_detail` | Deep dive into a specific endpoint |
|
|
107
|
-
| `list_schemas` | See what data types exist |
|
|
108
|
-
| `get_schema` | Get the full schema definition |
|
|
109
|
-
| `search_endpoints` | Find endpoints by keyword |
|
|
110
|
-
| `refresh_spec` | Reload spec if it changed |
|
|
254
|
+
### 로컬 파일
|
|
111
255
|
|
|
112
|
-
|
|
256
|
+
```bash
|
|
257
|
+
npx -y opamcp@latest file:///path/to/openapi.json
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### 여러 API 등록
|
|
113
261
|
|
|
262
|
+
MCP 설정에서 여러 서버 구성:
|
|
263
|
+
|
|
264
|
+
```json
|
|
265
|
+
{
|
|
266
|
+
"mcpServers": {
|
|
267
|
+
"petstore": {
|
|
268
|
+
"command": "npx",
|
|
269
|
+
"args": [
|
|
270
|
+
"-y",
|
|
271
|
+
"opamcp@latest",
|
|
272
|
+
"https://petstore3.swagger.io/api/v3/openapi.json"
|
|
273
|
+
]
|
|
274
|
+
},
|
|
275
|
+
"stripe": {
|
|
276
|
+
"command": "npx",
|
|
277
|
+
"args": [
|
|
278
|
+
"-y",
|
|
279
|
+
"opamcp@latest",
|
|
280
|
+
"https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
|
|
281
|
+
]
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}
|
|
114
285
|
```
|
|
115
|
-
You: "What's this API?"
|
|
116
|
-
AI: (calls get_api_info) "It's a pet store API for managing pets..."
|
|
117
286
|
|
|
118
|
-
|
|
119
|
-
|
|
287
|
+
## 개발
|
|
288
|
+
|
|
289
|
+
### 사전 요구사항
|
|
120
290
|
|
|
121
|
-
|
|
122
|
-
|
|
291
|
+
- [Bun](https://bun.sh) 런타임
|
|
292
|
+
|
|
293
|
+
### 설정
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
git clone https://github.com/your-username/opamcp.git
|
|
297
|
+
cd opamcp
|
|
298
|
+
bun install
|
|
123
299
|
```
|
|
124
300
|
|
|
125
|
-
|
|
301
|
+
### 명령어
|
|
126
302
|
|
|
127
303
|
```bash
|
|
128
|
-
bun
|
|
129
|
-
bun run
|
|
130
|
-
bun run build # Build
|
|
304
|
+
bun run dev <url> # 개발 서버 시작
|
|
305
|
+
bun run build # 프로덕션 빌드
|
|
131
306
|
```
|
|
132
307
|
|
|
133
|
-
##
|
|
308
|
+
## 기여
|
|
309
|
+
|
|
310
|
+
기여를 환영합니다. Pull Request를 제출하기 전에 먼저 Issue를 통해 제안하려는 변경 사항을 논의해 주세요.
|
|
311
|
+
|
|
312
|
+
## 라이선스
|
|
134
313
|
|
|
135
|
-
MIT
|
|
314
|
+
[MIT](LICENSE)
|