opamcp 1.0.4 → 1.0.5

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.
Files changed (2) hide show
  1. package/README.md +211 -69
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,135 +1,277 @@
1
1
  # opamcp
2
2
 
3
- > "OpenAPI 스펙 문서 읽기 귀찮아..." 하던 AI를 위한 MCP 서버
3
+ > OpenAPI spec을 context window에 욱여넣던 시절은 끝났다.
4
4
 
5
- OpenAPI 스펙 URL 하나 던져주면, AI가 알아서 API 구조를 탐색할 수 있게 해주는 도구입니다.
6
- 더 이상 "이 API 어떻게 쓰는 거야?" 라고 물을 때마다 스펙 문서 전체를 붙여넣지 않아도 됩니다.
5
+ ```
6
+
7
+ ___ _ __ __ _ _ __ ___ ___ _ __
8
+ / _ \| '_ \ / _` | '_ ` _ \ / __| '_ \
9
+ | (_) | |_) | (_| | | | | | | (__| |_) |
10
+ \___/| .__/ \__,_|_| |_| |_|\___| .__/
11
+ |_| |_|
12
+
13
+ ```
14
+
15
+ OpenAPI 스펙 URL 하나면 충분합니다. AI가 필요할 때 필요한 만큼만 가져갑니다.
7
16
 
8
- ## 어떻게 쓰나요?
17
+ ## TL;DR
9
18
 
10
19
  ```bash
11
20
  npx -y opamcp@latest https://petstore3.swagger.io/api/v3/openapi.json
12
21
  ```
13
22
 
14
- 끝. 진짜 이게 다입니다. (`@latest` 붙이면 항상 최신 버전)
23
+ 진짜 끝입니다. 더 설명이 필요하면 아래로 스크롤하세요.
24
+
25
+ ## Why?
26
+
27
+ 매번 이러고 계셨죠?
28
+
29
+ ```
30
+ Human: 이 API 어떻게 써?
31
+ *OpenAPI spec 10,000줄 복붙*
32
+
33
+ AI: 토큰이... 눈앞이... 캄캄...
34
+ ```
35
+
36
+ 이제 이렇게 됩니다:
37
+
38
+ ```
39
+ Human: 이 API 어떻게 써?
40
+
41
+ AI: (get_endpoint_detail 호출)
42
+ 아, POST /orders 쓰시면 됩니다. requestBody는...
43
+ ```
44
+
45
+ **Lazy loading for LLMs.** 필요한 정보만, 필요할 때.
46
+
47
+ ## Setup
15
48
 
16
- ## Claude Desktop / Cursor 설정
49
+ ### Claude Desktop / Cursor
50
+
51
+ `~/.cursor/mcp.json` 또는 Claude Desktop 설정:
17
52
 
18
53
  ```json
19
54
  {
20
55
  "mcpServers": {
21
- "my-api": {
56
+ "petstore": {
22
57
  "command": "npx",
23
- "args": ["-y", "opamcp@latest", "https://your-api.com/openapi.json"]
58
+ "args": [
59
+ "-y",
60
+ "opamcp@latest",
61
+ "https://petstore3.swagger.io/api/v3/openapi.json"
62
+ ]
24
63
  }
25
64
  }
26
65
  }
27
66
  ```
28
67
 
29
- ## 뭘 할 수 있나요?
68
+ 여러 API? 여러 서버 추가하면 됩니다:
30
69
 
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` | 스펙 변경됐으면 새로고침 |
70
+ ```json
71
+ {
72
+ "mcpServers": {
73
+ "petstore": {
74
+ "command": "npx",
75
+ "args": [
76
+ "-y",
77
+ "opamcp@latest",
78
+ "https://petstore3.swagger.io/api/v3/openapi.json"
79
+ ]
80
+ },
81
+ "stripe": {
82
+ "command": "npx",
83
+ "args": [
84
+ "-y",
85
+ "opamcp@latest",
86
+ "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"
87
+ ]
88
+ }
89
+ }
90
+ }
91
+ ```
42
92
 
43
- ## 이렇게 쓰면 됩니다
93
+ ## API
44
94
 
45
- ```
46
- 나: "이 API 뭐야?"
47
- AI: (get_api_info 호출) "아, 펫샵 API네요. 반려동물 관리하는..."
95
+ | Tool | Description |
96
+ | ---------------------- | ------------------------------------------------------ |
97
+ | `get_api_info` | 이 API가 뭔지 30초 안에 파악 |
98
+ | `list_tags` | API 그룹핑 구조 확인 |
99
+ | `list_endpoints` | 전체 엔드포인트 인덱스 |
100
+ | `get_endpoints_by_tag` | 태그별 필터링 |
101
+ | `get_endpoint_detail` | 단일 엔드포인트 딥다이브 (params, body, response 전부) |
102
+ | `list_schemas` | 데이터 모델 카탈로그 |
103
+ | `get_schema` | 스키마 정의 + nested refs 해석 |
104
+ | `search_endpoints` | 키워드 기반 엔드포인트 검색 |
105
+ | `refresh_spec` | 스펙 리로드 (개발 중 유용) |
48
106
 
49
- 나: "주문 관련 API 있어?"
50
- AI: (search_endpoints 'order' 호출) "네, 주문 생성, 조회, 삭제 API가 있네요"
107
+ ## How It Works
51
108
 
52
- 나: "주문 생성 어떻게 해?"
53
- AI: (get_endpoint_detail '/store/order' 'post' 호출) "이렇게 하시면 됩니다..."
109
+ ```
110
+ ┌─────────────────────────────────────────────────────────┐
111
+ │ Your AI │
112
+ └─────────────────────┬───────────────────────────────────┘
113
+ │ MCP Protocol
114
+ ▼
115
+ ┌─────────────────────────────────────────────────────────┐
116
+ │ opamcp │
117
+ │ ┌───────────────────────────────────────────────────┐ │
118
+ │ │ Parsed OpenAPI Spec (in memory) │ │
119
+ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
120
+ │ │ │ paths │ │ schemas │ │ tags │ ... │ │
121
+ │ │ └─────────┘ └─────────┘ └─────────┘ │ │
122
+ │ └───────────────────────────────────────────────────┘ │
123
+ │ │ │ │ │
124
+ │ list_endpoints get_schema search_endpoints │
125
+ │ │ │ │ │
126
+ │ ▼ ▼ ▼ │
127
+ │ Minimal, focused response to AI │
128
+ └─────────────────────────────────────────────────────────┘
54
129
  ```
55
130
 
56
- ## 개발
131
+ 전체 스펙을 파싱해서 메모리에 들고 있다가, AI가 필요한 부분만 쿼리합니다.
132
+
133
+ ## Development
57
134
 
58
135
  ```bash
59
- bun install # 의존성 설치
60
- bun run dev <url> # 로컬 실행
61
- bun run build # 빌드
136
+ # Prerequisites: bun (https://bun.sh)
137
+
138
+ git clone https://github.com/your-username/opamcp
139
+ cd opamcp
140
+
141
+ bun install # deps
142
+ bun run dev <url> # local dev server
143
+ bun run build # production build
62
144
  ```
63
145
 
64
- ## 라이선스
146
+ ### Project Structure
65
147
 
66
- MIT - 맘대로 쓰세요
148
+ ```
149
+ opamcp/
150
+ ├── index.ts # MCP server entry
151
+ ├── parser.ts # OpenAPI spec parser
152
+ ├── types.ts # TypeScript definitions
153
+ └── tools/ # Individual tool implementations
154
+ ├── get-api-info.ts
155
+ ├── get-endpoint-detail.ts
156
+ ├── search-endpoints.ts
157
+ └── ...
158
+ ```
159
+
160
+ ## Compatibility
161
+
162
+ - OpenAPI 3.0.x ✅
163
+ - OpenAPI 3.1.x ✅
164
+ - Swagger 2.0 ⚠️ (기본적인 것들은 동작, edge case 있을 수 있음)
165
+
166
+ ## FAQ
167
+
168
+ **Q: 스펙이 업데이트되면?**
169
+ A: `refresh_spec` 호출하거나, MCP 서버 재시작.
170
+
171
+ **Q: 로컬 파일도 되나요?**
172
+ A: `file:///path/to/spec.json` 또는 `file:///path/to/spec.yaml`
173
+
174
+ **Q: YAML 지원?**
175
+ A: 당연하죠.
176
+
177
+ **Q: Private API라 인증이 필요한데?**
178
+ A: 스펙 URL에 접근만 가능하면 됩니다. 실제 API 호출은 AI가 별도로 합니다.
179
+
180
+ ## License
181
+
182
+ MIT. Fork하든 수정하든 팔아먹든 알아서 하세요.
183
+
184
+ ---
185
+
186
+ <p align="center">
187
+ <sub>Built with ☕ and mass amounts of <code>console.log</code></sub>
188
+ </p>
67
189
 
68
190
  ---
69
191
 
70
192
  # English
71
193
 
72
- > For AIs tired of reading OpenAPI spec documents
194
+ > Stop stuffing OpenAPI specs into context windows.
73
195
 
74
- Just give it an OpenAPI spec URL, and your AI can explore the API structure on its own.
75
- No more pasting entire spec documents every time someone asks "how do I use this API?"
196
+ One URL. That's all your AI needs to explore any OpenAPI-compliant API.
76
197
 
77
- ## Quick Start
198
+ ## TL;DR
78
199
 
79
200
  ```bash
80
201
  npx -y opamcp@latest https://petstore3.swagger.io/api/v3/openapi.json
81
202
  ```
82
203
 
83
- That's it. Really. (`@latest` ensures you always get the newest version)
204
+ Done. Scroll down if you need more.
205
+
206
+ ## Why?
84
207
 
85
- ## Claude Desktop / Cursor Setup
208
+ Before:
209
+
210
+ ```
211
+ Human: How do I use this API?
212
+ *pastes 10,000 lines of OpenAPI spec*
213
+
214
+ AI: My tokens... my context... it's all... fading...
215
+ ```
216
+
217
+ After:
218
+
219
+ ```
220
+ Human: How do I use this API?
221
+
222
+ AI: (calls get_endpoint_detail)
223
+ Use POST /orders. The requestBody should be...
224
+ ```
225
+
226
+ **Lazy loading for LLMs.** Right info, right time.
227
+
228
+ ## Setup
229
+
230
+ ### Claude Desktop / Cursor
86
231
 
87
232
  ```json
88
233
  {
89
234
  "mcpServers": {
90
- "my-api": {
235
+ "petstore": {
91
236
  "command": "npx",
92
- "args": ["-y", "opamcp@latest", "https://your-api.com/openapi.json"]
237
+ "args": [
238
+ "-y",
239
+ "opamcp@latest",
240
+ "https://petstore3.swagger.io/api/v3/openapi.json"
241
+ ]
93
242
  }
94
243
  }
95
244
  }
96
245
  ```
97
246
 
98
- ## What can it do?
99
-
100
- | Tool | What it does |
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 |
247
+ ## API
111
248
 
112
- ## How it works
113
-
114
- ```
115
- You: "What's this API?"
116
- AI: (calls get_api_info) "It's a pet store API for managing pets..."
117
-
118
- You: "Any order-related endpoints?"
119
- AI: (calls search_endpoints 'order') "Yes, there's create, get, and delete order APIs"
120
-
121
- You: "How do I create an order?"
122
- AI: (calls get_endpoint_detail '/store/order' 'post') "Here's how..."
123
- ```
249
+ | Tool | Description |
250
+ | ---------------------- | ------------------------------------ |
251
+ | `get_api_info` | Quick overview of the API |
252
+ | `list_tags` | API grouping structure |
253
+ | `list_endpoints` | Full endpoint index |
254
+ | `get_endpoints_by_tag` | Filter by tag |
255
+ | `get_endpoint_detail` | Deep dive into single endpoint |
256
+ | `list_schemas` | Data model catalog |
257
+ | `get_schema` | Schema definition with resolved refs |
258
+ | `search_endpoints` | Keyword-based endpoint search |
259
+ | `refresh_spec` | Reload spec |
124
260
 
125
261
  ## Development
126
262
 
127
263
  ```bash
128
264
  bun install # Install deps
129
- bun run dev <url> # Run locally
265
+ bun run dev <url> # Local dev
130
266
  bun run build # Build
131
267
  ```
132
268
 
133
269
  ## License
134
270
 
135
- MIT - Do whatever you want
271
+ MIT. Do whatever.
272
+
273
+ ---
274
+
275
+ <p align="center">
276
+ <sub>Made by developers who got tired of Ctrl+F in Swagger UI</sub>
277
+ </p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opamcp",
3
- "version": "1.0.4",
3
+ "version": "1.0.5",
4
4
  "description": "OpenAPI MCP Server - Expose OpenAPI specs as MCP tools for AI assistants",
5
5
  "author": "jinwoo",
6
6
  "license": "MIT",