framework-mcp 1.3.7 → 1.5.0

package/MCP_INTEGRATION_GUIDE.md

@@ -2,7 +2,7 @@
 
 ## Claude Code MCP Integration
 
-This guide shows how to integrate Framework MCP with Claude Code for CIS Controls capability assessment.
+This guide shows how to integrate Framework MCP v1.4.0's Pure Data Provider architecture with Claude Code for LLM-driven CIS Controls capability analysis.
 
 ## Prerequisites
 
@@ -68,189 +68,156 @@ claude-code "List all available CIS Control safeguards"
 
 Expected response: List of 153 safeguards across 18 CIS Controls
 
-## 🔧 MCP Tool Usage
+## 🔧 Pure Data Provider Tools
 
-### 1. validate_vendor_mapping (PRIMARY)
+### 1. get_safeguard_details (PRIMARY)
 
-**Most Important Tool**: Evidence-based validation with domain validation
+**Primary Tool**: Retrieve detailed CIS safeguard breakdown for LLM analysis
 
 ```bash
-# Validate FULL capability claim (should pass)
-claude-code "Use validate_vendor_mapping with vendor_name 'ServiceNow CMDB', safeguard_id '1.1', claimed_capability 'full', and supporting_text 'Our CMDB provides comprehensive asset lifecycle management with automated discovery, detailed hardware and software inventory tracking, enterprise asset ownership records, departmental assignments, and documented bi-annual review processes.'"
+# Get comprehensive safeguard data for analysis
+claude-code "Use get_safeguard_details with safeguard_id '1.1' and include_examples true"
 
-# Validate FULL capability claim (should auto-downgrade)  
-claude-code "Use validate_vendor_mapping with vendor_name 'Splunk SIEM', safeguard_id '1.1', claimed_capability 'full', and supporting_text 'Our SIEM platform provides comprehensive network visibility through log analysis and maintains detailed asset information through security event correlation.'"
+# Research multiple related safeguards
+claude-code "Use get_safeguard_details for safeguard 5.1 then explain the key requirements for account inventory management"
 
-# Validate FACILITATES capability claim
-claude-code "Use validate_vendor_mapping with vendor_name 'Nessus Scanner', safeguard_id '1.1', claimed_capability 'facilitates', and supporting_text 'Our vulnerability scanner enhances existing asset management by providing additional device discovery and detailed software inventory during security assessments.'"
+# Get data for comparative analysis
+claude-code "Use get_safeguard_details for safeguard 6.3 then explain what makes this different from basic authentication controls"
 ```
 
-### 2. analyze_vendor_response
+### 2. list_available_safeguards  
 
-**Purpose**: Determine appropriate capability role when unknown
+**Discovery Tool**: Explore available safeguards for planning and assessment
 
 ```bash
-# Analyze identity management vendor
-claude-code "Use analyze_vendor_response with vendor_name 'Okta', safeguard_id '5.1', and response_text 'We provide comprehensive identity lifecycle management with automated account provisioning, detailed user directories, quarterly access reviews, and full compliance reporting with audit trails.'"
-
-# Analyze cross-domain vendor
-claude-code "Use analyze_vendor_response with vendor_name 'CrowdStrike Falcon', safeguard_id '1.1', and response_text 'Our endpoint protection platform provides real-time asset visibility with comprehensive device inventory, software tracking, and continuous asset monitoring across all enterprise endpoints.'"
-```
-
-### 3. get_safeguard_details
-
-**Purpose**: Research safeguard requirements before assessment
-
-```bash
-# Basic safeguard details
-claude-code "Use get_safeguard_details with safeguard_id '1.1'"
-
-# Detailed safeguard with examples
-claude-code "Use get_safeguard_details with safeguard_id '5.1' and include_examples true"
-
-# Research multiple safeguards
-claude-code "Use get_safeguard_details for safeguard 6.3 then explain what makes this safeguard different from 5.1"
-```
-
-### 4. list_available_safeguards  
-
-**Purpose**: Discover available safeguards for planning
-
-```bash
-# Complete safeguard list
+# Complete safeguard framework exploration
 claude-code "Use list_available_safeguards"
 
 # Targeted safeguard discovery
 claude-code "Use list_available_safeguards then identify which safeguards are most relevant for identity management vendor assessment"
+
+# Implementation Group planning
+claude-code "Use list_available_safeguards then show me all IG1 safeguards for small business security planning"
 ```
 
-## 📋 Common MCP Workflows
+## 📋 LLM-Driven Analysis Workflows
 
-### Workflow 1: New Vendor Assessment
+### Workflow 1: Comprehensive Vendor Assessment
 ```bash
-# Step 1: Research the safeguard
-claude-code "Use get_safeguard_details for safeguard 1.1 to understand all requirements"
+# Step 1: Get authoritative safeguard data
+claude-code "Use get_safeguard_details with safeguard_id '1.1' and include_examples true"
 
-# Step 2: Analyze vendor response (capability unknown)
-claude-code "Use analyze_vendor_response for vendor 'Device42' with safeguard '1.1' and response 'Our IT asset management platform provides comprehensive device discovery, detailed inventory tracking, and complete asset lifecycle management.'"
+# Step 2: Perform LLM-driven analysis
+claude-code "Based on the safeguard 1.1 requirements above, analyze Device42's capability: 'Our IT asset management platform provides comprehensive device discovery, detailed inventory tracking, and complete asset lifecycle management.' Determine capability role, provide confidence assessment, and recommend implementation approach."
 
-# Step 3: Validate specific claim (if vendor claims specific capability)
-claude-code "Use validate_vendor_mapping to validate Device42's claim of 'full' capability for safeguard 1.1"
+# Step 3: Context-aware evaluation
+claude-code "For our 500-employee technology company, assess whether Device42 meets our asset management needs for IG2 compliance. Consider deployment complexity and integration requirements."
 ```
 
-### Workflow 2: Claims Validation Audit
+### Workflow 2: Multi-Vendor Comparative Analysis
 ```bash
-# Validate high-confidence claim
-claude-code "Use validate_vendor_mapping for vendor 'Microsoft Entra ID', safeguard '5.1', claimed capability 'full', with supporting text 'Complete identity management with automated provisioning, detailed account inventories, quarterly reviews, and comprehensive compliance reporting.'"
+# Get safeguard requirements
+claude-code "Use get_safeguard_details for safeguard 5.1 with examples"
 
-# Validate questionable claim  
-claude-code "Use validate_vendor_mapping for vendor 'Network Scanner Pro', safeguard '1.1', claimed capability 'full', with supporting text 'We scan networks and find devices.'"
+# Comparative analysis with business context
+claude-code "Using the safeguard 5.1 requirements above, compare these identity management solutions for our financial services organization: 1) Microsoft Entra ID: 'Complete identity management with automated provisioning and compliance reporting' 2) Okta: 'Cloud identity platform with advanced analytics and risk assessment' 3) Ping Identity: 'Enterprise SSO with detailed audit trails and governance workflows'. Rank by compliance strength and implementation fit."
 ```
 
-### Workflow 3: Multi-Safeguard Vendor Analysis
+### Workflow 3: Gap Analysis and Roadmap Planning
 ```bash
-# Analyze vendor across multiple safeguards
-claude-code "Use analyze_vendor_response for Microsoft Defender for Endpoint across these scenarios:
-1. Safeguard 1.1: 'Comprehensive endpoint asset discovery and inventory'
-2. Safeguard 7.1: 'Continuous vulnerability assessment and patch management'  
-3. Safeguard 1.2: 'Unauthorized device detection and blocking'"
-```
-
-## 🎯 Domain Validation Examples
-
-### Asset Management Domain (Safeguards 1.1, 1.2)
-```bash
-# Appropriate tool type (should pass)
-claude-code "Use validate_vendor_mapping for 'Lansweeper', safeguard '1.1', claimed 'full', with 'Complete IT asset management with automated discovery, comprehensive inventory, and detailed asset tracking.'"
+# Research multiple related safeguards
+claude-code "Use get_safeguard_details for safeguard 5.1, then get details for 5.2, 5.3, and 5.4"
 
-# Inappropriate tool type (should auto-downgrade)
-claude-code "Use validate_vendor_mapping for 'Qualys VMDR', safeguard '1.1', claimed 'full', with 'Vulnerability scanning with network discovery and asset databases.'"
+# Comprehensive gap analysis
+claude-code "Based on the account management safeguards 5.1-5.4 above, analyze our current IAM capability: Azure AD basic with manual quarterly reviews. Identify gaps, prioritize improvements, and create 12-month implementation roadmap with budget estimates."
 ```
 
-### Identity Management Domain (Safeguards 5.1, 6.3)
+### Workflow 4: Risk-Based Assessment
 ```bash
-# Appropriate tool type (should pass)
-claude-code "Use validate_vendor_mapping for 'SailPoint', safeguard '5.1', claimed 'full', with 'Identity governance with comprehensive account management, lifecycle automation, and quarterly certifications.'"
+# Get network monitoring safeguards
+claude-code "Use get_safeguard_details for safeguard 13.1, then get details for 13.3 and 13.6"
 
-# Inappropriate tool type (should auto-downgrade)
-claude-code "Use validate_vendor_mapping for 'Splunk', safeguard '5.1', claimed 'full', with 'Account activity monitoring and user behavior analytics through log analysis.'"
+# Risk-focused analysis
+claude-code "Using the network monitoring safeguards above, our financial services organization faces advanced persistent threats and ransomware. Analyze Microsoft Defender for Endpoint's network capabilities: 'Real-time endpoint detection, behavioral analytics, automated response, and network traffic monitoring.' Prioritize safeguards by threat mitigation effectiveness and recommend complementary tools."
 ```
 
-## 🚀 Advanced MCP Usage
+## 🚀 Advanced LLM Analysis Patterns
 
-### Custom Analysis Prompts
+### Custom Methodology Applications
 ```bash
-# Comparative assessment
-claude-code "Use validate_vendor_mapping to compare these FULL capability claims for safeguard 1.1: ServiceNow CMDB vs Device42 vs Lansweeper. Analyze domain validation, evidence quality, and confidence scores."
+# Compliance-focused assessment
+claude-code "Use get_safeguard_details for safeguard 8.2. Apply PCI-DSS Level 1 compliance methodology to analyze Splunk Enterprise Security's logging capability: 'Centralized log management, real-time monitoring, compliance reporting, and data retention policies.' Focus on regulatory alignment and audit readiness."
 
-# Gap analysis
-claude-code "Use get_safeguard_details for safeguard 5.1, then use analyze_vendor_response for Vendor 'BasicIAM' with response 'We provide user directories and password management.' Identify capability gaps."
+# Technology integration assessment
+claude-code "Use get_safeguard_details for safeguard 16.1. Our DevOps pipeline uses Azure DevOps, GitHub, and Kubernetes. Analyze SonarQube's capability: 'Static application security testing with CI/CD integration and policy enforcement.' Recommend implementation approach and configuration."
 
-# Compliance planning
-claude-code "Use list_available_safeguards to identify all safeguards in Controls 1-3, then recommend which vendor types would be needed for comprehensive coverage."
+# Strategic planning
+claude-code "Use list_available_safeguards to identify all Implementation Group 1 safeguards, then create vendor selection strategy for a 200-employee company with $500K security budget. Prioritize by business impact and implementation complexity."
 ```
 
-### Error Handling Examples
+### Data Validation Examples
 ```bash
 # Invalid safeguard ID
 claude-code "Use get_safeguard_details with safeguard_id '99.99'"
 # Expected: Error with available safeguards suggestion
 
-# Invalid capability role
-claude-code "Use validate_vendor_mapping with claimed_capability 'super-full'"
-# Expected: Error listing valid capability roles
+# Missing required parameter
+claude-code "Use get_safeguard_details without safeguard_id"
+# Expected: Error specifying required parameter
 
-# Insufficient supporting text
-claude-code "Use validate_vendor_mapping with supporting_text 'Good tool'"  
-# Expected: Error requiring minimum 10 characters
+# Valid request with detailed response
+claude-code "Use get_safeguard_details with safeguard_id '1.1' and include_examples true"
+# Expected: Complete safeguard breakdown with implementation examples
 ```
 
-## 📊 Understanding MCP Responses
+## 📊 Understanding Pure Data Provider Responses
 
-### Successful Validation Response
+### Detailed Safeguard Data Response
 ```json
 {
-  "vendor_name": "ServiceNow CMDB",
-  "safeguard_id": "1.1", 
-  "claimed_capability": "full",
-  "validated_capability": "full",
-  "validation_status": "SUPPORTED",
-  "confidence_score": 88,
-  "domain_validation": {
-    "tool_type": "cmdb",
-    "domain_appropriate": true,
-    "auto_downgrade_applied": false
-  },
-  "evidence_analysis": {
-    "core_requirements_score": 95,
-    "governance_elements_score": 80,
-    "sub_elements_score": 85,
-    "language_consistency_score": 92
-  },
-  "reasoning": "Strong evidence for FULL capability with appropriate tool type",
-  "recommendations": []
+  "id": "1.1",
+  "title": "Establish and Maintain Detailed Enterprise Asset Inventory",
+  "description": "Establish and maintain an accurate, detailed, and up-to-date inventory of all enterprise assets...",
+  "implementationGroup": "IG1",
+  "governanceElements": [
+    "Maintain detailed inventory procedures",
+    "Establish asset classification standards",
+    "Define asset ownership responsibilities"
+  ],
+  "coreRequirements": [
+    "Automated discovery of enterprise assets",
+    "Detailed hardware and software inventory",
+    "Asset ownership and location tracking"
+  ],
+  "subTaxonomicalElements": [
+    "Device identification and classification",
+    "Software inventory and licensing",
+    "Network topology mapping"
+  ],
+  "implementationSuggestions": [
+    "Deploy automated discovery tools",
+    "Implement CMDB solutions",
+    "Regular inventory audits and updates"
+  ]
 }
 ```
 
-### Auto-Downgrade Response
-```json
-{
-  "vendor_name": "Nessus Scanner",
-  "safeguard_id": "1.1",
-  "claimed_capability": "full", 
-  "validated_capability": "facilitates",
-  "validation_status": "QUESTIONABLE",
-  "confidence_score": 60,
-  "domain_validation": {
-    "tool_type": "vulnerability_management",
-    "domain_appropriate": false,
-    "auto_downgrade_applied": true
-  },
-  "reasoning": "Auto-downgraded from FULL to FACILITATES due to domain mismatch",
-  "recommendations": [
-    "Consider repositioning as FACILITATES capability to align with tool type"
-  ]
-}
+### LLM Analysis Response Pattern
+```
+CAPABILITY ASSESSMENT: ServiceNow CMDB vs Safeguard 1.1
+
+DETERMINATION: FULL + GOVERNANCE + VALIDATES
+CONFIDENCE: 88%
+
+EVIDENCE ANALYSIS:
+✅ Core Requirements: Comprehensive CMDB with automated discovery
+✅ Governance Elements: Detailed procedures and asset classification
+✅ Sub-Elements: Complete device and software inventory tracking
+✅ Implementation: Strong technical capabilities and proven enterprise deployment
+
+REASONING: ServiceNow CMDB demonstrates strong alignment with all core requirements and provides additional governance and validation capabilities through workflow automation and compliance reporting.
+
+RECOMMENDATIONS: Excellent foundation for IG2-IG3 implementation. Consider integration with security tools for enhanced asset risk assessment.
 ```
 
 ## 🔍 Troubleshooting

package/MIGRATION_GUIDE_v1.4.0.md

@@ -0,0 +1,190 @@
+# Migration Guide: Framework MCP v1.4.0
+
+## Pure Data Provider Architecture Transformation
+
+Framework MCP v1.4.0 introduces a **Pure Data Provider architecture** that transforms how vendor capability analysis is performed. This guide helps existing users migrate to the new approach and understand the enhanced capabilities.
+
+## 🎯 Architectural Benefits
+
+### Before v1.4.0: Hardcoded Analysis Engine
+- **Limited Flexibility**: Fixed analysis logic with preset validation rules
+- **Rigid Assessment**: Single approach to capability determination
+- **Complex Configuration**: Multiple analysis parameters and validation settings
+- **Opaque Processing**: Analysis logic hidden within the tool
+
+### After v1.4.0: Pure Data Provider + LLM Analysis
+- **Unlimited Flexibility**: LLMs can apply any analysis approach or methodology
+- **Context-Aware Assessment**: Analysis considers industry, risk profile, and specific requirements
+- **Simplified Interface**: Clean data provision without analysis complexity
+- **Transparent Process**: Analysis reasoning fully visible and customizable
+
+## 🔄 Migration Overview
+
+**KEY CHANGE**: Framework MCP no longer performs analysis - it provides authoritative CIS Controls data for LLMs to analyze with sophisticated, context-aware intelligence.
+
+### Tools Removed
+- ❌ `analyze_vendor_response` - Analysis logic moved to LLM capability
+- ❌ `validate_vendor_mapping` - Validation logic moved to LLM intelligence
+
+### Tools Retained (Enhanced Data Focus)
+- ✅ `get_safeguard_details` - **Enhanced** with rich, structured CIS data
+- ✅ `list_available_safeguards` - Complete framework coverage
+
+## 📋 Step-by-Step Migration
+
+### Step 1: Update Framework MCP
+```bash
+npm update -g framework-mcp
+# Or reinstall to ensure latest version
+npm uninstall -g framework-mcp && npm install -g framework-mcp
+```
+
+### Step 2: Replace Analysis Calls with LLM-Driven Patterns
+
+#### OLD v1.3.7 Approach (Hardcoded Analysis)
+```bash
+claude-code "Use analyze_vendor_response with vendor_name 'Microsoft Defender', safeguard_id '5.1', and response_text 'We provide centralized account management with automated provisioning'"
+```
+
+#### NEW v1.4.0 Approach (LLM-Driven Analysis)
+```bash
+claude-code "Get safeguard details for 5.1, then analyze this vendor response against those requirements: Microsoft Defender - 'We provide centralized account management with automated provisioning'. Assess capability role considering enterprise context and provide confidence rating."
+```
+
+### Step 3: Leverage Enhanced LLM Capabilities
+
+The new approach enables sophisticated analysis patterns:
+
+#### Risk-Based Assessment
+```bash
+claude-code "Get details for safeguard 8.2. For a high-risk financial services environment, analyze SentinelOne's response: 'We collect endpoint telemetry and forward logs to SIEM platforms.' Consider regulatory requirements and determine appropriate capability role."
+```
+
+#### Comparative Analysis
+```bash
+claude-code "Get safeguard 1.1 details. Compare these vendor capabilities and rank by implementation completeness: 1) Lansweeper: 'Complete network discovery and inventory' 2) ServiceNow: 'CMDB with manual asset entry' 3) Microsoft Intune: 'Managed device tracking only'"
+```
+
+#### Multi-Safeguard Assessment
+```bash
+claude-code "Get details for safeguards 5.1, 5.2, and 5.3. Analyze how CyberArk PAM addresses these account management requirements and identify any gaps in coverage."
+```
+
+## 🚀 Advanced LLM Analysis Patterns
+
+### 1. Compliance-Focused Analysis
+```bash
+claude-code "Get safeguard 11.1 details. For SOX compliance requirements, assess Veeam Backup's capability: 'Automated daily backups with 99.9% recovery success rate and quarterly recovery testing.' Focus on governance and validation aspects."
+```
+
+### 2. Technology-Specific Assessment
+```bash
+claude-code "Get details for safeguard 16.3. From a DevSecOps perspective, analyze GitHub Advanced Security: 'Static analysis, dependency scanning, and secret detection in CI/CD pipeline.' Consider modern development workflows."
+```
+
+### 3. Implementation Planning
+```bash
+claude-code "Get safeguard 13.1 details. Our organization uses Splunk SIEM. Analyze how this addresses network monitoring requirements and recommend complementary tools for complete coverage."
+```
+
+## 🎨 Benefits of LLM-Driven Analysis
+
+### Context Awareness
+- **Industry Considerations**: LLMs understand sector-specific requirements
+- **Risk Profiles**: Analysis adapts to organizational risk tolerance
+- **Technology Stack**: Assessment considers existing tool ecosystems
+
+### Analytical Flexibility
+- **Multiple Methodologies**: Apply different assessment frameworks
+- **Custom Criteria**: Focus on organization-specific priorities
+- **Comparative Analysis**: Evaluate multiple vendors simultaneously
+
+### Enhanced Intelligence
+- **Natural Language**: Complex analysis requests in plain English
+- **Reasoning Transparency**: Full explanation of assessment logic
+- **Adaptive Questioning**: LLMs can ask clarifying questions
+
+## 📊 Migration Examples
+
+### Example 1: Basic Capability Assessment
+**Old Method:**
+```bash
+# Required specific tool call format
+claude-code "Use analyze_vendor_response..."
+```
+
+**New Method:**
+```bash
+claude-code "Get safeguard 6.8 details and assess whether Okta's MFA solution constitutes FULL or FACILITATES capability for this requirement."
+```
+
+### Example 2: Validation Assessment
+**Old Method:**
+```bash
+# Fixed validation logic
+claude-code "Use validate_vendor_mapping..."
+```
+
+**New Method:**
+```bash
+claude-code "Get safeguard 12.4 details. This vendor claims FULL capability: 'We monitor all network traffic and identify unauthorized devices.' Validate this claim and provide evidence-based assessment."
+```
+
+### Example 3: Multi-Vendor Comparison
+**Old Method:**
+```bash
+# Required multiple separate calls
+claude-code "Use analyze_vendor_response..." # Vendor A
+claude-code "Use analyze_vendor_response..." # Vendor B
+```
+
+**New Method:**
+```bash
+claude-code "Get safeguard 2.1 details. Compare these software inventory solutions and recommend the best fit for our 500-employee company: 1) Lansweeper 2) Device42 3) ManageEngine AssetExplorer. Consider deployment complexity and feature completeness."
+```
+
+## 🔧 Technical Changes
+
+### HTTP API Updates
+- **Removed**: `/api/analyze-vendor-response` endpoint
+- **Removed**: `/api/validate-vendor-mapping` endpoint
+- **Enhanced**: Data endpoints optimized for LLM consumption
+- **Maintained**: Full OpenAPI compatibility for Microsoft Copilot
+
+### MCP Protocol Changes
+- **Simplified**: 2 core tools instead of 4 complex tools
+- **Enhanced**: Rich data provision with structured safeguard information
+- **Optimized**: Performance improvements for data retrieval
+
+## 📚 Common Migration Questions
+
+### Q: Will my existing Copilot connectors work?
+**A**: Yes, but update to use data endpoints. The enhanced LLM analysis provides better results than hardcoded validation.
+
+### Q: How do I replicate my custom validation logic?
+**A**: Describe your validation criteria to the LLM along with the safeguard data. LLMs can apply complex, custom logic more effectively than preset rules.
+
+### Q: Can I still get confidence scores?
+**A**: Yes, LLMs can provide confidence assessments with detailed reasoning - often more nuanced than algorithmic scores.
+
+### Q: What about bulk vendor analysis?
+**A**: LLMs excel at processing multiple vendors simultaneously. Upload vendor data and request comparative analysis across all entries.
+
+## 🎯 Next Steps
+
+1. **Update Framework MCP** to v1.4.0
+2. **Review existing analysis workflows** and identify LLM-driven alternatives
+3. **Experiment with enhanced patterns** like comparative analysis and context-aware assessment
+4. **Update documentation** and training materials for new approach
+5. **Leverage LLM flexibility** to create more sophisticated vendor evaluations
+
+## 📞 Support
+
+If you encounter migration challenges:
+- 📧 **Issues**: [GitHub Issues](https://github.com/therealcybermattlee/FrameworkMCP/issues)
+- 📖 **Documentation**: [Enhanced Usage Patterns](examples/llm-analysis-patterns.md)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/therealcybermattlee/FrameworkMCP/discussions)
+
+---
+
+**The Pure Data Provider architecture transforms Framework MCP from a rigid analysis tool into a flexible foundation for sophisticated, LLM-powered vendor capability assessment.**