MCPHy

# LLM Enhancement Guide MCPhy uses GPT-4 to intelligently understand and enhance your API specifications, providing richer documentation and better conversational experiences. ## Table of Contents - [Overview](#overview) - [How It Works](#how-it-works) - [Benefits](#benefits) - [Setup](#setup) - [OpenAPI/Swagger Enhancement](#openapiswagger-enhancement) - [Postman Collection Enhancement](#postman-collection-enhancement) - [Cost & Performance](#cost--performance) - [Troubleshooting](#troubleshooting) --- ## Overview LLM (Large Language Model) enhancement is an **optional feature** that uses OpenAI's GPT-4 to analyze your API specification and generate: - 📝 **Enhanced descriptions** - More natural, user-friendly language - 🔍 **Better parameter docs** - Context-aware explanations - 💡 **Usage examples** - Practical guidance for endpoints - 🎯 **Smart summaries** - Clear, concise operation descriptions - 🔗 **Workflow discovery** - Common patterns and use cases ### When to Use LLM Enhancement **✅ Use LLM enhancement when:** - Your API spec has minimal documentation - You want more natural language descriptions - You're using Postman collections (highly recommended) - You want to improve developer experience - Your spec is auto-generated with generic descriptions **❌ Skip LLM enhancement when:** - Your spec already has comprehensive documentation - You don't have an OpenAI API key - You want to minimize costs - You prefer full control over documentation --- ## How It Works ### Processing Flow ``` 1. Parse API Spec └─> Basic validation and structure extraction 2. Analyze with GPT-4 (if key provided) └─> Send API overview and sample endpoints └─> GPT-4 analyzes structure and purpose └─> Returns enhanced descriptions 3. Apply Enhancements └─> Merge LLM suggestions with original spec └─> Only enhance missing/minimal documentation └─> Preserve existing rich documentation 4. Generate MCP Manifest └─> Create enhanced manifest for MCP server ``` ### Smart Enhancement MCPhy is intelligent about enhancements: - ✅ **Only enhances when needed** - Preserves good existing docs - ✅ **Non-destructive** - Original spec file unchanged - ✅ **Graceful fallback** - Works if LLM fails - ✅ **One-time cost** - Only runs during initialization --- ## Benefits ### For OpenAPI/Swagger Specs **Before Enhancement:** ```yaml paths: /users/{id}: get: summary: Get User parameters: - name: id in: path required: true ``` **After Enhancement:** ```yaml paths: /users/{id}: get: summary: Retrieve detailed information about a specific user description: Fetches a user profile including personal information, account status, and preferences. Returns 404 if user not found. x-usage-example: Use this endpoint to display user profiles or verify user existence parameters: - name: id in: path required: true description: The unique identifier of the user. Must be a valid UUID. ``` ### For Postman Collections **Before Enhancement:** ```json { "name": "Create Order", "request": { "method": "POST", "url": "{{baseUrl}}/orders" } } ``` **After Enhancement:** ```json { "name": "Create Order", "summary": "Create a new order for a customer", "description": "Submits a new order with items, shipping address, and payment method. Validates inventory availability before creation. Returns order ID and estimated delivery date.", "x-usage-example": "Use this endpoint after adding items to cart and collecting shipping/payment information", "parameters": [...] } ``` --- ## Setup ### 1. Get OpenAI API Key Visit [OpenAI Platform](https://platform.openai.com/api-keys) and: 1. Sign up or log in 2. Navigate to API keys 3. Create new secret key 4. Copy the key (starts with `sk-`) ### 2. Configure MCPhy **Option A: During initialization** ```bash mcphy init -f api-spec.yaml # Enter your OpenAI API key when prompted ``` **Option B: Environment variable** ```bash export OPENAI_API_KEY=sk-your-key-here mcphy init -f api-spec.yaml ``` **Option C: Add to config** Edit `.mcphy.json`: ```json { "openaiApiKey": "sk-your-key-here", ... } ``` ### 3. Verify Enhancement Look for this message during initialization: ``` ✓ OpenAI enabled for enhanced API parsing ✓ Enhancing API understanding with LLM... ✓ LLM enhancement completed ``` --- ## OpenAPI/Swagger Enhancement ### What Gets Enhanced #### 1. API Description - **Before**: Generic or missing - **After**: Clear overview of API purpose and capabilities #### 2. Endpoint Descriptions - **Before**: Short or auto-generated - **After**: Detailed explanations of functionality #### 3. Parameter Documentation - **Before**: Just type and required flag - **After**: Context, format requirements, examples #### 4. Usage Examples - **Added**: Practical guidance on when/how to use endpoints #### 5. Operation Summaries - **Before**: Terse technical names - **After**: Clear, user-friendly descriptions ### Example Enhancement **Original Spec:** ```yaml openapi: 3.0.0 info: title: Pet Store API version: 1.0.0 description: A simple pet store API paths: /pets: get: summary: List pets parameters: - name: limit in: query schema: type: integer ``` **Enhanced Spec:** ```yaml openapi: 3.0.0 info: title: Pet Store API version: 1.0.0 description: A comprehensive pet store management API that allows you to browse available pets, manage inventory, process adoptions, and track pet care records. Ideal for pet stores, shelters, and veterinary clinics. paths: /pets: get: summary: Retrieve a paginated list of available pets description: Returns a collection of pets currently available for adoption or purchase. Supports pagination and filtering by species, age, and availability status. Use this endpoint to display pets in your storefront or search interface. x-usage-example: Call this endpoint when loading the pet catalog page or implementing search functionality parameters: - name: limit in: query description: Maximum number of pets to return per page. Defaults to 20. Use with offset for pagination through large result sets. schema: type: integer minimum: 1 maximum: 100 ``` ### Smart Preservation LLM enhancement is smart about what to enhance: ```yaml # Case 1: Short description → Enhanced summary: Get users # Becomes: summary: Retrieve a paginated list of all registered users # Case 2: Already detailed → Preserved description: | Retrieves comprehensive user information including profile data, account status, permissions, and recent activity. This endpoint requires admin privileges and returns paginated results. # Stays the same (already good!) ``` --- ## Postman Collection Enhancement ### Why It's More Important Postman collections typically have: - ❌ Minimal descriptions (just request names) - ❌ No parameter documentation - ❌ Missing type information - ❌ No relationship context **LLM enhancement is HIGHLY RECOMMENDED for Postman collections.** ### What Gets Enhanced #### 1. Collection Understanding Analyzes overall structure and purpose #### 2. Endpoint Intent Infers what each endpoint does from: - Request name - URL structure - HTTP method - Request body examples - Folder organization #### 3. Parameter Documentation Generates descriptions for: - Path parameters - Query parameters - Headers - Body fields #### 4. Type Inference Better type detection from examples #### 5. Workflow Patterns Identifies common API workflows ### Example Enhancement **Original Postman:** ```json { "info": { "name": "User API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Get User", "request": { "method": "GET", "url": "{{baseUrl}}/users/{{userId}}" } }, { "name": "Update User", "request": { "method": "PUT", "url": "{{baseUrl}}/users/{{userId}}", "body": { "mode": "raw", "raw": "{\"name\": \"John\", \"email\": \"john@example.com\"}" } } } ] } ``` **Enhanced Result:** ```json { "info": { "title": "User API", "description": "A user management API providing endpoints for creating, retrieving, updating, and managing user accounts. Supports full CRUD operations with authentication and authorization controls.", "version": "1.0.0" }, "paths": { "/users/{userId}": { "get": { "summary": "Retrieve a specific user by their unique identifier", "description": "Fetches detailed information about a user including profile data, contact information, and account status. Requires valid authentication token. Returns 404 if user not found.", "x-usage-example": "Use this endpoint to display user profiles, verify user existence, or fetch user data for updates", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "The unique identifier of the user to retrieve. Must be a valid user ID from the system.", "schema": { "type": "string" } } ] }, "put": { "summary": "Update user information", "description": "Modifies user profile data including name, email, and preferences. Validates email format and ensures unique email addresses. Requires user to be authenticated and authorized to update this user.", "x-usage-example": "Use this endpoint when processing profile update forms or administrative user management operations", "parameters": [...], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The user's full name. Must be 2-100 characters." }, "email": { "type": "string", "description": "User's email address. Must be valid format and unique in the system." } } } } } } } } } } ``` --- ## Cost & Performance ### OpenAI API Costs **GPT-4 Pricing (as of 2024):** - Input: ~$0.03 per 1K tokens - Output: ~$0.06 per 1K tokens **Typical Costs per API:** - Small API (10 endpoints): $0.01 - 0.05 - Medium API (50 endpoints): $0.05 - 0.15 - Large API (200+ endpoints): $0.15 - 0.50 **💡 Cost happens only once** - During initialization, not per query! ### Performance - **Enhancement time**: 2-10 seconds depending on API size - **Runs once**: Only during `mcphy init` - **No runtime impact**: Doesn't affect server performance - **Cached results**: Stored in manifest ### Optimization Tips 1. **Only enhance when needed** - Skip if docs are already good 2. **Use for development** - Can disable for production 3. **Share enhanced manifests** - Team members don't need API keys 4. **One-time investment** - Cost is per-project, not per-user --- ## Troubleshooting ### Enhancement Failed **Error:** ``` ⚠️ LLM enhancement failed, using basic parsing ``` **Common Causes:** 1. **Invalid API key** - Check it starts with `sk-` 2. **Rate limit** - Too many requests to OpenAI 3. **Network issues** - Can't reach OpenAI servers 4. **Billing issue** - No credits or payment method **Solutions:** ```bash # Verify API key echo $OPENAI_API_KEY # Check OpenAI status curl https://status.openai.com # Try again with explicit key mcphy init -f api.yaml # (Enter key when prompted) ``` **Note:** MCPhy automatically falls back to basic parsing, so initialization still succeeds! ### Enhancement Didn't Help **Issue:** Enhancements seem generic or unhelpful **Possible Reasons:** 1. **Original spec too sparse** - Not enough context for LLM 2. **Unclear naming** - Endpoints named "Request 1", "API Call" 3. **No examples** - Missing request/response examples **Solutions:** 1. Add better names to endpoints before exporting 2. Include descriptions in your original spec 3. Provide realistic request body examples 4. Use meaningful folder structure (Postman) ### Too Expensive **Issue:** OpenAI costs adding up **Solutions:** 1. **Skip for well-documented APIs** - Only use when needed 2. **Use for initialization only** - Not required for serving 3. **Share .mcphy-manifest.json** - Team members reuse 4. **Switch to GPT-3.5** - Modify source (lower quality but cheaper) ### Want More Control **Issue:** LLM changing things you don't want changed **Solutions:** 1. **Enhance original spec first** - LLM preserves good docs 2. **Edit manifest after** - Modify `.mcphy-manifest.json` 3. **Disable LLM** - Skip API key to use basic parsing 4. **Selective enhancement** - Edit source to target specific fields --- ## FAQ **Q: Is LLM enhancement required?** A: No, it's completely optional. MCPhy works great without it. **Q: Does it change my original files?** A: No, original spec files are never modified. Enhancements are stored in the manifest. **Q: Can I edit the enhanced descriptions?** A: Yes! Edit `.mcphy-manifest.json` after initialization. **Q: What if I don't have an OpenAI key?** A: MCPhy works fine without it. You'll get basic parsing which is perfectly functional. **Q: Does it work offline?** A: No, LLM enhancement requires internet to call OpenAI API. Basic parsing works offline. **Q: How accurate are the enhancements?** A: Generally very good, but review important endpoints. GPT-4 infers based on patterns. **Q: Can I use a different LLM?** A: Currently only OpenAI GPT-4. You can modify the source to use other providers. **Q: Does it send my data to OpenAI?** A: Yes, your API spec structure (paths, names) is sent. No actual API data or credentials. --- ## Best Practices ### 1. Start with Good Naming ``` ❌ Bad: "API Call 1", "Request", "Test" ✅ Good: "Create User", "Get Order Details", "Update Payment Method" ``` ### 2. Add Minimal Descriptions Even short descriptions help LLM understand context: ```yaml paths: /orders: post: summary: Create order # Just this helps a lot! ``` ### 3. Include Examples ```json { "body": { "raw": "{\"name\": \"John\", \"age\": 30}" # LLM infers schema better } } ``` ### 4. Organize with Folders (Postman) ``` API Collection ├── Authentication # LLM understands these are auth endpoints ├── Users └── Orders ``` ### 5. Review Enhanced Results Check `.mcphy-manifest.json` after initialization and adjust if needed. --- ## Summary | Feature | OpenAPI/Swagger | Postman | |---------|----------------|---------| | **LLM Enhancement** | Recommended | Highly Recommended | | **Works Without** | ✅ Yes | ✅ Yes | | **Main Benefit** | Better descriptions | Essential for good parsing | | **Cost** | $0.01-0.50 per API | $0.01-0.50 per API | | **When Needed** | Sparse documentation | Always beneficial | --- **Ready to enhance your API?** [Get started with Quick Start Guide](./quick-start.md) **Need help?** [Check Troubleshooting](./troubleshooting.md) or [open an issue](https://github.com/sehmim/mcphy/issues)