@ampeco/public-api-mcp 0.2.0

package/README.md

@@ -0,0 +1,734 @@
+# Public API MCP Server
+
+An MCP (Model Context Protocol) server that dynamically exposes a public API defined by an OpenAPI 3 specification.
+
+## Quick Start
+
+### Development (Stdio Mode)
+
+```bash
+# One-liner to add dev server (with hot reload)
+claude mcp add --transport stdio ampeco-api-dev \
+  --env AMPECO_BEARER_TOKEN=your-token-here \
+  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"
+```
+
+### Production (via NPX)
+
+```bash
+# 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
+```
+
+### HTTP Mode (Remote Server)
+
+```bash
+# Start the server first
+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 \
+  --header "Authorization: Bearer your-token-here"
+```
+
+See [Setting Up with Claude Code](#setting-up-with-claude-code) for detailed instructions and troubleshooting.
+
+## Overview
+
+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
+
+```bash
+# Install dependencies
+npm install
+
+# Run the build pipeline with default path
+npm run build
+
+# Run the build pipeline with custom OpenAPI spec path
+OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml npm run build
+
+# Or set it as an environment variable for multiple commands
+export OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml
+npm run build
+npm run dev
+```
+
+The build script:
+1. Parses the OpenAPI spec from the specified path (defaults to `../backend/main/docs/public.yaml`)
+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`
+
+### Development
+
+```bash
+# Type check without building
+npm run type-check
+
+# Run in development mode (build + start server)
+npm run dev
+```
+
+## Architecture
+
+### Build-Time Pipeline
+
+```
+OpenAPI Spec
+    ↓
+[Parser] Bundle & Resolve References
+    ↓
+[Extractor] Extract Endpoints & Security
+    ↓
+[Flattener] Flatten Schemas (allOf, nested objects)
+    ↓
+[Security] Embed Authentication Details
+    ↓
+[Optimizer] Minify & Optimize
+    ↓
+[Zod Generator] Generate Validation Schemas
+    ↓
+Generated Artifacts (endpoints.json, schemas.ts)
+```
+
+### Module Structure
+
+```
+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`
+
+#### 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
+
+### Running the Server
+
+```bash
+# Development mode (rebuild + start server)
+npm run dev
+
+# Production mode
+npm run build  # First time only
+npm start
+
+# Custom port
+PORT=3001 npm run dev
+```
+
+### Server Endpoints
+
+The server uses a hostname-based routing structure where the target API hostname is embedded in the URL path:
+
+- **`GET /health`**: Health check and server statistics
+- **`POST /{hostname}[/{protocol}]`**: MCP protocol endpoint with hostname routing
+  - `{hostname}`: Target API hostname (e.g., `api.example.com`)
+  - `{protocol}`: Optional protocol (`http` or `https`, defaults to `https`)
+
+**Examples:**
+- `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`
+
+## Setting Up with Claude Code
+
+The MCP server supports two transport modes:
+
+1. **Stdio Mode (Recommended)**: Direct process communication for local development and production
+2. **HTTP Mode**: Remote server access via HTTP transport
+
+### Stdio Mode (Local Development)
+
+For development with hot reloading and build integration:
+
+#### Option 1: One-Liner (Recommended)
+
+```bash
+# Add dev server with a single command
+claude mcp add --transport stdio ampeco-api-dev \
+  --env AMPECO_BEARER_TOKEN=your-token-here \
+  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"
+```
+
+**Replace**:
+- `/absolute/path/to/public-api-mcp` with your actual project path
+- `your-token-here` with your API token
+
+**Features**:
+- Automatically creates `.mcp.json` configuration
+- Rebuilds on each start for hot reloading
+- All build output redirected to stderr (clean protocol)
+
+#### Option 2: Manual Configuration
+
+If you prefer to manually edit configuration files:
+
+1. **Set environment variable** (optional, for substitution):
+```bash
+export AMPECO_BEARER_TOKEN="your-token-here"
+source ~/.bashrc  # or ~/.zshrc
+```
+
+2. **Create `.mcp.json` in project root**:
+```json
+{
+  "mcpServers": {
+    "ampeco-api-dev": {
+      "type": "stdio",
+      "command": "bash",
+      "args": ["-c", "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"],
+      "env": {"AMPECO_BEARER_TOKEN": "${AMPECO_BEARER_TOKEN}"}
+    }
+  }
+}
+```
+
+3. **Reload**: Claude Code will auto-detect the configuration
+
+### Stdio Mode (Production via NPX)
+
+For production use without needing the source code:
+
+#### Option 1: One-Liner (Recommended)
+
+```bash
+# 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
+```
+
+**Replace**:
+- `your-token-here` with your API token
+- `http://demo.charge.alex2.dev.ampeco.tech` with your target API hostname
+
+**Features**:
+- NPX downloads and caches the package automatically
+- No source code or build required
+- Works from any directory
+
+#### Option 2: Manual Configuration
+
+Create `.mcp.json` in your project or home directory:
+
+```json
+{
+  "mcpServers": {
+    "ampeco-api": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@ampeco/public-api-mcp",
+        "--stdio",
+        "--hostname",
+        "http://demo.charge.alex2.dev.ampeco.tech"
+      ],
+      "env": {
+        "AMPECO_BEARER_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+**Using environment variables** (more secure):
+```bash
+export AMPECO_BEARER_TOKEN="your-token-here"
+```
+
+Then use `"${AMPECO_BEARER_TOKEN}"` in the JSON config.
+
+### Stdio Mode (Production via Global Install)
+
+For faster startup without NPX overhead:
+
+#### 1. Install Globally
+
+```bash
+npm install -g @ampeco/public-api-mcp
+```
+
+#### 2. Add to Claude Code (One-Liner)
+
+```bash
+# 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
+```
+
+**Or manual configuration** in `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "ampeco-api": {
+      "type": "stdio",
+      "command": "ampeco-api-mcp",
+      "args": ["--stdio", "--hostname", "http://demo.charge.alex2.dev.ampeco.tech"],
+      "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
+    }
+  }
+}
+```
+
+### HTTP Mode (Remote Server)
+
+For shared server access or when multiple clients need to connect:
+
+#### 1. Start the Server
+
+```bash
+# Development mode
+PORT=3001 npm run dev:http
+
+# Production mode
+npm run build  # First time only
+PORT=3001 npm start -- --http --port 3001
+```
+
+#### 2. Add to Claude Code (One-Liner)
+
+```bash
+# Add HTTP server with a single command
+claude mcp add --transport http ampeco-api \
+  http://localhost:3001/demo.charge.alex2.dev.ampeco.tech \
+  --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 \
+  --header "Authorization: Bearer your-token-here"
+```
+
+**Or manual configuration** in `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "ampeco-api-http": {
+      "type": "http",
+      "url": "http://localhost:3001/demo.charge.alex2.dev.ampeco.tech",
+      "headers": {"Authorization": "Bearer your-token-here"}
+    }
+  }
+}
+```
+
+**Notes:**
+- Server must be running before connecting
+- Target API hostname is in the URL path
+- Optional `/http` or `/https` suffix controls target API protocol
+- Defaults to HTTPS if not specified
+
+### Comparison: Stdio vs HTTP Mode
+
+| Feature | Stdio Mode | HTTP Mode |
+|---------|-----------|-----------|
+| **Use Case** | Local development, single user | Remote access, multiple clients |
+| **Setup Complexity** | Simple (just config file) | Requires running server |
+| **Performance** | Faster (no HTTP overhead) | Slightly slower (HTTP latency) |
+| **Security** | More secure (local only) | Network exposure (use HTTPS in prod) |
+| **Hot Reload** | Yes (dev mode) | Requires server restart |
+| **Multi-Client** | No (one client at a time) | Yes (concurrent clients) |
+| **Memory Usage** | Lower (~30MB per instance) | Higher (~50MB + per-request) |
+
+**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
+
+**Problem**: Server not starting or connection fails
+```bash
+# List configured MCP servers
+claude mcp list
+
+# Check status
+claude mcp status ampeco-api-dev
+
+# Remove and re-add the server
+claude mcp remove ampeco-api-dev
+claude mcp add --transport stdio ampeco-api-dev \
+  --env AMPECO_BEARER_TOKEN=your-token \
+  -- bash -c "cd /path/to/public-api-mcp && npm run dev:stdio"
+
+# Verify the command works standalone
+cd /path/to/public-api-mcp
+AMPECO_BEARER_TOKEN=your-token npm run dev:stdio
+```
+
+**Problem**: Build output interfering with protocol
+- This is fixed in `dev:stdio` script which redirects build output to stderr
+- For production, run `npm run build` first, then use the compiled CLI
+
+**Problem**: Environment variables not loading
+```bash
+# Verify environment variable is set
+echo $AMPECO_BEARER_TOKEN
+
+# Reload shell configuration
+source ~/.bashrc  # or ~/.zshrc
+```
+
+#### HTTP Mode Issues
+
+**Problem**: Server not accessible
+```bash
+# Test server health
+curl http://localhost:3001/health
+
+# Check if port is in use
+lsof -i :3001
+
+# Try a different port
+PORT=3002 npm run dev:http
+```
+
+**Problem**: CORS errors
+- The server has CORS enabled for all origins
+- Check browser console for specific error messages
+
+#### General Issues
+
+**Problem**: Endpoints not loading
+```bash
+# Verify build artifacts exist
+ls -la src/generated/
+
+# Rebuild if needed
+npm run build
+```
+
+**Problem**: Authentication errors
+- Verify your `AMPECO_BEARER_TOKEN` is correct
+- Check the token has proper permissions for the API
+- Test the token directly with the API:
+  ```bash
+  curl -H "Authorization: Bearer your-token" \
+    http://demo.charge.alex2.dev.ampeco.tech/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
+- **Language**: TypeScript / Node.js (ES2022 modules)
+- **Server**: Express
+- **MCP SDK**: `@modelcontextprotocol/sdk`
+- **HTTP Client**: `node-fetch`
+- **Validation**: `zod`
+
+### Build-Time
+- **OpenAPI Parser**: `@readme/openapi-parser`
+- **Build Tools**: tsx, TypeScript compiler
+
+### Development
+- **Type Checking**: TypeScript (strict mode)
+- **Testing**: Vitest (planned)
+
+## License
+
+MIT