@ampeco/public-api-mcp 0.2.2 → 0.4.0
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 +296 -4
- package/dist/build/index.js +52 -7
- package/dist/build/index.js.map +1 -1
- package/dist/build/optimizer.d.ts.map +1 -1
- package/dist/build/optimizer.js +82 -21
- package/dist/build/optimizer.js.map +1 -1
- package/dist/build/parser.d.ts.map +1 -1
- package/dist/build/parser.js +74 -1
- package/dist/build/parser.js.map +1 -1
- package/dist/build/types.d.ts +24 -2
- package/dist/build/types.d.ts.map +1 -1
- package/dist/cli/index.js +25 -11
- package/dist/cli/index.js.map +1 -1
- package/dist/generated/build-stats.json +11 -5
- package/dist/generated/endpoints.json +29219 -20895
- package/dist/generated/response-schemas.json +84437 -0
- package/dist/generated/schemas.d.ts +7157 -2416
- package/dist/generated/schemas.d.ts.map +1 -1
- package/dist/generated/schemas.js +1443 -590
- package/dist/generated/schemas.js.map +1 -1
- package/dist/generated/schemas.ts +1447 -596
- package/dist/server/factory.d.ts +3 -2
- package/dist/server/factory.d.ts.map +1 -1
- package/dist/server/factory.js +144 -231
- package/dist/server/factory.js.map +1 -1
- package/dist/server/factory.test.js +62 -4
- package/dist/server/factory.test.js.map +1 -1
- package/dist/server/http.d.ts +2 -1
- package/dist/server/http.d.ts.map +1 -1
- package/dist/server/http.js +11 -3
- package/dist/server/http.js.map +1 -1
- package/dist/server/index.d.ts +2 -0
- package/dist/server/index.d.ts.map +1 -1
- package/dist/server/index.js +12 -1388
- package/dist/server/index.js.map +1 -1
- package/dist/server/instructions.d.ts +13 -0
- package/dist/server/instructions.d.ts.map +1 -0
- package/dist/server/instructions.js +146 -0
- package/dist/server/instructions.js.map +1 -0
- package/dist/server/loader.d.ts +6 -1
- package/dist/server/loader.d.ts.map +1 -1
- package/dist/server/loader.js +9 -0
- package/dist/server/loader.js.map +1 -1
- package/dist/server/resources/handlers.d.ts +31 -0
- package/dist/server/resources/handlers.d.ts.map +1 -0
- package/dist/server/resources/handlers.js +113 -0
- package/dist/server/resources/handlers.js.map +1 -0
- package/dist/server/resources/handlers.test.d.ts +6 -0
- package/dist/server/resources/handlers.test.d.ts.map +1 -0
- package/dist/server/resources/handlers.test.js +203 -0
- package/dist/server/resources/handlers.test.js.map +1 -0
- package/dist/server/resources/native.d.ts +11 -0
- package/dist/server/resources/native.d.ts.map +1 -0
- package/dist/server/resources/native.js +31 -0
- package/dist/server/resources/native.js.map +1 -0
- package/dist/server/resources/tools.d.ts +11 -0
- package/dist/server/resources/tools.d.ts.map +1 -0
- package/dist/server/resources/tools.js +41 -0
- package/dist/server/resources/tools.js.map +1 -0
- package/dist/server/stdio.d.ts +2 -1
- package/dist/server/stdio.d.ts.map +1 -1
- package/dist/server/stdio.js +11 -3
- package/dist/server/stdio.js.map +1 -1
- package/dist/server/types.d.ts +36 -0
- package/dist/server/types.d.ts.map +1 -0
- package/dist/server/types.js +6 -0
- package/dist/server/types.js.map +1 -0
- package/dist/server/utils/response-transformer.d.ts +78 -0
- package/dist/server/utils/response-transformer.d.ts.map +1 -0
- package/dist/server/utils/response-transformer.js +423 -0
- package/dist/server/utils/response-transformer.js.map +1 -0
- package/dist/server/utils/response-transformer.test.d.ts +2 -0
- package/dist/server/utils/response-transformer.test.d.ts.map +1 -0
- package/dist/server/utils/response-transformer.test.js +103 -0
- package/dist/server/utils/response-transformer.test.js.map +1 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -106,12 +106,26 @@ Generated Artifacts (endpoints.json, schemas.ts)
|
|
|
106
106
|
The server provides a complete MCP implementation for accessing your OpenAPI-defined API:
|
|
107
107
|
|
|
108
108
|
- **Dual Transport Support**: Both Stdio (local) and HTTP (remote) transports
|
|
109
|
+
- **Flexible Resource Mode**: Native MCP resources OR tool-based emulation for Claude Desktop compatibility
|
|
109
110
|
- **Dynamic Resources**: All API endpoints exposed as MCP resources with full schema details
|
|
110
111
|
- **API Request Tool**: Fully typed `api_request` tool with automatic authentication and parameter validation
|
|
111
112
|
- **Stateless Architecture**: No session state required - all parameters provided per request
|
|
112
113
|
- **Zero Configuration**: Pre-processed data loads instantly, no config files needed
|
|
113
114
|
- **MCP Protocol Compliance**: Full implementation of MCP Streamable HTTP transport specification
|
|
114
115
|
|
|
116
|
+
#### Resource Modes
|
|
117
|
+
|
|
118
|
+
The server supports two modes for exposing API endpoints:
|
|
119
|
+
|
|
120
|
+
1. **Native Resources Mode** (Default): Uses native MCP resources for endpoint discovery
|
|
121
|
+
- Best for: MCP clients that fully support the resources capability
|
|
122
|
+
- Features: Hierarchical 3-tier navigation (tags → endpoints → details)
|
|
123
|
+
|
|
124
|
+
2. **Tool Emulation Mode**: Exposes resources through tools (`list_resources`, `read_resource`)
|
|
125
|
+
- **Required for Claude Desktop** (does not support native MCP resources)
|
|
126
|
+
- Provides identical functionality through tool-based interface
|
|
127
|
+
- Enable with `--emulate-resources-via-tools` flag
|
|
128
|
+
|
|
115
129
|
### Running the Server
|
|
116
130
|
|
|
117
131
|
```bash
|
|
@@ -141,6 +155,189 @@ The server uses a hostname-based routing structure where the target API hostname
|
|
|
141
155
|
- `POST /api.example.com/http` → Routes to `http://api.example.com`
|
|
142
156
|
- `POST /internal.api.company.com/http` → Routes to `http://internal.api.company.com`
|
|
143
157
|
|
|
158
|
+
## Setting Up with Claude Desktop
|
|
159
|
+
|
|
160
|
+
**IMPORTANT**: Claude Desktop **does not support native MCP resources**. You **MUST** use the `--emulate-resources-via-tools` flag for Claude Desktop.
|
|
161
|
+
|
|
162
|
+
### Installation via Desktop Extension (.mcpb)
|
|
163
|
+
|
|
164
|
+
The easiest way to install this MCP server in Claude Desktop is using the Desktop Extension bundle:
|
|
165
|
+
|
|
166
|
+
#### Option 1: From Official Directory (Recommended)
|
|
167
|
+
|
|
168
|
+
1. Open Claude Desktop
|
|
169
|
+
2. Go to **Settings** → **Extensions**
|
|
170
|
+
3. Click **"Browse extensions"**
|
|
171
|
+
4. Search for **"AMPECO Public API"**
|
|
172
|
+
5. Click **Install** and follow the configuration prompts
|
|
173
|
+
|
|
174
|
+
#### Option 2: Manual Installation
|
|
175
|
+
|
|
176
|
+
1. Download the latest `.mcpb` file from the [releases page](https://github.com/ampeco/public-api-mcp/releases)
|
|
177
|
+
2. Open Claude Desktop
|
|
178
|
+
3. Go to **Settings** → **Extensions**
|
|
179
|
+
4. Click **"Install Extension..."**
|
|
180
|
+
5. Select the downloaded `.mcpb` file
|
|
181
|
+
6. Configure the required settings:
|
|
182
|
+
- **API Hostname**: Your AMPECO API server (e.g., `https://api.example.com`)
|
|
183
|
+
- **Bearer Token**: Your AMPECO API authentication token
|
|
184
|
+
|
|
185
|
+
The extension will automatically operate in resource emulation mode for Claude Desktop compatibility.
|
|
186
|
+
|
|
187
|
+
### Manual Configuration (Advanced)
|
|
188
|
+
|
|
189
|
+
If you prefer manual configuration or want to customize the setup:
|
|
190
|
+
|
|
191
|
+
### Claude Desktop Configuration
|
|
192
|
+
|
|
193
|
+
Claude Desktop uses a configuration file called `claude_desktop_config.json` located at:
|
|
194
|
+
|
|
195
|
+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
196
|
+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
197
|
+
|
|
198
|
+
You can also access this file through Claude Desktop: **Settings** → **Developer** → **Edit Config**
|
|
199
|
+
|
|
200
|
+
### Configuration Example
|
|
201
|
+
|
|
202
|
+
Add this to your `claude_desktop_config.json`:
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{
|
|
206
|
+
"mcpServers": {
|
|
207
|
+
"ampeco-api": {
|
|
208
|
+
"command": "npx",
|
|
209
|
+
"args": [
|
|
210
|
+
"-y",
|
|
211
|
+
"@ampeco/public-api-mcp",
|
|
212
|
+
"--stdio",
|
|
213
|
+
"--hostname",
|
|
214
|
+
"https://api.example.com",
|
|
215
|
+
"--emulate-resources-via-tools"
|
|
216
|
+
],
|
|
217
|
+
"env": {
|
|
218
|
+
"AMPECO_BEARER_TOKEN": "your-token-here"
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Replace**:
|
|
226
|
+
- `https://api.example.com` with your actual API hostname
|
|
227
|
+
- `your-token-here` with your bearer token
|
|
228
|
+
|
|
229
|
+
**After editing the file**, restart Claude Desktop for changes to take effect
|
|
230
|
+
|
|
231
|
+
### What is Tool Emulation Mode?
|
|
232
|
+
|
|
233
|
+
When `--emulate-resources-via-tools` is enabled, the server provides two additional tools:
|
|
234
|
+
|
|
235
|
+
1. **`list_resources`**: Discover available API tags (e.g., Users, ChargingSessions)
|
|
236
|
+
- No parameters required
|
|
237
|
+
- Returns list of tags that group related endpoints
|
|
238
|
+
|
|
239
|
+
2. **`read_resource`**: Read endpoint definitions by URI
|
|
240
|
+
- Parameter: `uri` (e.g., `tag://Users` or `api://GET/users/{id}`)
|
|
241
|
+
- Returns full endpoint specification
|
|
242
|
+
|
|
243
|
+
These tools provide **identical functionality** to native MCP resources but work through the tools interface that Claude Desktop supports.
|
|
244
|
+
|
|
245
|
+
### Tool Schemas (Emulation Mode)
|
|
246
|
+
|
|
247
|
+
When `--emulate-resources-via-tools` is enabled, the following tools are available:
|
|
248
|
+
|
|
249
|
+
#### `list_resources` Tool
|
|
250
|
+
|
|
251
|
+
**Description**: List all available API tags. This emulates the native MCP resources/list functionality. Returns a list of tags that group related endpoints together (e.g., Users, ChargingSessions, Connectors). Each tag can then be read using the read_resource tool with tag:// URIs.
|
|
252
|
+
|
|
253
|
+
**Parameters**: None
|
|
254
|
+
|
|
255
|
+
**Returns**: JSON object with `resources` array containing:
|
|
256
|
+
```json
|
|
257
|
+
{
|
|
258
|
+
"resources": [
|
|
259
|
+
{
|
|
260
|
+
"uri": "tag://Users",
|
|
261
|
+
"name": "Users",
|
|
262
|
+
"description": "15 endpoints tagged with 'Users'",
|
|
263
|
+
"mimeType": "application/json"
|
|
264
|
+
},
|
|
265
|
+
{
|
|
266
|
+
"uri": "tag://ChargingSessions",
|
|
267
|
+
"name": "ChargingSessions",
|
|
268
|
+
"description": "8 endpoints tagged with 'ChargingSessions'",
|
|
269
|
+
"mimeType": "application/json"
|
|
270
|
+
}
|
|
271
|
+
]
|
|
272
|
+
}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
**Example Usage**:
|
|
276
|
+
```
|
|
277
|
+
Call list_resources tool → Get list of all API tags
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
#### `read_resource` Tool
|
|
281
|
+
|
|
282
|
+
**Description**: Read a specific resource by URI. This emulates the native MCP resources/read functionality. Supports two URI formats: tag://{TagName} to read all endpoints within a tag, and api://{METHOD}{path} to read detailed endpoint specifications. You MUST use this tool to read endpoint definitions before calling api_request.
|
|
283
|
+
|
|
284
|
+
**Parameters**:
|
|
285
|
+
- `uri` (string, required): The resource URI to read
|
|
286
|
+
- Format: `tag://{TagName}` or `api://{METHOD}{path}`
|
|
287
|
+
- Examples: `"tag://Users"`, `"api://GET/users/{id}"`, `"api://POST/charging-sessions"`
|
|
288
|
+
|
|
289
|
+
**Returns** (for tag URIs):
|
|
290
|
+
```json
|
|
291
|
+
{
|
|
292
|
+
"tag": "Users",
|
|
293
|
+
"count": 15,
|
|
294
|
+
"endpoints": [
|
|
295
|
+
{
|
|
296
|
+
"uri": "api://GET/users/{id}",
|
|
297
|
+
"method": "GET",
|
|
298
|
+
"path": "/users/{id}",
|
|
299
|
+
"summary": "Get user by ID",
|
|
300
|
+
"operationId": "getUser"
|
|
301
|
+
}
|
|
302
|
+
]
|
|
303
|
+
}
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
**Returns** (for api URIs):
|
|
307
|
+
```json
|
|
308
|
+
{
|
|
309
|
+
"path": "/users/{id}",
|
|
310
|
+
"method": "GET",
|
|
311
|
+
"operationId": "getUser",
|
|
312
|
+
"summary": "Get user by ID",
|
|
313
|
+
"description": "Retrieves detailed information about a specific user",
|
|
314
|
+
"parameters": [...],
|
|
315
|
+
"requestBody": {...},
|
|
316
|
+
"responses": {...},
|
|
317
|
+
"security": "Include token in Authorization header as: Authorization: Bearer <token>"
|
|
318
|
+
}
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
**Example Usage**:
|
|
322
|
+
```
|
|
323
|
+
1. Call read_resource with uri="tag://Users" → Get all endpoints in Users tag
|
|
324
|
+
2. Call read_resource with uri="api://GET/users/{id}" → Get full endpoint specification
|
|
325
|
+
3. Call api_request with correct parameters → Make the actual API call
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
### When to Use Each Mode
|
|
329
|
+
|
|
330
|
+
| Mode | Use For | Clients |
|
|
331
|
+
|------|---------|---------|
|
|
332
|
+
| **Native Resources** (default) | MCP clients that fully support resources | **Claude Code**, MCP Inspector |
|
|
333
|
+
| **Tool Emulation** (`--emulate-resources-via-tools`) | Clients without resource support | **Claude Desktop** |
|
|
334
|
+
|
|
335
|
+
**Important Distinction**:
|
|
336
|
+
- **Claude Code** (the CLI tool): Supports native MCP resources - use **default mode**
|
|
337
|
+
- **Claude Desktop** (the desktop app): Does NOT support resources - use **`--emulate-resources-via-tools`**
|
|
338
|
+
|
|
339
|
+
**Rule of thumb**: If you're using **Claude Desktop**, always add `--emulate-resources-via-tools`. If using **Claude Code**, use default mode.
|
|
340
|
+
|
|
144
341
|
## Setting Up with Claude Code
|
|
145
342
|
|
|
146
343
|
The MCP server supports two transport modes:
|
|
@@ -203,10 +400,15 @@ For production use without needing the source code:
|
|
|
203
400
|
#### Option 1: One-Liner (Recommended)
|
|
204
401
|
|
|
205
402
|
```bash
|
|
206
|
-
# Add production server with a single command
|
|
403
|
+
# Add production server with a single command (native resources)
|
|
207
404
|
claude mcp add --transport stdio ampeco-api \
|
|
208
405
|
--env AMPECO_BEARER_TOKEN=your-token-here \
|
|
209
406
|
-- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com
|
|
407
|
+
|
|
408
|
+
# With tool emulation mode (if client doesn't support resources)
|
|
409
|
+
claude mcp add --transport stdio ampeco-api \
|
|
410
|
+
--env AMPECO_BEARER_TOKEN=your-token-here \
|
|
411
|
+
-- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools
|
|
210
412
|
```
|
|
211
413
|
|
|
212
414
|
**Replace**:
|
|
@@ -217,11 +419,13 @@ claude mcp add --transport stdio ampeco-api \
|
|
|
217
419
|
- NPX downloads and caches the package automatically
|
|
218
420
|
- No source code or build required
|
|
219
421
|
- Works from any directory
|
|
422
|
+
- Add `--emulate-resources-via-tools` for Claude Desktop compatibility
|
|
220
423
|
|
|
221
424
|
#### Option 2: Manual Configuration
|
|
222
425
|
|
|
223
426
|
Create `.mcp.json` in your project or home directory:
|
|
224
427
|
|
|
428
|
+
**Native Resources Mode**:
|
|
225
429
|
```json
|
|
226
430
|
{
|
|
227
431
|
"mcpServers": {
|
|
@@ -243,6 +447,29 @@ Create `.mcp.json` in your project or home directory:
|
|
|
243
447
|
}
|
|
244
448
|
```
|
|
245
449
|
|
|
450
|
+
**Tool Emulation Mode** (for Claude Desktop):
|
|
451
|
+
```json
|
|
452
|
+
{
|
|
453
|
+
"mcpServers": {
|
|
454
|
+
"ampeco-api": {
|
|
455
|
+
"type": "stdio",
|
|
456
|
+
"command": "npx",
|
|
457
|
+
"args": [
|
|
458
|
+
"-y",
|
|
459
|
+
"@ampeco/public-api-mcp",
|
|
460
|
+
"--stdio",
|
|
461
|
+
"--hostname",
|
|
462
|
+
"https://api.example.com",
|
|
463
|
+
"--emulate-resources-via-tools"
|
|
464
|
+
],
|
|
465
|
+
"env": {
|
|
466
|
+
"AMPECO_BEARER_TOKEN": "your-token-here"
|
|
467
|
+
}
|
|
468
|
+
}
|
|
469
|
+
}
|
|
470
|
+
}
|
|
471
|
+
```
|
|
472
|
+
|
|
246
473
|
**Using environment variables** (more secure):
|
|
247
474
|
```bash
|
|
248
475
|
export AMPECO_BEARER_TOKEN="your-token-here"
|
|
@@ -263,13 +490,20 @@ npm install -g @ampeco/public-api-mcp
|
|
|
263
490
|
#### 2. Add to Claude Code (One-Liner)
|
|
264
491
|
|
|
265
492
|
```bash
|
|
266
|
-
# Add globally installed server
|
|
493
|
+
# Add globally installed server (native resources)
|
|
267
494
|
claude mcp add --transport stdio ampeco-api \
|
|
268
495
|
--env AMPECO_BEARER_TOKEN=your-token-here \
|
|
269
496
|
-- ampeco-api-mcp --stdio --hostname https://api.example.com
|
|
497
|
+
|
|
498
|
+
# With tool emulation mode (for Claude Desktop)
|
|
499
|
+
claude mcp add --transport stdio ampeco-api \
|
|
500
|
+
--env AMPECO_BEARER_TOKEN=your-token-here \
|
|
501
|
+
-- ampeco-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools
|
|
270
502
|
```
|
|
271
503
|
|
|
272
504
|
**Or manual configuration** in `.mcp.json`:
|
|
505
|
+
|
|
506
|
+
**Native Resources Mode**:
|
|
273
507
|
```json
|
|
274
508
|
{
|
|
275
509
|
"mcpServers": {
|
|
@@ -283,6 +517,25 @@ claude mcp add --transport stdio ampeco-api \
|
|
|
283
517
|
}
|
|
284
518
|
```
|
|
285
519
|
|
|
520
|
+
**Tool Emulation Mode** (for Claude Desktop):
|
|
521
|
+
```json
|
|
522
|
+
{
|
|
523
|
+
"mcpServers": {
|
|
524
|
+
"ampeco-api": {
|
|
525
|
+
"type": "stdio",
|
|
526
|
+
"command": "ampeco-api-mcp",
|
|
527
|
+
"args": [
|
|
528
|
+
"--stdio",
|
|
529
|
+
"--hostname",
|
|
530
|
+
"https://api.example.com",
|
|
531
|
+
"--emulate-resources-via-tools"
|
|
532
|
+
],
|
|
533
|
+
"env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
}
|
|
537
|
+
```
|
|
538
|
+
|
|
286
539
|
### HTTP Mode (Remote Server)
|
|
287
540
|
|
|
288
541
|
For shared server access or when multiple clients need to connect:
|
|
@@ -290,12 +543,19 @@ For shared server access or when multiple clients need to connect:
|
|
|
290
543
|
#### 1. Start the Server
|
|
291
544
|
|
|
292
545
|
```bash
|
|
293
|
-
# Development mode
|
|
546
|
+
# Development mode (native resources)
|
|
294
547
|
PORT=3001 npm run dev:http
|
|
295
548
|
|
|
296
|
-
#
|
|
549
|
+
# Development mode (tool emulation)
|
|
550
|
+
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools
|
|
551
|
+
|
|
552
|
+
# Production mode (native resources)
|
|
297
553
|
npm run build # First time only
|
|
298
554
|
PORT=3001 npm start -- --http --port 3001
|
|
555
|
+
|
|
556
|
+
# Production mode (tool emulation)
|
|
557
|
+
npm run build # First time only
|
|
558
|
+
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools
|
|
299
559
|
```
|
|
300
560
|
|
|
301
561
|
#### 2. Add to Claude Code (One-Liner)
|
|
@@ -421,6 +681,38 @@ npm run build
|
|
|
421
681
|
https://api.example.com/health
|
|
422
682
|
```
|
|
423
683
|
|
|
684
|
+
## Building Desktop Extension (.mcpb)
|
|
685
|
+
|
|
686
|
+
To package this MCP server as a Desktop Extension for distribution:
|
|
687
|
+
|
|
688
|
+
```bash
|
|
689
|
+
# Build and package as .mcpb
|
|
690
|
+
npm run package:mcpb
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
This creates a `.mcpb` file (e.g., `ampeco-api-mcp-0.3.0.mcpb`) that can be:
|
|
694
|
+
- Distributed to users for manual installation
|
|
695
|
+
- Submitted to the official Claude Desktop extensions directory
|
|
696
|
+
- Shared within your organization
|
|
697
|
+
|
|
698
|
+
The `.mcpb` file is a self-contained bundle including:
|
|
699
|
+
- Compiled server code (`dist/`)
|
|
700
|
+
- All dependencies (via `package.json`)
|
|
701
|
+
- Extension metadata (`manifest.json`)
|
|
702
|
+
- Documentation (`README.md`)
|
|
703
|
+
|
|
704
|
+
### What's Included in the Bundle
|
|
705
|
+
|
|
706
|
+
The Desktop Extension bundle operates in **resource emulation mode** by default, which means:
|
|
707
|
+
- Full compatibility with Claude Desktop (no native resource support needed)
|
|
708
|
+
- `list_resources` and `read_resource` tools for endpoint discovery
|
|
709
|
+
- `api_request` tool for making authenticated API calls
|
|
710
|
+
- Automatic token management via environment variables
|
|
711
|
+
|
|
712
|
+
Users only need to provide two configuration values during installation:
|
|
713
|
+
1. **API Hostname**: The AMPECO API server URL
|
|
714
|
+
2. **Bearer Token**: Their authentication token
|
|
715
|
+
|
|
424
716
|
## Technology Stack
|
|
425
717
|
|
|
426
718
|
### Runtime
|
package/dist/build/index.js
CHANGED
|
@@ -62,6 +62,7 @@ async function build() {
|
|
|
62
62
|
// Step 3: Process each endpoint through the pipeline
|
|
63
63
|
console.log("\n[Step 3/6] Processing endpoints through pipeline...");
|
|
64
64
|
const optimizedEndpoints = [];
|
|
65
|
+
const responseSchemas = {};
|
|
65
66
|
for (const { path, method, operation } of rawEndpoints) {
|
|
66
67
|
let endpoint = {
|
|
67
68
|
path,
|
|
@@ -86,12 +87,41 @@ async function build() {
|
|
|
86
87
|
else if (operation.requestBody) {
|
|
87
88
|
endpoint.requestBody = operation.requestBody;
|
|
88
89
|
}
|
|
89
|
-
// Flatten responses
|
|
90
|
-
if (operation.responses
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
90
|
+
// Flatten responses and separate schemas
|
|
91
|
+
if (operation.responses) {
|
|
92
|
+
const flattenedResponses = config.enableFlattening
|
|
93
|
+
? flattenResponses(operation.responses)
|
|
94
|
+
: operation.responses;
|
|
95
|
+
// Extract schemas separately for transformation use
|
|
96
|
+
if (operation.operationId) {
|
|
97
|
+
responseSchemas[operation.operationId] = {};
|
|
98
|
+
for (const [statusCode, response] of Object.entries(flattenedResponses)) {
|
|
99
|
+
const typedResponse = response; // Type assertion for response object
|
|
100
|
+
// Store only description in endpoint (for MCP resources)
|
|
101
|
+
if (!endpoint.responses) {
|
|
102
|
+
endpoint.responses = {};
|
|
103
|
+
}
|
|
104
|
+
endpoint.responses[statusCode] = {
|
|
105
|
+
description: typedResponse.description || '',
|
|
106
|
+
};
|
|
107
|
+
// Store schema separately (for transformation)
|
|
108
|
+
if (typedResponse.content?.['application/json']?.schema) {
|
|
109
|
+
responseSchemas[operation.operationId][statusCode] = {
|
|
110
|
+
schema: typedResponse.content['application/json'].schema,
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
else {
|
|
116
|
+
// No operationId - just keep descriptions
|
|
117
|
+
endpoint.responses = {};
|
|
118
|
+
for (const [statusCode, response] of Object.entries(flattenedResponses)) {
|
|
119
|
+
const typedResponse = response; // Type assertion for response object
|
|
120
|
+
endpoint.responses[statusCode] = {
|
|
121
|
+
description: typedResponse.description || '',
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
}
|
|
95
125
|
}
|
|
96
126
|
// Optimize
|
|
97
127
|
if (config.enableOptimization) {
|
|
@@ -100,6 +130,7 @@ async function build() {
|
|
|
100
130
|
optimizedEndpoints.push(endpoint);
|
|
101
131
|
}
|
|
102
132
|
console.log(`✓ Processed ${optimizedEndpoints.length} endpoints`);
|
|
133
|
+
console.log(`✓ Extracted response schemas for ${Object.keys(responseSchemas).length} operations`);
|
|
103
134
|
// Step 4: Calculate size reduction
|
|
104
135
|
console.log("\n[Step 4/6] Calculating optimization statistics...");
|
|
105
136
|
const sizeStats = calculateSizeReduction(rawEndpoints, optimizedEndpoints);
|
|
@@ -108,6 +139,9 @@ async function build() {
|
|
|
108
139
|
console.log(`✓ Reduction: ${sizeStats.reductionPercent.toFixed(2)}%`);
|
|
109
140
|
// Step 5: Create build output
|
|
110
141
|
console.log("\n[Step 5/6] Creating build output...");
|
|
142
|
+
// Calculate response schema stats
|
|
143
|
+
const responseSchemasJson = JSON.stringify(responseSchemas);
|
|
144
|
+
const withSchemas = Object.values(responseSchemas).filter(schemaObj => Object.keys(schemaObj).length > 0).length;
|
|
111
145
|
const buildOutput = {
|
|
112
146
|
endpoints: optimizedEndpoints,
|
|
113
147
|
info: {
|
|
@@ -123,6 +157,12 @@ async function build() {
|
|
|
123
157
|
optimizedSize: sizeStats.optimizedSize,
|
|
124
158
|
reductionPercent: sizeStats.reductionPercent,
|
|
125
159
|
buildDuration: Date.now() - buildStartTime,
|
|
160
|
+
responseSchemas: {
|
|
161
|
+
total: Object.keys(responseSchemas).length,
|
|
162
|
+
withSchemas,
|
|
163
|
+
totalSchemaSize: responseSchemasJson.length,
|
|
164
|
+
averageSchemaSize: Math.round(responseSchemasJson.length / Math.max(1, withSchemas)),
|
|
165
|
+
},
|
|
126
166
|
},
|
|
127
167
|
};
|
|
128
168
|
// Step 6: Generate Zod schemas and write output files
|
|
@@ -133,10 +173,14 @@ async function build() {
|
|
|
133
173
|
console.log(`✓ Generated Zod schemas for ${optimizedEndpoints.length} endpoints`);
|
|
134
174
|
}
|
|
135
175
|
await mkdir(config.outputPath, { recursive: true });
|
|
136
|
-
// Write optimized endpoints
|
|
176
|
+
// Write optimized endpoints (without schemas)
|
|
137
177
|
const endpointsPath = resolve(config.outputPath, "endpoints.json");
|
|
138
178
|
await writeFile(endpointsPath, JSON.stringify(buildOutput, null, 2));
|
|
139
179
|
console.log(`✓ Written: ${endpointsPath}`);
|
|
180
|
+
// Write response schemas separately (for transformation use only)
|
|
181
|
+
const responseSchemasPath = resolve(config.outputPath, "response-schemas.json");
|
|
182
|
+
await writeFile(responseSchemasPath, JSON.stringify(responseSchemas, null, 2));
|
|
183
|
+
console.log(`✓ Written: ${responseSchemasPath} (${(responseSchemasJson.length / 1024).toFixed(1)}KB)`);
|
|
140
184
|
// Write Zod schemas
|
|
141
185
|
if (config.enableZodGeneration) {
|
|
142
186
|
const zodPath = resolve(config.outputPath, "schemas.ts");
|
|
@@ -154,6 +198,7 @@ async function build() {
|
|
|
154
198
|
console.log(`Total duration: ${buildDuration}ms`);
|
|
155
199
|
console.log(`Endpoints processed: ${optimizedEndpoints.length}`);
|
|
156
200
|
console.log(`Size reduction: ${sizeStats.reductionPercent.toFixed(2)}%`);
|
|
201
|
+
console.log(`Response schemas: ${withSchemas}/${Object.keys(responseSchemas).length} endpoints (${(responseSchemasJson.length / 1024).toFixed(1)}KB)`);
|
|
157
202
|
console.log("=".repeat(60));
|
|
158
203
|
console.log("");
|
|
159
204
|
// Restore original working directory
|
package/dist/build/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/build/optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,iBAAiB,CAc/E;
|
|
1
|
+
{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/build/optimizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,iBAAiB,CAc/E;AA8PD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAaA"}
|
package/dist/build/optimizer.js
CHANGED
|
@@ -45,31 +45,91 @@ function optimizeDescription(description) {
|
|
|
45
45
|
.trim();
|
|
46
46
|
}
|
|
47
47
|
/**
|
|
48
|
-
* Optimize parameters by
|
|
48
|
+
* Optimize parameters by grouping by type (path/query) and using object keys
|
|
49
|
+
*
|
|
50
|
+
* Transforms flat OpenAPI parameter array into a more intuitive structure:
|
|
51
|
+
* - Separates path and query parameters into distinct objects
|
|
52
|
+
* - Uses parameter name as the object key (eliminating redundant "name" field)
|
|
53
|
+
* - Maintains readable field names (type, description, required, etc.)
|
|
54
|
+
* - Reduces nesting while keeping the format clear and LLM-friendly
|
|
55
|
+
*
|
|
56
|
+
* Example:
|
|
57
|
+
* Before: [{"name": "userId", "in": "path", "required": true, "schema": {"type": "integer"}}]
|
|
58
|
+
* After: {"path": {"userId": {"type": "integer", "required": true}}}
|
|
49
59
|
*
|
|
50
60
|
* @param parameters - Array of parameters
|
|
51
|
-
* @returns Optimized parameters
|
|
61
|
+
* @returns Optimized parameters object with named keys
|
|
52
62
|
*/
|
|
53
63
|
function optimizeParameters(parameters) {
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
64
|
+
if (!parameters || parameters.length === 0) {
|
|
65
|
+
return undefined;
|
|
66
|
+
}
|
|
67
|
+
const pathParams = {};
|
|
68
|
+
const queryParams = {};
|
|
69
|
+
for (const param of parameters) {
|
|
70
|
+
const optimized = {};
|
|
71
|
+
// Add description if present
|
|
59
72
|
if (param.description) {
|
|
60
73
|
optimized.description = optimizeDescription(param.description);
|
|
61
74
|
}
|
|
62
|
-
|
|
63
|
-
optimized.required = true; // Only include if true
|
|
64
|
-
}
|
|
75
|
+
// Add schema info
|
|
65
76
|
if (param.schema) {
|
|
66
|
-
|
|
77
|
+
const schema = param.schema;
|
|
78
|
+
// For simple types, flatten the schema into the parameter
|
|
79
|
+
if (schema.type && !schema.properties && !schema.items && !schema.enum && !schema.oneOf && !schema.anyOf) {
|
|
80
|
+
optimized.type = schema.type;
|
|
81
|
+
// Add format if present
|
|
82
|
+
if (schema.format) {
|
|
83
|
+
optimized.format = schema.format;
|
|
84
|
+
}
|
|
85
|
+
// Add constraints
|
|
86
|
+
if (schema.minimum !== undefined)
|
|
87
|
+
optimized.minimum = schema.minimum;
|
|
88
|
+
if (schema.maximum !== undefined)
|
|
89
|
+
optimized.maximum = schema.maximum;
|
|
90
|
+
if (schema.minLength !== undefined)
|
|
91
|
+
optimized.minLength = schema.minLength;
|
|
92
|
+
if (schema.maxLength !== undefined)
|
|
93
|
+
optimized.maxLength = schema.maxLength;
|
|
94
|
+
if (schema.pattern)
|
|
95
|
+
optimized.pattern = schema.pattern;
|
|
96
|
+
if (schema.default !== undefined)
|
|
97
|
+
optimized.default = schema.default;
|
|
98
|
+
if (schema.example !== undefined)
|
|
99
|
+
optimized.example = schema.example;
|
|
100
|
+
if (schema.nullable)
|
|
101
|
+
optimized.nullable = true;
|
|
102
|
+
}
|
|
103
|
+
else {
|
|
104
|
+
// For complex schemas (objects, arrays, enums), keep as nested schema
|
|
105
|
+
optimized.schema = optimizeSchema(schema);
|
|
106
|
+
}
|
|
67
107
|
}
|
|
68
|
-
if (
|
|
108
|
+
// Only add required flag if true (omit for optional params)
|
|
109
|
+
if (param.required) {
|
|
110
|
+
optimized.required = true;
|
|
111
|
+
}
|
|
112
|
+
// Add example if present and not already in schema
|
|
113
|
+
if (param.example !== undefined && !optimized.example) {
|
|
69
114
|
optimized.example = param.example;
|
|
70
115
|
}
|
|
71
|
-
|
|
72
|
-
|
|
116
|
+
// Group by parameter location, using parameter name as key
|
|
117
|
+
if (param.in === 'path') {
|
|
118
|
+
pathParams[param.name] = optimized;
|
|
119
|
+
}
|
|
120
|
+
else if (param.in === 'query') {
|
|
121
|
+
queryParams[param.name] = optimized;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
// Build result object with only non-empty groups
|
|
125
|
+
const result = {};
|
|
126
|
+
if (Object.keys(pathParams).length > 0) {
|
|
127
|
+
result.path = pathParams;
|
|
128
|
+
}
|
|
129
|
+
if (Object.keys(queryParams).length > 0) {
|
|
130
|
+
result.query = queryParams;
|
|
131
|
+
}
|
|
132
|
+
return Object.keys(result).length > 0 ? result : undefined;
|
|
73
133
|
}
|
|
74
134
|
/**
|
|
75
135
|
* Optimize request body by removing unnecessary fields
|
|
@@ -115,21 +175,22 @@ function optimizeMediaType(mediaType) {
|
|
|
115
175
|
/**
|
|
116
176
|
* Optimize responses by removing unnecessary fields
|
|
117
177
|
*
|
|
178
|
+
* Response content schemas are stripped to save tokens (70-80% reduction).
|
|
179
|
+
* Only the description is kept for each status code, which is sufficient for
|
|
180
|
+
* understanding what to expect. The actual response data is more useful than
|
|
181
|
+
* the schema definition when working with APIs.
|
|
182
|
+
*
|
|
118
183
|
* @param responses - Response definitions
|
|
119
|
-
* @returns Optimized responses
|
|
184
|
+
* @returns Optimized responses with content stripped
|
|
120
185
|
*/
|
|
121
186
|
function optimizeResponses(responses) {
|
|
122
187
|
const optimized = {};
|
|
123
188
|
for (const [statusCode, response] of Object.entries(responses)) {
|
|
189
|
+
// Only keep the description, strip all content schemas
|
|
124
190
|
optimized[statusCode] = {
|
|
125
191
|
description: optimizeDescription(response.description),
|
|
192
|
+
// content field is intentionally omitted to save tokens
|
|
126
193
|
};
|
|
127
|
-
if (response.content) {
|
|
128
|
-
optimized[statusCode].content = {};
|
|
129
|
-
for (const [mediaType, content] of Object.entries(response.content)) {
|
|
130
|
-
optimized[statusCode].content[mediaType] = optimizeMediaType(content);
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
194
|
}
|
|
134
195
|
return optimized;
|
|
135
196
|
}
|