opamcp 1.0.5 → 1.0.8

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 (3) hide show
  1. package/README.md +189 -152
  2. package/dist/index.js +54 -54
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,59 +1,51 @@
1
1
  # opamcp
2
2
 
3
- > OpenAPI spec을 context window에 욱여넣던 시절은 끝났다.
3
+ MCP (Model Context Protocol) server for OpenAPI specification exploration.
4
4
 
5
- ```
6
-
7
- ___ _ __ __ _ _ __ ___ ___ _ __
8
- / _ \| '_ \ / _` | '_ ` _ \ / __| '_ \
9
- | (_) | |_) | (_| | | | | | | (__| |_) |
10
- \___/| .__/ \__,_|_| |_| |_|\___| .__/
11
- |_| |_|
5
+ Enables AI assistants to query OpenAPI specifications on-demand, eliminating the need to load entire spec documents into context.
12
6
 
13
- ```
7
+ ## Features
14
8
 
15
- OpenAPI 스펙 URL 하나면 충분합니다. AI가 필요할 때 필요한 만큼만 가져갑니다.
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
16
13
 
17
- ## TL;DR
14
+ ## Installation
18
15
 
19
16
  ```bash
20
- npx -y opamcp@latest https://petstore3.swagger.io/api/v3/openapi.json
17
+ npx -y opamcp@latest <openapi-spec-url>
21
18
  ```
22
19
 
23
- 진짜 끝입니다. 더 설명이 필요하면 아래로 스크롤하세요.
24
-
25
- ## Why?
20
+ ## Quick Start
26
21
 
27
- 매번 이러고 계셨죠?
22
+ ### Claude Desktop
28
23
 
29
- ```
30
- Human: 이 API 어떻게 써?
31
- *OpenAPI spec 10,000줄 복붙*
32
-
33
- AI: 토큰이... 눈앞이... 캄캄...
34
- ```
24
+ Add to your Claude Desktop configuration (`claude_desktop_config.json`):
35
25
 
36
- 이제 이렇게 됩니다:
37
-
38
- ```
39
- Human: 이 API 어떻게 써?
40
-
41
- AI: (get_endpoint_detail 호출)
42
- 아, POST /orders 쓰시면 됩니다. requestBody는...
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
+ }
43
39
  ```
44
40
 
45
- **Lazy loading for LLMs.** 필요한 정보만, 필요할 때.
46
-
47
- ## Setup
41
+ ### Cursor
48
42
 
49
- ### Claude Desktop / Cursor
50
-
51
- `~/.cursor/mcp.json` 또는 Claude Desktop 설정:
43
+ Add to your MCP settings (`.cursor/mcp.json`):
52
44
 
53
45
  ```json
54
46
  {
55
47
  "mcpServers": {
56
- "petstore": {
48
+ "my-api": {
57
49
  "command": "npx",
58
50
  "args": [
59
51
  "-y",
@@ -65,7 +57,41 @@ AI: (get_endpoint_detail 호출)
65
57
  }
66
58
  ```
67
59
 
68
- 여러 API? 여러 서버 추가하면 됩니다:
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
+ ```
91
+
92
+ ### Multiple APIs
93
+
94
+ Configure multiple servers in your MCP settings:
69
95
 
70
96
  ```json
71
97
  {
@@ -90,144 +116,150 @@ AI: (get_endpoint_detail 호출)
90
116
  }
91
117
  ```
92
118
 
93
- ## API
94
-
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` | 스펙 리로드 (개발 중 유용) |
119
+ ## Development
106
120
 
107
- ## How It Works
121
+ ### Prerequisites
108
122
 
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
- └─────────────────────────────────────────────────────────┘
129
- ```
123
+ - [Bun](https://bun.sh) runtime
130
124
 
131
- 전체 스펙을 파싱해서 메모리에 들고 있다가, AI가 필요한 부분만 쿼리합니다.
132
-
133
- ## Development
125
+ ### Setup
134
126
 
135
127
  ```bash
136
- # Prerequisites: bun (https://bun.sh)
137
-
138
- git clone https://github.com/your-username/opamcp
128
+ git clone https://github.com/your-username/opamcp.git
139
129
  cd opamcp
130
+ bun install
131
+ ```
132
+
133
+ ### Commands
140
134
 
141
- bun install # deps
142
- bun run dev <url> # local dev server
143
- bun run build # production build
135
+ ```bash
136
+ bun run dev <url> # Start development server
137
+ bun run build # Build for production
144
138
  ```
145
139
 
146
140
  ### Project Structure
147
141
 
148
142
  ```
149
143
  opamcp/
150
- ├── index.ts # MCP server entry
151
- ├── parser.ts # OpenAPI spec parser
152
- ├── types.ts # TypeScript definitions
153
- └── tools/ # Individual tool implementations
144
+ ├── index.ts # MCP server entry point
145
+ ├── parser.ts # OpenAPI specification parser
146
+ ├── types.ts # TypeScript type definitions
147
+ └── tools/ # Tool implementations
154
148
  ├── get-api-info.ts
155
149
  ├── get-endpoint-detail.ts
156
- ├── search-endpoints.ts
157
- └── ...
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
158
157
  ```
159
158
 
160
- ## Compatibility
159
+ ## Contributing
161
160
 
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가 별도로 합니다.
161
+ Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.
179
162
 
180
163
  ## License
181
164
 
182
- MIT. Fork하든 수정하든 팔아먹든 알아서 하세요.
165
+ [MIT](LICENSE)
183
166
 
184
167
  ---
185
168
 
186
- <p align="center">
187
- <sub>Built with ☕ and mass amounts of <code>console.log</code></sub>
188
- </p>
169
+ # 한국어
189
170
 
190
- ---
171
+ OpenAPI 스펙 탐색을 위한 MCP (Model Context Protocol) 서버입니다.
191
172
 
192
- # English
173
+ AI 어시스턴트가 OpenAPI 스펙을 필요에 따라 조회할 수 있도록 하여, 전체 스펙 문서를 컨텍스트에 로드할 필요를 없앱니다.
193
174
 
194
- > Stop stuffing OpenAPI specs into context windows.
175
+ ## 주요 기능
195
176
 
196
- One URL. That's all your AI needs to explore any OpenAPI-compliant API.
177
+ - **온디맨드 조회** — OpenAPI 스펙의 필요한 부분만 가져옴
178
+ - **스키마 참조 해석** — `$ref` 참조를 자동으로 해석
179
+ - **검색 기능** — 키워드, 경로, 태그로 엔드포인트 검색
180
+ - **설정 불필요** — OpenAPI 스펙 URL 하나로 즉시 시작
197
181
 
198
- ## TL;DR
182
+ ## 설치
199
183
 
200
184
  ```bash
201
- npx -y opamcp@latest https://petstore3.swagger.io/api/v3/openapi.json
185
+ npx -y opamcp@latest <openapi-spec-url>
202
186
  ```
203
187
 
204
- Done. Scroll down if you need more.
188
+ ## 빠른 시작
205
189
 
206
- ## Why?
190
+ ### Claude Desktop
207
191
 
208
- Before:
192
+ Claude Desktop 설정 파일(`claude_desktop_config.json`)에 추가:
209
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
+ }
210
207
  ```
211
- Human: How do I use this API?
212
- *pastes 10,000 lines of OpenAPI spec*
213
208
 
214
- AI: My tokens... my context... it's all... fading...
215
- ```
209
+ ### Cursor
216
210
 
217
- After:
211
+ MCP 설정 파일(`.cursor/mcp.json`)에 추가:
218
212
 
213
+ ```json
214
+ {
215
+ "mcpServers": {
216
+ "my-api": {
217
+ "command": "npx",
218
+ "args": [
219
+ "-y",
220
+ "opamcp@latest",
221
+ "https://petstore3.swagger.io/api/v3/openapi.json"
222
+ ]
223
+ }
224
+ }
225
+ }
219
226
  ```
220
- Human: How do I use this API?
221
227
 
222
- AI: (calls get_endpoint_detail)
223
- Use POST /orders. The requestBody should be...
224
- ```
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 | 지원 |
225
251
 
226
- **Lazy loading for LLMs.** Right info, right time.
252
+ ## 설정
227
253
 
228
- ## Setup
254
+ ### 로컬 파일
255
+
256
+ ```bash
257
+ npx -y opamcp@latest file:///path/to/openapi.json
258
+ ```
229
259
 
230
- ### Claude Desktop / Cursor
260
+ ### 여러 API 등록
261
+
262
+ MCP 설정에서 여러 서버 구성:
231
263
 
232
264
  ```json
233
265
  {
@@ -239,39 +271,44 @@ AI: (calls get_endpoint_detail)
239
271
  "opamcp@latest",
240
272
  "https://petstore3.swagger.io/api/v3/openapi.json"
241
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
+ ]
242
282
  }
243
283
  }
244
284
  }
245
285
  ```
246
286
 
247
- ## API
287
+ ## 개발
248
288
 
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 |
289
+ ### 사전 요구사항
260
290
 
261
- ## Development
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
299
+ ```
300
+
301
+ ### 명령어
262
302
 
263
303
  ```bash
264
- bun install # Install deps
265
- bun run dev <url> # Local dev
266
- bun run build # Build
304
+ bun run dev <url> # 개발 서버 시작
305
+ bun run build # 프로덕션 빌드
267
306
  ```
268
307
 
269
- ## License
308
+ ## 기여
270
309
 
271
- MIT. Do whatever.
310
+ 기여를 환영합니다. Pull Request를 제출하기 전에 먼저 Issue를 통해 제안하려는 변경 사항을 논의해 주세요.
272
311
 
273
- ---
312
+ ## 라이선스
274
313
 
275
- <p align="center">
276
- <sub>Made by developers who got tired of Ctrl+F in Swagger UI</sub>
277
- </p>
314
+ [MIT](LICENSE)