framework-mcp 1.1.3 → 1.3.0

package/RELEASE_NOTES_v1.2.0.md

@@ -0,0 +1,396 @@
+# Framework MCP v1.2.0 Release Notes
+
+## 🚀 Major Release: Dual Architecture - DigitalOcean Deployment Support
+
+**Release Date**: August 2025  
+**Version**: 1.2.0  
+**Breaking Changes**: None (fully backward compatible)
+
+---
+
+## 🌟 Executive Summary
+
+Framework MCP v1.2.0 introduces **dual architecture support**, solving the critical DigitalOcean App Services deployment issue while maintaining full backward compatibility. This release enables both local MCP integration and cloud HTTP deployment through a shared core architecture.
+
+**Primary Achievement**: Solves the stdio vs HTTP binding conflict that prevented cloud deployment.
+
+---
+
+## 🏗️ Major New Features
+
+### **1. Dual Architecture Implementation**
+
+```
+                    [Shared Core Logic]
+                           |
+                    +------+------+
+                    |             |
+            [MCP Interface]   [HTTP Interface]  
+                    |             |
+               [stdio comm]   [Express.js]     
+                    |             |
+             [Claude Code]   [Cloud Deploy]
+```
+
+**Components**:
+- **Shared Core**: `CapabilityAnalyzer` + `SafeguardManager` with identical logic
+- **MCP Interface**: Refactored stdio-based server for Claude Code integration
+- **HTTP Interface**: Express.js REST API for cloud deployment
+
+### **2. Production-Ready HTTP API**
+
+**New REST Endpoints**:
+```
+POST   /api/validate-vendor-mapping    # Primary capability validation
+POST   /api/analyze-vendor-response    # Capability role determination  
+POST   /api/validate-coverage-claim    # Implementation claim validation
+GET    /api/safeguards                 # List all safeguards
+GET    /api/safeguards/:id             # Get safeguard details
+GET    /health                         # Platform health check
+GET    /api/metrics                    # Performance monitoring
+```
+
+**Production Features**:
+- ✅ **Health Checks**: Platform monitoring support (`/health`)
+- ✅ **CORS Enabled**: Web application integration
+- ✅ **Security Hardened**: Helmet, input validation, rate limiting ready
+- ✅ **Compression**: Optimized response sizes
+- ✅ **Error Handling**: Production-friendly error messages
+- ✅ **Performance Monitoring**: Real-time metrics at `/api/metrics`
+
+### **3. DigitalOcean App Services Support**
+
+**Complete Configuration**:
+- ✅ **HTTP Port Binding**: Port 8080 (not stdio)
+- ✅ **Health Check Endpoint**: `/health` with proper status codes
+- ✅ **Environment Variables**: Production configuration support
+- ✅ **Auto-Scaling**: Resource allocation configuration
+- ✅ **Deployment YAML**: Complete `.do/app.yaml` provided
+
+**Deployment Command**:
+```bash
+# Option 1: GitHub integration (recommended)
+# Connect branch: feature/dual-architecture-http-api
+
+# Option 2: doctl CLI
+doctl apps create .do/app.yaml
+```
+
+---
+
+## 🔧 Technical Enhancements
+
+### **Shared Core Architecture**
+
+**CapabilityAnalyzer Class**:
+- Extracted from MCP server implementation
+- Maintains all v1.1.3 performance optimizations (95% cache improvement)
+- Preserves domain validation and auto-downgrade logic
+- Identical functionality across MCP and HTTP interfaces
+
+**SafeguardManager Class**:
+- Centralized CIS safeguards data management
+- Intelligent caching with configurable TTL
+- Input validation and error handling
+- Support for implementation examples
+
+### **Interface Compatibility**
+
+**MCP Interface** (Preserved):
+```typescript
+// Exact same tool signatures
+validate_vendor_mapping(vendor_name, safeguard_id, claimed_capability, supporting_text)
+analyze_vendor_response(vendor_name, safeguard_id, response_text)
+validate_coverage_claim(vendor_name, safeguard_id, claimed_capability, response_text)
+get_safeguard_details(safeguard_id, include_examples)
+list_available_safeguards()
+```
+
+**HTTP Interface** (New):
+```bash
+# RESTful equivalent endpoints
+curl -X POST /api/validate-vendor-mapping -d '{"vendor_name":"...", "safeguard_id":"1.1", ...}'
+curl -X POST /api/analyze-vendor-response -d '{"vendor_name":"...", "safeguard_id":"5.1", ...}'
+curl -X POST /api/validate-coverage-claim -d '{"vendor_name":"...", "claimed_capability":"full", ...}'
+curl /api/safeguards/1.1?include_examples=true
+curl /api/safeguards
+```
+
+---
+
+## 📦 Package and Deployment Updates
+
+### **Package.json Enhancements**
+
+**New Scripts**:
+```json
+{
+  "start": "node dist/interfaces/http/http-server.js",      // Default: HTTP server
+  "start:mcp": "node dist/index.js",                       // MCP server
+  "start:http": "node dist/interfaces/http/http-server.js", // HTTP server
+  "dev": "tsc && npm run start:mcp",                       // MCP development
+  "dev:http": "tsc && npm run start:http"                  // HTTP development
+}
+```
+
+**Updated Dependencies**:
+```json
+{
+  "express": "^4.18.2",
+  "cors": "^2.8.5", 
+  "helmet": "^8.1.0",
+  "compression": "^1.8.1"
+}
+```
+
+**Main Entry Point**: 
+- **Default**: `dist/interfaces/http/http-server.js` (cloud-ready)
+- **MCP**: `dist/index.js` (Claude Code integration)
+
+### **Cloud Platform Support**
+
+**DigitalOcean App Services**:
+```yaml
+name: framework-mcp-api
+services:
+- name: api
+  run_command: npm run start:http
+  http_port: 8080
+  health_check:
+    http_path: /health
+```
+
+**Alternative Platforms**:
+- **Railway**: `railway up`
+- **Render**: Node.js + `npm run start:http`
+- **AWS App Runner**: HTTP service configuration
+- **Google Cloud Run**: Container deployment ready
+
+---
+
+## 🧪 Testing and Validation
+
+### **Dual Interface Testing**
+
+**HTTP API Validation**:
+```bash
+# Health check
+curl http://localhost:8080/health
+
+# Primary validation endpoint
+curl -X POST http://localhost:8080/api/validate-vendor-mapping \
+  -H "Content-Type: application/json" \
+  -d '{"vendor_name":"AssetMax Pro","safeguard_id":"1.1","claimed_capability":"full","supporting_text":"..."}'
+
+# Domain validation test
+curl -X POST http://localhost:8080/api/validate-vendor-mapping \
+  -H "Content-Type: application/json" \
+  -d '{"vendor_name":"ThreatIntel Pro","safeguard_id":"1.1","claimed_capability":"full","supporting_text":"..."}'
+```
+
+**MCP Interface Validation**:
+```bash
+# Standard MCP usage (unchanged)
+npm run start:mcp
+# Use with Claude Code as before
+```
+
+### **Performance Verification**
+
+**Shared Core Performance**:
+- ✅ **95% Cache Improvement**: Maintained across both interfaces
+- ✅ **Domain Validation**: Auto-downgrade working in both MCP and HTTP
+- ✅ **Memory Management**: Intelligent cache cleanup active
+- ✅ **Error Handling**: Production-friendly messages in both interfaces
+
+**HTTP-Specific Performance**:
+- ✅ **Response Times**: Sub-200ms for cached requests
+- ✅ **Compression**: Significant bandwidth reduction
+- ✅ **Concurrent Requests**: Express.js scalability
+- ✅ **Health Monitoring**: Real-time metrics collection
+
+---
+
+## 📋 Migration Guide
+
+### **No Breaking Changes**
+
+**Existing MCP Users**:
+- ✅ **Zero Changes Required**: All existing integrations continue working
+- ✅ **Same Tool Signatures**: No API changes to MCP tools
+- ✅ **Same Results**: Identical capability assessment output
+- ✅ **Same Performance**: All v1.1.3 optimizations preserved
+
+**Upgrade Path**:
+```bash
+# Update to v1.2.0
+npm update -g framework-mcp
+
+# Existing usage continues working
+npm run start:mcp  # or npm run dev
+
+# New cloud deployment option available
+npm run start:http
+```
+
+### **New Deployment Options**
+
+**When to Use Each Interface**:
+
+**Use MCP Interface For**:
+- Claude Code integration
+- Local development and testing
+- Tool-based LLM interactions
+- Existing workflows (no changes needed)
+
+**Use HTTP Interface For**:
+- DigitalOcean App Services deployment
+- Cloud platform deployment
+- Web application integration
+- API-based access requirements
+- Production scaling needs
+
+---
+
+## 🔒 Security and Validation
+
+### **HTTP API Security**
+
+**Input Validation**:
+- Request size limits (10MB maximum)
+- Text length validation (10-10,000 characters)
+- Capability enum validation
+- Safeguard ID format validation
+- XSS prevention through input sanitization
+
+**Security Headers**:
+```javascript
+// Helmet security configuration
+helmet({
+  contentSecurityPolicy: true,
+  crossOriginEmbedderPolicy: true,
+  crossOriginOpenerPolicy: true,
+  crossOriginResourcePolicy: true
+})
+```
+
+**CORS Configuration**:
+```bash
+# Configurable via environment
+ALLOWED_ORIGINS=https://your-domain.com,https://app.your-domain.com
+```
+
+### **Production Environment**
+
+**Environment Variables**:
+```bash
+NODE_ENV=production          # Required for production optimizations
+PORT=8080                   # HTTP server port
+ALLOWED_ORIGINS=...         # CORS configuration
+```
+
+**Monitoring and Observability**:
+- Real-time performance metrics at `/api/metrics`
+- Health check endpoint for platform monitoring
+- Error tracking and logging
+- Request counting and response time monitoring
+
+---
+
+## 📈 Business Impact
+
+### **For Security Practitioners**
+- **☁️ Cloud Deployment**: Access capability assessment from any cloud platform
+- **🔌 API Integration**: Integrate with existing security tools and workflows
+- **📊 Scalability**: Deploy at enterprise scale with cloud auto-scaling
+- **🔄 Flexibility**: Choose deployment method based on use case
+
+### **For Development Teams**
+- **🚀 Faster Deployment**: Cloud-ready HTTP API out of the box
+- **🔧 CI/CD Ready**: Standard REST API for automation pipelines  
+- **🌐 Web Integration**: Direct integration with web applications
+- **📋 Platform Agnostic**: Deploy on any cloud platform
+
+### **For Enterprise Adoption**
+- **💼 Production Ready**: Enterprise-grade HTTP API with monitoring
+- **🔒 Security Hardened**: Production security best practices implemented
+- **📈 Scalable**: Cloud-native architecture for enterprise workloads
+- **🛡️ Reliable**: Health checks and error handling for high availability
+
+---
+
+## 🎯 Success Metrics
+
+### **Deployment Success Indicators**
+- ✅ **Health Check**: `/health` returns 200 status
+- ✅ **API Functionality**: All endpoints return expected responses
+- ✅ **Domain Validation**: Auto-downgrade working correctly
+- ✅ **Performance**: Cache hit rates >95%
+- ✅ **Cloud Platform**: Successful deployment to DigitalOcean
+
+### **Integration Success Indicators**
+- ✅ **MCP Compatibility**: Existing Claude Code integrations work unchanged
+- ✅ **HTTP API**: REST endpoints accessible and functional
+- ✅ **Capability Assessment**: All 5 roles determined accurately
+- ✅ **Error Handling**: Production-friendly error messages
+- ✅ **Monitoring**: Performance metrics collection active
+
+---
+
+## 🚀 What's Next
+
+### **Immediate Benefits (Day 1)**
+- **Cloud Deployment**: Deploy to DigitalOcean App Services immediately
+- **API Access**: Integrate with web applications and automation
+- **Scalability**: Enterprise-ready deployment capability
+- **Monitoring**: Production observability and health checks
+
+### **Strategic Impact (Month 1)**
+- **Enterprise Adoption**: Cloud-native capability assessment platform
+- **Integration Ecosystem**: API-first architecture enables broader tooling
+- **Scalable Operations**: Cloud auto-scaling for high-volume assessments
+- **Multi-Platform**: Deploy across multiple cloud providers
+
+---
+
+## 📞 Support and Resources
+
+### **Documentation**
+- **📖 Deployment Guide**: Complete `DEPLOYMENT_GUIDE.md` included
+- **⚙️ Configuration**: DigitalOcean `.do/app.yaml` provided
+- **🔧 API Reference**: REST endpoint documentation at `/api`
+- **🧪 Testing Guide**: Validation commands and examples
+
+### **Community and Support**
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Community Q&A and best practices
+- **Documentation**: Complete API and deployment documentation
+- **Examples**: Production deployment configurations
+
+---
+
+## 🎊 Release Summary
+
+**Framework MCP v1.2.0** delivers the **most significant deployment enhancement** in the project's history:
+
+✅ **Dual Architecture**: MCP + HTTP interfaces with shared core logic  
+✅ **DigitalOcean Ready**: Solves stdio vs HTTP deployment conflict  
+✅ **Backward Compatible**: Zero breaking changes to existing integrations  
+✅ **Production Ready**: Enterprise-grade HTTP API with monitoring  
+✅ **Cloud Agnostic**: Deploy on any cloud platform  
+✅ **API First**: REST endpoints for modern integration patterns  
+
+**This release transforms Framework MCP from a local-only tool to a cloud-native, enterprise-ready capability assessment platform while preserving all existing functionality.**
+
+---
+
+**🌟 Upgrade today and unlock cloud deployment for your capability assessment workflows!**
+
+```bash
+npm install -g framework-mcp@1.2.0
+```
+
+**Deploy to DigitalOcean**:
+```bash
+doctl apps create .do/app.yaml
+```

package/dist/core/capability-analyzer.d.ts

@@ -0,0 +1,29 @@
+import { SafeguardElement, VendorAnalysis, DomainValidationResult, PerformanceMetrics } from '../shared/types.js';
+export declare class CapabilityAnalyzer {
+    private cache;
+    private performanceMetrics;
+    constructor();
+    performCapabilityAnalysis(vendorName: string, safeguard: SafeguardElement, responseText: string): VendorAnalysis;
+    validateVendorMapping(vendorName: string, safeguardId: string, claimedCapability: string, supportingText: string, safeguard: SafeguardElement): DomainValidationResult;
+    private determineClaimedCapability;
+    private getImplementationIndicators;
+    private assessCapabilityQuality;
+    private assessImplementationQuality;
+    private assessFacilitationQuality;
+    private assessGovernanceQuality;
+    private assessValidationQuality;
+    private generateCapabilityAnalysis;
+    private generateToolCapabilityDescription;
+    private generateRecommendedUse;
+    private detectToolType;
+    private validateDomainMatch;
+    private assessCapabilityClaimAlignment;
+    private generateValidationFeedback;
+    private calculateKeywordScore;
+    private calculateElementCoverage;
+    private recordToolExecution;
+    private logPerformanceStats;
+    private cleanupExpiredCache;
+    getPerformanceMetrics(): PerformanceMetrics;
+}
+//# sourceMappingURL=capability-analyzer.d.ts.map

package/dist/core/capability-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-analyzer.d.ts","sourceRoot":"","sources":["../../src/core/capability-analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,kBAAkB,EAMnB,MAAM,oBAAoB,CAAC;AAiE5B,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,kBAAkB,CAAqB;;IAmBxC,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,GAAG,cAAc;IA2BhH,qBAAqB,CAC1B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,MAAM,EACzB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,gBAAgB,GAC1B,sBAAsB;IA6EzB,OAAO,CAAC,0BAA0B;IAmDlC,OAAO,CAAC,2BAA2B;IAanC,OAAO,CAAC,uBAAuB;IAoC/B,OAAO,CAAC,2BAA2B;IAmCnC,OAAO,CAAC,yBAAyB;IA6BjC,OAAO,CAAC,uBAAuB;IA6B/B,OAAO,CAAC,uBAAuB;IA6B/B,OAAO,CAAC,0BAA0B;IAgClC,OAAO,CAAC,iCAAiC;IAmBzC,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,mBAAmB;IAoC3B,OAAO,CAAC,8BAA8B;IA8CtC,OAAO,CAAC,0BAA0B;IA2BlC,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,wBAAwB;IAUhC,OAAO,CAAC,mBAAmB;IAoB3B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,mBAAmB;IAkBpB,qBAAqB,IAAI,kBAAkB;CAGnD"}