@ampeco/public-api-mcp 0.2.0 → 0.2.2

package/README.md

@@ -19,7 +19,7 @@ claude mcp add --transport stdio ampeco-api-dev \
 # One-liner to add production server
 claude mcp add --transport stdio ampeco-api \
   --env AMPECO_BEARER_TOKEN=your-token-here \
-  -- npx -y @ampeco/public-api-mcp --stdio --hostname http://demo.charge.alex2.dev.ampeco.tech
+  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com
 ```
 
 ### HTTP Mode (Remote Server)
@@ -30,7 +30,7 @@ PORT=3001 npm run dev:http
 
 # Then add to Claude Code
 claude mcp add --transport http ampeco-api \
-  http://localhost:3001/demo.charge.alex2.dev.ampeco.tech \
+  http://localhost:3001/api.example.com \
   --header "Authorization: Bearer your-token-here"
 ```
 
@@ -40,83 +40,6 @@ See [Setting Up with Claude Code](#setting-up-with-claude-code) for detailed ins
 
 This project transforms OpenAPI specifications into optimized, self-contained API definitions that can be served through the Model Context Protocol. It features a sophisticated build pipeline that processes OpenAPI specs at build time to minimize runtime overhead and reduce token usage.
 
-## Phase 1: Build Pipeline Foundation ✅
-
-### Completed Features
-
-#### 1. OpenAPI Parsing Module with Dereferencing
-- ✅ Loads and bundles OpenAPI 3 specifications (JSON/YAML)
-- ✅ Resolves external file references
-- ✅ Handles circular references automatically
-- ✅ Creates self-contained endpoint definitions
-
-**Location**: `src/build/parser.ts`
-
-#### 2. Schema Flattening
-- ✅ Flattens `allOf` compositions by merging properties
-- ✅ Resolves nested schemas to reduce complexity
-- ✅ Handles `anyOf`, `oneOf`, and complex schema constructs
-- ✅ Deep merging of object properties
-
-**Location**: `src/build/flattener.ts`
-
-#### 3. Security Embedding Logic
-- ✅ Embeds full security scheme details per endpoint
-- ✅ Includes authentication type, scheme, and usage instructions
-- ✅ Eliminates references to shared security components
-- ✅ Generates human-readable authentication descriptions
-
-**Location**: `src/build/security-embedder.ts`
-
-#### 4. Optimization and Minification
-- ✅ Removes redundant whitespace and empty keys
-- ✅ Optimizes schema definitions
-- ✅ **Achieved 22.39% size reduction** on target API
-- ✅ Calculates and reports optimization statistics
-
-**Location**: `src/build/optimizer.ts`
-
-#### 5. Zod Schema Generation
-- ✅ Converts OpenAPI schemas to Zod validation schemas
-- ✅ Supports complex types, enums, unions, and validation rules
-- ✅ Handles edge cases (null enums, single-element unions, number enums)
-- ✅ Generates TypeScript code for runtime validation
-
-**Location**: `src/build/zod-generator.ts`
-
-### Build Statistics
-
-Successfully processed the AMPECO.CHARGE Public API (v3.96.4):
-
-```
-Total Endpoints:    443
-Original Size:      809,161 bytes
-Optimized Size:     628,009 bytes
-Size Reduction:     22.39%
-Build Duration:     ~1 second
-```
-
-### Generated Artifacts
-
-The build pipeline produces three files in `src/generated/`:
-
-1. **`endpoints.json`** (1.2MB)
-   - Optimized endpoint definitions
-   - Fully dereferenced schemas
-   - Embedded security requirements
-   - API metadata and build statistics
-
-2. **`schemas.ts`** (122KB)
-   - Generated Zod validation schemas
-   - Type-safe parameter validation
-   - Request body schemas
-   - Auto-generated from OpenAPI spec
-
-3. **`build-stats.json`**
-   - Build metrics
-   - Optimization statistics
-   - Performance data
-
 ## Usage
 
 ### Running the Build Pipeline
@@ -138,14 +61,13 @@ npm run dev
 ```
 
 The build script:
-1. Parses the OpenAPI spec from the specified path (defaults to `../backend/main/docs/public.yaml`)
+1. Parses the OpenAPI spec from the specified path
 2. Processes all endpoints through the optimization pipeline
 3. Generates Zod schemas for runtime validation
 4. Outputs optimized artifacts to `src/generated/`
 
 **Configuration Options:**
 - **`OPENAPI_SPEC_PATH`**: Path to the OpenAPI YAML/JSON file (relative or absolute)
-  - Default: `../backend/main/docs/public.yaml`
   - Can be set as an environment variable or passed directly to npm commands
   - Used by both `npm run build` and `npm run dev`
 
@@ -172,8 +94,6 @@ OpenAPI Spec
     ↓
 [Flattener] Flatten Schemas (allOf, nested objects)
     ↓
-[Security] Embed Authentication Details
-    ↓
 [Optimizer] Minify & Optimize
     ↓
 [Zod Generator] Generate Validation Schemas
@@ -181,115 +101,16 @@ OpenAPI Spec
 Generated Artifacts (endpoints.json, schemas.ts)
 ```
 
-### Module Structure
+### MCP Server
 
-```
-src/
-├── build/                    # Build-time pipeline
-│   ├── index.ts             # Pipeline orchestrator
-│   ├── parser.ts            # OpenAPI parsing & bundling
-│   ├── flattener.ts         # Schema flattening logic
-│   ├── security-embedder.ts # Security details embedding
-│   ├── optimizer.ts         # Optimization & minification
-│   ├── zod-generator.ts     # Zod schema generation
-│   └── types.ts             # Build pipeline types
-│
-├── cli/                     # CLI entry point
-│   └── index.ts             # Argument parsing & mode selection
-│
-├── server/                  # Runtime MCP server
-│   ├── factory.ts           # Shared server creation logic
-│   ├── loader.ts            # Endpoint loading module
-│   ├── prompts.ts           # Workflow prompt handlers
-│   ├── stdio.ts             # Stdio transport server
-│   ├── http.ts              # HTTP transport server
-│   ├── index.ts             # (Legacy - kept for reference)
-│   └── factory.test.ts      # Unit tests
-│
-└── generated/               # Build output (gitignored)
-    ├── endpoints.json       # Optimized endpoints (~1.2MB)
-    ├── schemas.ts           # Zod validation schemas (~122KB)
-    └── build-stats.json     # Build statistics
-```
-
-## Key Features
-
-### Zero Runtime Overhead
-All OpenAPI processing happens at build time. The server loads pre-processed, optimized data instantly.
-
-### Comprehensive Dereferencing
-Resolves all `$ref` pointers (external files, internal components) to create fully self-contained endpoint definitions.
-
-### Intelligent Schema Flattening
-- Merges `allOf` compositions
-- Resolves nested complexity
-- Handles circular references
-
-### Embedded Security Documentation
-Each endpoint includes complete authentication instructions:
-- Bearer token: "Include token in Authorization header as: Authorization: Bearer <token>"
-- API key, OAuth, and other schemes fully documented
-
-### Token Optimization
-Aggressive optimization targeting 50-70% token reduction through:
-- Redundant data removal
-- Whitespace minimization
-- Essential-only field retention
-
-### Type Safety
-- Generated Zod schemas for runtime validation
-- TypeScript types for compile-time safety
-- Validates parameters before API calls
-
-## Phase 2: MCP Server Core ✅
-
-### Completed Features
-
-#### 1. Streamable HTTP Transport Server
-- ✅ Express-based HTTP server with MCP transport
-- ✅ Stateless design (no session management)
-- ✅ CORS-enabled for browser clients
-- ✅ Health check endpoint at `/health`
-- ✅ MCP protocol endpoint at `/mcp`
-
-**Location**: `src/server/index.ts`
+The server provides a complete MCP implementation for accessing your OpenAPI-defined API:
 
-#### 2. Dynamic Resource Handlers
-- ✅ **Resources List**: Exposes all 443 API endpoints as MCP resources
-- ✅ **Resources Read**: Returns complete endpoint details
-  - Path, method, operationId, descriptions
-  - Request/response schemas (flattened and optimized)
-  - Embedded security information
-  - Parameter definitions with validation rules
-
-#### 3. HTTP Request Tool
-- ✅ Fully typed `api_request` tool with Zod validation
-- ✅ Parameters:
-  - `hostname`: API base URL
-  - `bearer_token`: Authentication token
-  - `endpoint`: API path with parameter substitution
-  - `method`: HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
-  - `path_params`: Path parameter values
-  - `query_params`: Query string parameters
-  - `body`: Request payload
-  - `headers`: Additional HTTP headers
-- ✅ Automatic Bearer token authentication
-- ✅ Structured responses (status, headers, body)
-
-#### 4. Error Handling & Logging
-- ✅ Request/response logging to console
-- ✅ Graceful error handling with JSON-RPC error responses
-- ✅ Connection cleanup on request close
-
-### Server Features
-
-**Stateless Architecture**: No session state required - hostname and auth tokens provided per request
-
-**Zero Configuration**: No config files needed - all parameters passed at runtime
-
-**Fast Startup**: Pre-processed endpoint data loads instantly
-
-**MCP Protocol Compliance**: Fully implements MCP Streamable HTTP transport specification
+- **Dual Transport Support**: Both Stdio (local) and HTTP (remote) transports
+- **Dynamic Resources**: All API endpoints exposed as MCP resources with full schema details
+- **API Request Tool**: Fully typed `api_request` tool with automatic authentication and parameter validation
+- **Stateless Architecture**: No session state required - all parameters provided per request
+- **Zero Configuration**: Pre-processed data loads instantly, no config files needed
+- **MCP Protocol Compliance**: Full implementation of MCP Streamable HTTP transport specification
 
 ### Running the Server
 
@@ -318,7 +139,7 @@ The server uses a hostname-based routing structure where the target API hostname
 - `POST /api.example.com` → Routes to `https://api.example.com`
 - `POST /api.example.com/https` → Routes to `https://api.example.com`
 - `POST /api.example.com/http` → Routes to `http://api.example.com`
-- `POST /demo.charge.dev.ampeco.tech/http` → Routes to `http://demo.charge.dev.ampeco.tech`
+- `POST /internal.api.company.com/http` → Routes to `http://internal.api.company.com`
 
 ## Setting Up with Claude Code
 
@@ -385,12 +206,12 @@ For production use without needing the source code:
 # Add production server with a single command
 claude mcp add --transport stdio ampeco-api \
   --env AMPECO_BEARER_TOKEN=your-token-here \
-  -- npx -y @ampeco/public-api-mcp --stdio --hostname http://demo.charge.alex2.dev.ampeco.tech
+  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com
 ```
 
 **Replace**:
 - `your-token-here` with your API token
-- `http://demo.charge.alex2.dev.ampeco.tech` with your target API hostname
+- `https://api.example.com` with your target API hostname
 
 **Features**:
 - NPX downloads and caches the package automatically
@@ -412,7 +233,7 @@ Create `.mcp.json` in your project or home directory:
         "@ampeco/public-api-mcp",
         "--stdio",
         "--hostname",
-        "http://demo.charge.alex2.dev.ampeco.tech"
+        "https://api.example.com"
       ],
       "env": {
         "AMPECO_BEARER_TOKEN": "your-token-here"
@@ -445,7 +266,7 @@ npm install -g @ampeco/public-api-mcp
 # Add globally installed server
 claude mcp add --transport stdio ampeco-api \
   --env AMPECO_BEARER_TOKEN=your-token-here \
-  -- ampeco-api-mcp --stdio --hostname http://demo.charge.alex2.dev.ampeco.tech
+  -- ampeco-api-mcp --stdio --hostname https://api.example.com
 ```
 
 **Or manual configuration** in `.mcp.json`:
@@ -455,7 +276,7 @@ claude mcp add --transport stdio ampeco-api \
     "ampeco-api": {
       "type": "stdio",
       "command": "ampeco-api-mcp",
-      "args": ["--stdio", "--hostname", "http://demo.charge.alex2.dev.ampeco.tech"],
+      "args": ["--stdio", "--hostname", "https://api.example.com"],
       "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
     }
   }
@@ -482,14 +303,14 @@ PORT=3001 npm start -- --http --port 3001
 ```bash
 # Add HTTP server with a single command
 claude mcp add --transport http ampeco-api \
-  http://localhost:3001/demo.charge.alex2.dev.ampeco.tech \
+  http://localhost:3001/api.example.com \
   --header "Authorization: Bearer your-token-here"
 ```
 
 **With protocol override** (use HTTP for target API instead of HTTPS):
 ```bash
 claude mcp add --transport http ampeco-api \
-  http://localhost:3001/demo.charge.alex2.dev.ampeco.tech/http \
+  http://localhost:3001/api.example.com/http \
   --header "Authorization: Bearer your-token-here"
 ```
 
@@ -499,7 +320,7 @@ claude mcp add --transport http ampeco-api \
   "mcpServers": {
     "ampeco-api-http": {
       "type": "http",
-      "url": "http://localhost:3001/demo.charge.alex2.dev.ampeco.tech",
+      "url": "http://localhost:3001/api.example.com",
       "headers": {"Authorization": "Bearer your-token-here"}
     }
   }
@@ -526,23 +347,6 @@ claude mcp add --transport http ampeco-api \
 
 **Recommendation**: Use **stdio mode** for development and single-user production. Use **HTTP mode** for shared servers or when multiple clients need concurrent access.
 
-### Configuration File Locations
-
-MCP configuration files can be placed at different scopes:
-
-| Scope | Location | Priority | Use Case |
-|-------|----------|----------|----------|
-| **Project** | `.mcp.json` in project root | Highest | Project-specific servers |
-| **User** | `~/.mcp.json` | Medium | Personal cross-project servers |
-| **Claude Code** | Per OS (see below) | N/A | Claude Code-specific |
-
-**Claude Code Configuration Locations:**
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
-
-**Recommendation**: Use project `.mcp.json` for development, user `~/.mcp.json` for production.
-
 ### Troubleshooting
 
 #### Stdio Mode Issues
@@ -614,104 +418,9 @@ npm run build
 - Test the token directly with the API:
   ```bash
   curl -H "Authorization: Bearer your-token" \
-    http://demo.charge.alex2.dev.ampeco.tech/health
+    https://api.example.com/health
   ```
 
-### Other MCP Clients (Claude Desktop, etc.)
-
-For other MCP-enabled tools like Claude Desktop, the configuration is similar:
-
-#### Stdio Configuration
-
-**Location**:
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "ampeco-api": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@ampeco/public-api-mcp",
-        "--stdio",
-        "--hostname",
-        "http://demo.charge.alex2.dev.ampeco.tech"
-      ],
-      "env": {
-        "AMPECO_BEARER_TOKEN": "your-api-token-here"
-      }
-    }
-  }
-}
-```
-
-#### HTTP Configuration
-
-If your MCP client supports HTTP transport:
-
-```json
-{
-  "mcpServers": {
-    "ampeco-api": {
-      "type": "http",
-      "url": "http://localhost:3001/demo.charge.alex2.dev.ampeco.tech",
-      "headers": {
-        "Authorization": "Bearer your-api-token-here"
-      }
-    }
-  }
-}
-```
-
-**Server URL Format**: `http://localhost:{port}/{api-hostname}/{protocol}`
-- `{api-hostname}`: Your target API's hostname
-- `{protocol}`: Optional - `http` or `https` (defaults to `https`)
-
-### Testing the Server
-
-```bash
-# Check server health
-curl http://localhost:3001/health
-
-# Test MCP connection with hostname routing
-curl -X POST http://localhost:3001/api.example.com \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer your-api-token" \
-  -H "Accept: application/json, text/event-stream" \
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "initialize",
-    "params": {
-      "protocolVersion": "2025-06-18",
-      "capabilities": {},
-      "clientInfo": {
-        "name": "test-client",
-        "version": "1.0.0"
-      }
-    }
-  }'
-```
-
-## Next Steps
-
-### Phase 3: Optimization & Polish
-- [ ] Improve token optimization (target 50-70% reduction)
-- [ ] Enhanced description generation with examples
-- [ ] Performance testing and optimization
-- [ ] Comprehensive test suite
-- [ ] Documentation and usage examples
-
-### Phase 4: Production Readiness
-- [ ] Observability and monitoring integration
-- [ ] Error handling refinement
-- [ ] Validation accuracy testing
-- [ ] Production deployment configuration
-- [ ] Performance benchmarking
-
 ## Technology Stack
 
 ### Runtime

package/dist/generated/build-stats.json

@@ -3,5 +3,5 @@
   "originalSize": 815026,
   "optimizedSize": 537657,
   "reductionPercent": 34.03,
-  "buildDuration": 584
+  "buildDuration": 599
 }

package/dist/generated/endpoints.json

@@ -32156,7 +32156,7 @@
   ],
   "info": {
     "title": "AMPECO.CHARGE Public API",
-    "version": "3.97.2",
+    "version": "3.97.3",
     "description": "AMPECO.CHARGE Public API provides you with the option to use AMPECO.CHARGE's backend in a server-to-server manner\n"
   },
   "servers": [
@@ -32170,12 +32170,12 @@
       }
     }
   ],
-  "buildTimestamp": "2025-10-10T12:09:54.932Z",
+  "buildTimestamp": "2025-10-10T13:15:02.845Z",
   "stats": {
     "totalEndpoints": 445,
     "originalSize": 815026,
     "optimizedSize": 537657,
     "reductionPercent": 34.03,
-    "buildDuration": 584
+    "buildDuration": 599
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampeco/public-api-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP server that dynamically exposes the AMPECO.CHARGE Public API defined by an OpenAPI 3 specification",
   "type": "module",
   "main": "dist/cli/index.js",