opamcp 1.0.0 → 1.0.1

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 +69 -83
  2. package/dist/index.js +91 -91
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,149 +1,135 @@
1
1
  # opamcp
2
2
 
3
- OpenAPI MCP Server - OpenAPI 스펙을 MCP 도구로 노출하여 AI 어시스턴트가 API를 탐색할 수 있게 합니다.
3
+ > "OpenAPI 스펙 문서 읽기 귀찮아..." 하던 AI를 위한 MCP 서버
4
4
 
5
- ## 설치 및 사용법
5
+ OpenAPI 스펙 URL 하나 던져주면, AI가 알아서 API 구조를 탐색할 수 있게 해주는 도구입니다.
6
+ 더 이상 "이 API 어떻게 쓰는 거야?" 라고 물을 때마다 스펙 문서 전체를 붙여넣지 않아도 됩니다.
6
7
 
7
- ```bash
8
- # npx로 바로 실행
9
- npx -y opamcp <openapi-url>
8
+ ## 어떻게 쓰나요?
10
9
 
11
- # 예시
10
+ ```bash
12
11
  npx -y opamcp https://petstore3.swagger.io/api/v3/openapi.json
13
12
  ```
14
13
 
15
- ## MCP 클라이언트 설정
16
-
17
- ### Claude Desktop / Cursor
14
+ 끝. 진짜 이게 다입니다.
18
15
 
19
- MCP 클라이언트 설정에 다음을 추가하세요:
16
+ ## Claude Desktop / Cursor 설정
20
17
 
21
18
  ```json
22
19
  {
23
20
  "mcpServers": {
24
21
  "my-api": {
25
22
  "command": "npx",
26
- "args": [
27
- "-y",
28
- "opamcp",
29
- "https://petstore3.swagger.io/api/v3/openapi.json"
30
- ]
23
+ "args": ["-y", "opamcp", "https://your-api.com/openapi.json"]
31
24
  }
32
25
  }
33
26
  }
34
27
  ```
35
28
 
36
- ## 제공되는 도구
29
+ ## 뭘 할 수 있나요?
37
30
 
38
- | 도구 | 설명 | 파라미터 |
39
- | ---------------------- | ----------------------------------------------------------- | -------------------------------- |
40
- | `get_api_info` | API 기본 정보 조회 (title, version, description, servers) | - |
41
- | `list_tags` | 모든 태그(API 그룹) 목록 조회 | - |
42
- | `list_endpoints` | 모든 엔드포인트 요약 목록 조회 | - |
43
- | `get_endpoints_by_tag` | 특정 태그에 속한 엔드포인트 조회 | `tag: string` |
44
- | `get_endpoint_detail` | 엔드포인트 상세 정보 조회 (파라미터, 요청, 응답, 스키마 등) | `path: string`, `method: string` |
45
- | `list_schemas` | components/schemas의 모든 스키마 이름 조회 | - |
46
- | `get_schema` | 특정 스키마 정의 조회 | `name: string` |
47
- | `search_endpoints` | path, summary, operationId로 엔드포인트 검색 | `query: string` |
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` | 스펙 변경됐으면 새로고침 |
48
42
 
49
- ## 권장 사용 흐름
43
+ ## 이렇게 쓰면 됩니다
50
44
 
51
- 1. **`get_api_info`** - API가 무엇인지 파악
52
- 2. **`list_tags`** - API 구조 파악
53
- 3. **`list_endpoints`** 또는 **`get_endpoints_by_tag`** - 관련 엔드포인트 찾기
54
- 4. **`get_endpoint_detail`** - 특정 엔드포인트 상세 정보 확인
55
- 5. **`list_schemas`** → **`get_schema`** - 데이터 타입 탐색
45
+ ```
46
+ 나: "이 API 뭐야?"
47
+ AI: (get_api_info 호출) "아, 펫샵 API네요. 반려동물 관리하는..."
56
48
 
57
- ## 개발
49
+ 나: "주문 관련 API 있어?"
50
+ AI: (search_endpoints 'order' 호출) "네, 주문 생성, 조회, 삭제 API가 있네요"
58
51
 
59
- ```bash
60
- # 의존성 설치
61
- bun install
52
+ 나: "주문 생성 어떻게 해?"
53
+ AI: (get_endpoint_detail '/store/order' 'post' 호출) "이렇게 하시면 됩니다..."
54
+ ```
62
55
 
63
- # 로컬 실행
64
- bun run dev https://petstore3.swagger.io/api/v3/openapi.json
56
+ ## 개발
65
57
 
66
- # 배포용 빌드
67
- bun run build
58
+ ```bash
59
+ bun install # 의존성 설치
60
+ bun run dev <url> # 로컬 실행
61
+ bun run build # 빌드
68
62
  ```
69
63
 
70
64
  ## 라이선스
71
65
 
72
- MIT
66
+ MIT - 맘대로 쓰세요
73
67
 
74
68
  ---
75
69
 
76
70
  # English
77
71
 
78
- OpenAPI MCP Server - Expose OpenAPI specs as MCP tools for AI assistants.
72
+ > For AIs tired of reading OpenAPI spec documents
79
73
 
80
- This MCP server parses an OpenAPI specification and provides semantic tools that allow AI assistants to explore and understand APIs step by step.
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?"
81
76
 
82
- ## Installation & Usage
77
+ ## Quick Start
83
78
 
84
79
  ```bash
85
- # Run directly with npx
86
- npx -y opamcp <openapi-url>
87
-
88
- # Example
89
80
  npx -y opamcp https://petstore3.swagger.io/api/v3/openapi.json
90
81
  ```
91
82
 
92
- ## MCP Client Configuration
93
-
94
- ### Claude Desktop / Cursor
83
+ That's it. Really.
95
84
 
96
- Add to your MCP client configuration:
85
+ ## Claude Desktop / Cursor Setup
97
86
 
98
87
  ```json
99
88
  {
100
89
  "mcpServers": {
101
90
  "my-api": {
102
91
  "command": "npx",
103
- "args": [
104
- "-y",
105
- "opamcp",
106
- "https://petstore3.swagger.io/api/v3/openapi.json"
107
- ]
92
+ "args": ["-y", "opamcp", "https://your-api.com/openapi.json"]
108
93
  }
109
94
  }
110
95
  }
111
96
  ```
112
97
 
113
- ## Available Tools
98
+ ## What can it do?
114
99
 
115
- | Tool | Description | Parameters |
116
- | ---------------------- | --------------------------------------------------------------- | -------------------------------- |
117
- | `get_api_info` | Get API basic info (title, version, description, servers) | - |
118
- | `list_tags` | List all tags (API groups) | - |
119
- | `list_endpoints` | List all endpoints with summary | - |
120
- | `get_endpoints_by_tag` | Get endpoints filtered by tag | `tag: string` |
121
- | `get_endpoint_detail` | Get detailed endpoint info (params, request, response, schemas) | `path: string`, `method: string` |
122
- | `list_schemas` | List all schema names in components/schemas | - |
123
- | `get_schema` | Get full schema definition | `name: string` |
124
- | `search_endpoints` | Search endpoints by path, summary, or operationId | `query: string` |
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 |
125
111
 
126
- ## Recommended Usage Flow
112
+ ## How it works
127
113
 
128
- 1. **`get_api_info`** - Understand what the API is about
129
- 2. **`list_tags`** - See how the API is organized
130
- 3. **`list_endpoints`** or **`get_endpoints_by_tag`** - Find relevant endpoints
131
- 4. **`get_endpoint_detail`** - Get detailed information about a specific endpoint
132
- 5. **`list_schemas`** → **`get_schema`** - Explore data types
114
+ ```
115
+ You: "What's this API?"
116
+ AI: (calls get_api_info) "It's a pet store API for managing pets..."
133
117
 
134
- ## Development
118
+ You: "Any order-related endpoints?"
119
+ AI: (calls search_endpoints 'order') "Yes, there's create, get, and delete order APIs"
135
120
 
136
- ```bash
137
- # Install dependencies
138
- bun install
121
+ You: "How do I create an order?"
122
+ AI: (calls get_endpoint_detail '/store/order' 'post') "Here's how..."
123
+ ```
139
124
 
140
- # Run locally
141
- bun run dev https://petstore3.swagger.io/api/v3/openapi.json
125
+ ## Development
142
126
 
143
- # Build for distribution
144
- bun run build
127
+ ```bash
128
+ bun install # Install deps
129
+ bun run dev <url> # Run locally
130
+ bun run build # Build
145
131
  ```
146
132
 
147
133
  ## License
148
134
 
149
- MIT
135
+ MIT - Do whatever you want