framework-mcp 1.5.2 → 2.2.2

package/RELEASE_NOTES_v1.2.0.md

@@ -1,396 +0,0 @@
-# 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/RELEASE_NOTES_v1.3.7.md

@@ -1,275 +0,0 @@
-# Framework MCP v1.3.7 Release Notes
-
-**Release Date**: August 21, 2025  
-**Version**: 1.3.7  
-**Sprint**: 4-Sprint Architecture Cleanup Complete  
-
-## 🎉 Major Release: Clean Architecture & Complete Documentation Ecosystem
-
-Framework MCP v1.3.7 represents a **major architectural cleanup** that simplifies and strengthens the codebase while maintaining all functionality. This release completes a comprehensive 4-sprint refactoring initiative focused on content-based capability analysis.
-
----
-
-## 🚀 What's New in v1.3.7
-
-### ✅ **Sprint 1 (Days 1-2): Domain Validation Removal**
-- **REMOVED**: All domain validation logic and tool type detection
-- **SIMPLIFIED**: Capability analysis now uses pure content-based assessment
-- **ENHANCED**: More reliable and consistent capability role determination
-- **CLEANED**: Eliminated complex auto-downgrade logic
-
-### ✅ **Sprint 2 (Days 3-4): Safeguards Data Replacement**
-- **REPLACED**: All 153 safeguards with exact CIS Controls PDF data
-- **IMPROVED**: More accurate and authoritative safeguard definitions
-- **ENHANCED**: Better alignment with official CIS Controls v8.1 framework
-- **STANDARDIZED**: Consistent data structure across all safeguards
-
-### ✅ **Sprint 3 (Days 5-6): API Documentation Alignment**
-- **UPDATED**: Complete Swagger/OpenAPI specification alignment
-- **FIXED**: All API endpoint documentation reflects clean architecture
-- **REMOVED**: Domain validation references from API docs
-- **ENHANCED**: Clearer and more accurate API documentation
-
-### ✅ **Sprint 4 (Days 7-8): Documentation Ecosystem Completion**
-- **UPDATED**: Complete README.md overhaul with clean architecture
-- **REVISED**: All example usage to reflect simplified approach
-- **CLEANED**: Deployment guide updated for v1.3.7
-- **COMPLETED**: Comprehensive documentation consistency
-
----
-
-## 🎯 Core Changes Summary
-
-### **Capability Analysis Engine**
-- **BEFORE**: Complex domain validation with tool type detection and auto-downgrade
-- **AFTER**: Clean content-based analysis focusing on evidence quality
-- **BENEFIT**: More reliable, transparent, and maintainable assessment logic
-
-### **Safeguards Framework**
-- **BEFORE**: Interpreted safeguard data with potential inconsistencies
-- **AFTER**: Exact CIS Controls PDF data with authoritative definitions
-- **BENEFIT**: Perfect alignment with official CIS Controls v8.1 framework
-
-### **API Documentation**
-- **BEFORE**: Mixed references to domain validation features
-- **AFTER**: Clean, consistent documentation reflecting actual functionality
-- **BENEFIT**: Accurate developer experience and integration guidance
-
-### **Documentation Ecosystem**
-- **BEFORE**: Domain validation examples and references throughout
-- **AFTER**: Content-based examples and clean architecture descriptions
-- **BENEFIT**: Clear, consistent documentation across entire project
-
----
-
-## 🔧 Technical Improvements
-
-### **Code Quality**
-- **Reduced Complexity**: Eliminated domain validation logic paths
-- **Improved Maintainability**: Cleaner, more focused codebase
-- **Enhanced Reliability**: Fewer edge cases and validation conflicts
-- **Better Performance**: Streamlined analysis without tool type detection
-
-### **API Consistency**
-- **Unified Response Format**: Consistent JSON structure across endpoints
-- **Clear Error Handling**: Simplified error responses without domain mismatches
-- **Improved Validation**: Content-focused validation criteria
-- **Enhanced Documentation**: Accurate Swagger/OpenAPI specifications
-
-### **User Experience**
-- **Simplified Workflow**: No need to understand domain validation rules
-- **Clearer Results**: Content-based confidence scores and evidence analysis
-- **Better Examples**: Real-world scenarios with practical guidance
-- **Consistent Behavior**: Predictable capability role determination
-
----
-
-## 📋 Migration Guide
-
-### **For Existing Users**
-✅ **No Breaking Changes**: All existing API endpoints continue working  
-✅ **Same Input Format**: No changes to request structure  
-✅ **Enhanced Output**: Improved response quality without domain validation complexity  
-✅ **Better Documentation**: Updated examples and usage guidance  
-
-### **What Changed**
-- **Domain Validation**: Removed entirely - no more auto-downgrade logic
-- **Tool Type Detection**: Eliminated - focus on content analysis only  
-- **Response Format**: `domain_validation` fields replaced with `content_validation`
-- **Example Usage**: Updated to reflect content-based approach
-
-### **What Stayed the Same**
-- **Core Functionality**: All 5 capability roles (FULL, PARTIAL, FACILITATES, GOVERNANCE, VALIDATES)
-- **API Endpoints**: Same URLs and HTTP methods
-- **Input Parameters**: Same request structure
-- **CIS Coverage**: Complete 153 safeguards across all 18 controls
-
----
-
-## 🎨 New Content-Based Analysis
-
-### **Analysis Dimensions**
-| Dimension | Description | Focus |
-|-----------|-------------|-------|
-| **Core Requirements Coverage** | Alignment with primary safeguard elements | Implementation specifics |
-| **Sub-Elements Coverage** | Support for detailed components | Breadth of coverage |
-| **Governance Alignment** | Policy/process management | Oversight capabilities |
-| **Implementation Depth** | Technical detail and specificity | Solution completeness |
-| **Language Consistency** | Claim-evidence alignment | Response quality |
-
-### **Validation Logic**
-- **Strong Evidence**: Detailed implementation with comprehensive coverage
-- **Moderate Evidence**: Good coverage with some gaps or general language  
-- **Weak Evidence**: Limited specifics, vague implementation details
-
-### **Status Determination**
-- **SUPPORTED** (70-100%): Evidence strongly supports claimed capability
-- **QUESTIONABLE** (40-69%): Partial support with notable gaps or inconsistencies
-- **UNSUPPORTED** (0-39%): Evidence does not adequately support the claim
-
----
-
-## 📊 Example Response Updates
-
-### **Before (v1.3.6)**
-```json
-{
-  "domain_validation": {
-    "required_tool_type": "inventory",
-    "detected_tool_type": "threat_intelligence",
-    "domain_match": false,
-    "capability_adjusted": true
-  }
-}
-```
-
-### **After (v1.3.7)**
-```json
-{
-  "content_validation": {
-    "implementation_depth": "comprehensive",
-    "scope_clarity": "well_defined",
-    "evidence_strength": "strong",
-    "capability_aligned": true
-  }
-}
-```
-
----
-
-## 🛠️ Developer Benefits
-
-### **Simplified Integration**
-- **No Tool Type Mapping**: No need to understand domain validation rules
-- **Clearer Responses**: Content-focused validation results
-- **Better Documentation**: Accurate examples and integration guides
-- **Consistent Behavior**: Predictable capability assessment logic
-
-### **Enhanced Reliability**
-- **Fewer Edge Cases**: No domain mismatch conflicts
-- **Cleaner Codebase**: Reduced complexity and technical debt
-- **Better Testing**: Simpler test scenarios and validation logic
-- **Improved Performance**: Streamlined analysis pipeline
-
----
-
-## 📈 Performance Improvements
-
-- **95% Cache Efficiency**: Maintained high-performance caching
-- **Reduced Analysis Time**: Simpler logic paths improve speed
-- **Lower Memory Usage**: Eliminated tool type detection overhead
-- **Better Scalability**: Clean architecture supports growth
-
----
-
-## 🔒 Security & Compliance
-
-- **Same Security Model**: No changes to security posture
-- **CIS Controls Alignment**: Perfect alignment with official v8.1 framework
-- **Data Integrity**: Authoritative safeguard data from official sources
-- **Audit Trail**: Clear content-based assessment reasoning
-
----
-
-## 🎯 Use Case Examples
-
-### **GRC Teams**
-```bash
-# Validate vendor capability claims with content analysis
-claude-code "Use validate_vendor_mapping for vendor 'AssetMax Pro', 
-safeguard '1.1', claimed capability 'full', with supporting text: 
-'Comprehensive automated discovery, detailed inventory management...'"
-```
-
-### **Security Professionals**
-```bash
-# Analyze vendor responses for capability determination
-claude-code "Use analyze_vendor_response to analyze Microsoft Entra ID 
-for safeguard 5.1 with response about centralized identity management..."
-```
-
-### **Compliance Assessors**
-```bash
-# Get detailed safeguard requirements for assessment
-claude-code "Use get_safeguard_details for safeguard 1.1 with examples 
-to understand complete requirements"
-```
-
----
-
-## 🗂️ Complete File Changes
-
-### **Updated Documentation**
-- `README.md` - Complete overhaul with clean architecture
-- `DEPLOYMENT_GUIDE.md` - Updated for v1.3.7 without domain validation
-- `examples/example-usage.md` - All examples updated for content-based approach
-- `swagger.json` - API documentation aligned with clean architecture
-
-### **Core Implementation Files**
-- `src/core/capability-analyzer.ts` - Domain validation logic removed
-- `src/core/safeguard-manager.ts` - All 153 safeguards updated with CIS PDF data
-- `src/interfaces/http/http-server.ts` - API responses updated
-- `src/interfaces/mcp/mcp-server.ts` - MCP tool responses cleaned
-
----
-
-## 🎉 Success Metrics
-
-✅ **Architecture Cleanup**: 100% domain validation removal completed  
-✅ **Data Quality**: 153/153 safeguards updated with authoritative CIS data  
-✅ **Documentation**: 100% documentation consistency achieved  
-✅ **API Alignment**: Complete Swagger/OpenAPI specification accuracy  
-✅ **User Experience**: Simplified, content-focused capability analysis  
-✅ **Performance**: Maintained 95%+ cache efficiency  
-✅ **Reliability**: Eliminated domain validation edge cases  
-
----
-
-## 🚀 What's Next
-
-Framework MCP v1.3.7 represents the **complete architecture cleanup** and establishes a solid foundation for future enhancements:
-
-- **Enhanced Analytics**: Advanced content analysis features
-- **Extended Coverage**: Additional CIS Controls as they're released
-- **Integration Improvements**: Enhanced MCP and HTTP API capabilities
-- **Performance Optimization**: Continued efficiency improvements
-
----
-
-## 🙏 Acknowledgments
-
-This major release was made possible by:
-- **CIS Controls Framework**: Official CIS Controls v8.1 documentation
-- **Community Feedback**: User input driving simplification efforts
-- **Architecture Review**: Comprehensive code quality and maintainability focus
-
----
-
-**🎯 Framework MCP v1.3.7: Clean Architecture. Authoritative Data. Enhanced Reliability.**
-
-For support, documentation, and updates:
-- **GitHub**: [Framework MCP Repository](https://github.com/therealcybermattlee/FrameworkMCP)
-- **Issues**: [GitHub Issues](https://github.com/therealcybermattlee/FrameworkMCP/issues)
-- **Documentation**: Complete API and usage documentation included
-
-**Framework MCP v1.3.7 - Ready for Production** ✅