framework-mcp 1.3.7 → 1.5.0

package/COPILOT_INTEGRATION.md

@@ -1,10 +1,10 @@
 # Microsoft Copilot Integration Guide
 
-This guide provides step-by-step instructions for integrating Framework MCP with Microsoft Copilot using custom connectors.
+This guide provides step-by-step instructions for integrating Framework MCP v1.4.0's Pure Data Provider architecture with Microsoft Copilot using custom connectors.
 
 ## Overview
 
-Framework MCP provides a dual-architecture solution that enables both Model Context Protocol (MCP) integration with Claude Code and HTTP API integration with Microsoft Copilot. This allows security professionals to access CIS Controls capability assessment through their preferred AI platform.
+Framework MCP v1.4.0 provides a **Pure Data Provider architecture** with dual interfaces enabling both Model Context Protocol (MCP) integration with Claude Code and HTTP API integration with Microsoft Copilot. This empowers security professionals to access authoritative CIS Controls data through their preferred AI platform for sophisticated, LLM-driven vendor capability analysis.
 
 ## Prerequisites
 
@@ -52,7 +52,7 @@ Expected response:
   "uptime": 1234,
   "totalRequests": 0,
   "errorCount": 0,
-  "version": "1.3.7",
+  "version": "1.4.0",
   "timestamp": "2025-08-21T01:00:00.000Z"
 }
 ```
@@ -74,8 +74,8 @@ Expected response:
    - Click **Continue**
 
 4. **Configure Connector Details**
-   - **Name**: Framework MCP - CIS Controls Capability Assessment
-   - **Description**: Validate vendor capability claims against CIS Controls Framework
+   - **Name**: Framework MCP - Pure Data Provider
+   - **Description**: Authoritative CIS Controls Framework data for LLM-driven analysis
    - **Host**: Update to your deployed API URL (e.g., `your-app.ondigitalocean.app`)
    - **Base URL**: `/`
 
@@ -109,89 +109,72 @@ Expected response:
    - Select **Custom connector**
    - Choose your Framework MCP connector
 
-## Custom Actions Configuration
+## Data Actions Configuration
 
-### Primary Action: Validate Vendor Capability
+### Primary Action: Get Safeguard Details
 
-Configure this action for evidence-based validation:
+Configure this action for detailed CIS safeguard information:
 
 **Action Details:**
-- **Name**: Validate Vendor Capability Mapping
-- **Description**: Validate vendor capability claims against CIS Controls with domain validation and auto-downgrade protection
+- **Name**: Get CIS Safeguard Details
+- **Description**: Retrieve detailed CIS Controls safeguard breakdown for LLM analysis
 - **Connector**: Framework MCP Custom Connector
-- **Operation**: `validateVendorMapping`
+- **Operation**: `getSafeguardDetails`
 
 **Parameters:**
-- **vendor_name** (Required): Name of the vendor/tool being analyzed
-- **safeguard_id** (Required): CIS safeguard ID (e.g., "1.1", "5.1", "12.8")
-- **claimed_capability** (Required): Capability role (full, partial, facilitates, governance, validates)
-- **supporting_text** (Required): Vendor response supporting their capability claim
+- **safeguardId** (Required): CIS safeguard ID (e.g., "1.1", "5.1", "12.8")
+- **include_examples** (Optional): Include implementation examples (true/false)
 
 **Sample Input:**
 ```json
 {
-  "vendor_name": "CrowdStrike Falcon",
-  "safeguard_id": "1.1",
-  "claimed_capability": "full",
-  "supporting_text": "Our platform provides comprehensive enterprise asset inventory with real-time discovery, automated classification, and continuous monitoring of all hardware and software assets across the organization."
+  "safeguardId": "5.1",
+  "include_examples": true
 }
 ```
 
-### Secondary Action: Analyze Vendor Response
+### Secondary Action: List All Safeguards
 
-Configure this action for capability determination:
+Configure this action for safeguard discovery:
 
 **Action Details:**
-- **Name**: Analyze Vendor Response
-- **Description**: Determine appropriate capability role for vendor response text
+- **Name**: List CIS Safeguards
+- **Description**: Get complete list of available CIS Controls safeguards
 - **Connector**: Framework MCP Custom Connector
-- **Operation**: `analyzeVendorResponse`
-
-**Parameters:**
-- **vendor_name** (Required): Name of the vendor
-- **safeguard_id** (Required): CIS safeguard ID
-- **response_text** (Required): Vendor response text to analyze
-
-### Additional Actions: Safeguard Information
-
-**Get Safeguard Details:**
-- **Operation**: `getSafeguardDetails`
-- **Parameters**: safeguard_id, include_examples (optional)
+- **Operation**: `listSafeguards`
 
-**List Available Safeguards:**
-- **Operation**: `listAvailableSafeguards`  
-- **Parameters**: None
+**No Parameters Required**
 
 ## Example User Interactions
 
-Once configured, users can interact with your Copilot using natural language:
+Once configured, users can interact with your Copilot using natural language for LLM-driven analysis:
 
-### Capability Validation Examples
+### LLM-Driven Capability Assessment
 
 ```
-"Validate this vendor capability: Microsoft Defender for Endpoint claims FULL coverage for safeguard 1.1. Their response: 'Microsoft Defender provides comprehensive asset discovery, detailed hardware and software inventory, and real-time asset status monitoring across all enterprise endpoints.'"
+"Get details for safeguard 1.1, then analyze Microsoft Defender for Endpoint's capability: 'Microsoft Defender provides comprehensive asset discovery, detailed hardware and software inventory, and real-time asset status monitoring across all enterprise endpoints.' Determine appropriate capability role and provide confidence assessment."
 
-"Check if CrowdStrike Falcon can provide PARTIAL coverage for safeguard 5.1 based on this: 'We offer centralized identity integration with detailed user account tracking and automated access reviews.'"
+"Retrieve safeguard 5.1 requirements and assess CrowdStrike Falcon: 'We offer centralized identity integration with detailed user account tracking and automated access reviews.' Consider enterprise environment and provide implementation recommendations."
 
-"Validate this FACILITATES claim: Qualys VMDR for safeguard 1.1 - 'Our vulnerability scanner enhances existing asset management by providing additional device discovery and detailed software inventory during security assessments.'"
+"Get safeguard 6.3 details. For a financial services organization with strict compliance requirements, analyze Okta's MFA solution: 'We provide comprehensive multi-factor authentication for all external applications with adaptive authentication policies, risk-based assessments, and SSO integration.'"
 ```
 
-### Response Analysis Examples
+### Comparative Analysis Examples
 
 ```
-"Analyze this vendor response for safeguard 6.3: Okta - 'We provide comprehensive multi-factor authentication for all external applications with adaptive authentication policies, risk-based assessments, and SSO integration.'"
+"Get safeguard 7.1 details and compare these vulnerability management solutions: 1) Rapid7 InsightVM: 'Continuous vulnerability scanning with automated remediation guidance' 2) Qualys VMDR: 'Cloud-based vulnerability scanning with patch prioritization' 3) Tenable Nessus: 'Comprehensive vulnerability assessment with compliance reporting'. Rank by implementation completeness."
 
-"What capability role should we assign to this response for safeguard 7.1: Rapid7 InsightVM - 'Our platform performs continuous vulnerability scanning, provides automated remediation guidance, and tracks patch deployment across the infrastructure.'"
+"Retrieve details for safeguards 13.1, 13.3, and 13.6. Analyze how SentinelOne addresses these network monitoring requirements and identify any coverage gaps."
 ```
 
-### Information Requests
+### Data Discovery Requests
 
 ```
-"What are the requirements for CIS safeguard 1.1?"
+"Show me all available CIS safeguards related to identity and access management."
 
-"Show me all available CIS safeguards in the inventory domain."
+"Get detailed breakdown of safeguard 11.1 including all sub-elements and governance requirements."
 
-"What's the difference between FULL and PARTIAL capability roles?"
+"List all Implementation Group 1 (IG1) safeguards for a small business security assessment."
 ```
 
 ## Advanced Configuration
@@ -201,20 +184,24 @@ Once configured, users can interact with your Copilot using natural language:
 Add these instructions to your Copilot's system message:
 
 ```
-You are a CIS Controls capability assessment expert. You help security professionals evaluate vendor tool capabilities against specific CIS Control safeguards.
+You are a CIS Controls expert powered by Framework MCP's Pure Data Provider architecture. You help security professionals perform sophisticated vendor capability analysis using authoritative CIS Controls data.
 
 Key Principles:
-1. Use validate_vendor_mapping for evidence-based validation of capability claims
-2. Use analyze_vendor_response when the capability role is unknown
-3. Always explain the 5 capability roles: FULL, PARTIAL, FACILITATES, GOVERNANCE, VALIDATES
-4. Highlight domain validation results and auto-downgrade protection
-5. Provide actionable recommendations for capability improvements
-
-When users provide vendor responses:
-1. Ask for the specific CIS safeguard ID if not provided
-2. Determine if they want validation (they have a claimed capability) or analysis (no claimed capability)
-3. Use the appropriate action and explain the results in plain language
-4. Highlight any domain mismatches or auto-downgrades that occurred
+1. Always retrieve detailed safeguard data using get_safeguard_details before analysis
+2. Apply context-aware analysis considering industry, risk profile, and organizational needs
+3. Explain the 5 capability roles: FULL, PARTIAL, FACILITATES, GOVERNANCE, VALIDATES
+4. Provide transparent reasoning with evidence-based assessments
+5. Offer implementation recommendations and deployment guidance
+
+Analysis Approach:
+1. Get safeguard requirements using the data actions
+2. Analyze vendor capabilities against detailed CIS requirements
+3. Consider organizational context (industry, size, risk tolerance)
+4. Provide capability role determination with confidence assessment
+5. Include implementation recommendations and integration considerations
+6. For comparative analysis, rank vendors and explain reasoning
+
+Flexibility: Adapt analysis methodology based on user needs - strict compliance, risk-based assessment, technology integration, or custom evaluation criteria.
 ```
 
 ### Environment Variables

package/DEPLOYMENT_GUIDE.md

@@ -1,11 +1,11 @@
 # Framework MCP Deployment Guide
 
-## Dual Architecture: MCP + HTTP API
+## Pure Data Provider Architecture: MCP + HTTP API
 
-Framework MCP v1.3.7 features a **dual architecture** that solves the DigitalOcean App Services stdio vs HTTP mismatch:
+Framework MCP v1.4.0 features a **Pure Data Provider architecture** with dual interfaces for maximum flexibility:
 
-- **MCP Interface**: stdio-based for Claude Code integration
-- **HTTP Interface**: REST API for cloud deployment
+- **MCP Interface**: stdio-based for Claude Code integration with LLM-driven analysis
+- **HTTP Interface**: REST API for cloud deployment and Microsoft Copilot integration
 
 ---
 
@@ -146,38 +146,20 @@ GET /health
 # Returns server status and metrics
 ```
 
-### Primary Validation
+### Data Endpoints (Pure Provider Architecture)
 ```bash
-POST /api/validate-vendor-mapping
-{
-  "vendor_name": "AssetMax Pro",
-  "safeguard_id": "1.1", 
-  "claimed_capability": "full",
-  "supporting_text": "Comprehensive asset management..."
-}
+GET /api/safeguards              # List all 153 CIS safeguards
+GET /api/safeguards/1.1         # Get detailed safeguard breakdown
+GET /api/safeguards/1.1?include_examples=true  # Include implementation examples
 ```
 
-### Capability Analysis
-```bash
-POST /api/analyze-vendor-response
-{
-  "vendor_name": "VendorName",
-  "safeguard_id": "5.1",
-  "response_text": "Our identity management solution..."
-}
-```
-
-### Safeguards
+### Monitoring
 ```bash
-GET /api/safeguards              # List all safeguards
-GET /api/safeguards/1.1         # Get safeguard details
-GET /api/safeguards/1.1?include_examples=true
+GET /api/metrics                # Performance metrics and statistics
+GET /api                        # API documentation and capabilities
 ```
 
-### Performance
-```bash
-GET /api/metrics                # Performance metrics
-```
+**LLM-Driven Analysis**: The Pure Data Provider architecture supplies authoritative CIS data while LLMs perform sophisticated vendor capability analysis with unlimited flexibility.
 
 ---
 
@@ -185,45 +167,62 @@ GET /api/metrics                # Performance metrics
 
 ### HTTP Interface Advantages
 - ✅ **DigitalOcean Compatible**: Uses HTTP instead of stdio
-- ✅ **REST API**: Standard HTTP endpoints
+- ✅ **REST API**: Standard HTTP endpoints for data access
 - ✅ **Health Checks**: Platform monitoring support
 - ✅ **CORS Enabled**: Web application integration
 - ✅ **Production Ready**: Error handling, security, compression
+- ✅ **Microsoft Copilot**: Custom connector compatibility
 
 ### MCP Interface Advantages  
 - ✅ **Claude Code Integration**: Native stdio communication
 - ✅ **Tool Discovery**: Automatic tool registration
 - ✅ **Type Safety**: Full MCP schema validation
-- ✅ **Rich Responses**: Structured tool responses
+- ✅ **LLM-Driven Analysis**: Direct access to safeguards data for intelligent analysis
 
-### Shared Core Benefits
-- ✅ **Identical Functionality**: Both interfaces use same logic
-- ✅ **Content Analysis**: Comprehensive capability assessment in both
-- ✅ **Performance**: 95% cache optimization in both
-- ✅ **Consistency**: Same capability assessment results
+### Pure Data Provider Benefits
+- ✅ **Clean Architecture**: Simple data provision without analysis complexity
+- ✅ **LLM Flexibility**: Unlimited analysis approaches and methodologies
+- ✅ **Performance Optimized**: Fast data retrieval for real-time analysis
+- ✅ **Context-Aware**: LLMs can apply industry, risk, and organizational context
+- ✅ **Transparent Reasoning**: Full visibility into analysis logic and evidence
 
 ---
 
 ## Migration Guide
 
-### From MCP-Only to Dual Architecture
+### Migrating to Pure Data Provider v1.4.0
 
-1. **No Breaking Changes**: Existing MCP integrations continue working
-2. **New HTTP Option**: Add cloud deployment capability
-3. **Gradual Adoption**: Choose interface based on use case
+1. **Simplified Architecture**: Analysis logic moved to LLM capability
+2. **Enhanced Flexibility**: Unlimited analysis approaches and methodologies
+3. **Maintained Compatibility**: Both interfaces continue providing data access
+4. **Improved Performance**: Optimized for fast data retrieval
 
 ### Use Case Guidelines
 
 **Use MCP Interface When:**
-- Integrating with Claude Code
+- Integrating with Claude Code for LLM-driven analysis
 - Local development and testing
-- Tool-based LLM interactions
+- Direct tool-based interactions with LLMs
 
 **Use HTTP Interface When:**
-- Cloud deployment required
-- Web application integration
-- API-based access needed
-- DigitalOcean App Services deployment
+- Cloud deployment required (DigitalOcean, Railway, Render)
+- Microsoft Copilot custom connector integration
+- Web application or API-based access needed
+- Distributed team access to CIS Controls data
+
+### Analysis Pattern Migration
+
+**Old Approach (v1.3.7):**
+```bash
+POST /api/analyze-vendor-response
+# Hardcoded analysis with fixed validation rules
+```
+
+**New Approach (v1.4.0):**
+```bash
+GET /api/safeguards/5.1
+# Get authoritative data, then use LLM for sophisticated analysis
+```
 
 ---