framework-mcp 1.2.0 → 1.3.1

package/COPILOT_INTEGRATION.md

@@ -0,0 +1,335 @@
+# Microsoft Copilot Integration Guide
+
+This guide provides step-by-step instructions for integrating Framework MCP 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.
+
+## Prerequisites
+
+- **Microsoft Copilot Studio** access (Microsoft 365 Business license or higher)
+- **Deployed Framework MCP HTTP API** (DigitalOcean, Railway, Render, or other cloud platform)
+- **Administrative permissions** in your Microsoft environment
+
+## Quick Start
+
+### 1. Deploy the HTTP API
+
+First, deploy Framework MCP to a cloud platform. Choose one of these options:
+
+#### Option A: DigitalOcean App Services (Recommended)
+```bash
+git clone https://github.com/therealcybermattlee/FrameworkMCP.git
+cd FrameworkMCP
+doctl apps create .do/app.yaml
+```
+
+#### Option B: Railway
+```bash
+railway login
+railway up
+```
+
+#### Option C: Render
+1. Connect your GitHub repository to Render
+2. Use these settings:
+   - **Build Command**: `npm install && npm run build`
+   - **Start Command**: `npm run start:http`
+   - **Port**: 8080
+
+### 2. Verify Deployment
+
+Test your deployed API:
+```bash
+curl https://your-api-url.com/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "uptime": 1234,
+  "totalRequests": 0,
+  "errorCount": 0,
+  "version": "1.3.1",
+  "timestamp": "2025-08-21T01:00:00.000Z"
+}
+```
+
+### 3. Create Custom Connector in Copilot Studio
+
+1. **Open Microsoft Copilot Studio**
+   - Navigate to [https://copilotstudio.microsoft.com](https://copilotstudio.microsoft.com)
+   - Sign in with your Microsoft 365 account
+
+2. **Access Custom Connectors**
+   - In the left navigation, click **Data**
+   - Select **Custom connectors**
+
+3. **Import OpenAPI Specification**
+   - Click **+ New custom connector**
+   - Choose **Import from OpenAPI file**
+   - Upload the `swagger.json` file from the Framework MCP repository
+   - Click **Continue**
+
+4. **Configure Connector Details**
+   - **Name**: Framework MCP - CIS Controls Capability Assessment
+   - **Description**: Validate vendor capability claims against CIS Controls Framework
+   - **Host**: Update to your deployed API URL (e.g., `your-app.ondigitalocean.app`)
+   - **Base URL**: `/`
+
+5. **Review and Save**
+   - Review the imported endpoints
+   - Click **Create connector**
+
+### 4. Test the Connection
+
+1. **Create Test Connection**
+   - Click **Test** in your custom connector
+   - No authentication is required (public API)
+   - Click **Create connection**
+
+2. **Test Health Endpoint**
+   - Select the `healthCheck` operation
+   - Click **Test operation**
+   - Verify you receive a 200 response with health status
+
+### 5. Create Your Copilot
+
+1. **Create New Copilot**
+   - Go to **Copilots** in Copilot Studio
+   - Click **+ New copilot**
+   - Choose **Conversational** type
+   - Name: "CIS Controls Capability Assessor"
+
+2. **Add Custom Actions**
+   - In your copilot, go to **Actions**
+   - Click **+ Add action**
+   - Select **Custom connector**
+   - Choose your Framework MCP connector
+
+## Custom Actions Configuration
+
+### Primary Action: Validate Vendor Capability
+
+Configure this action for evidence-based validation:
+
+**Action Details:**
+- **Name**: Validate Vendor Capability Mapping
+- **Description**: Validate vendor capability claims against CIS Controls with domain validation and auto-downgrade protection
+- **Connector**: Framework MCP Custom Connector
+- **Operation**: `validateVendorMapping`
+
+**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
+
+**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."
+}
+```
+
+### Secondary Action: Analyze Vendor Response
+
+Configure this action for capability determination:
+
+**Action Details:**
+- **Name**: Analyze Vendor Response
+- **Description**: Determine appropriate capability role for vendor response text
+- **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)
+
+**List Available Safeguards:**
+- **Operation**: `listSafeguards`
+- **Parameters**: None
+
+## Example User Interactions
+
+Once configured, users can interact with your Copilot using natural language:
+
+### Capability Validation Examples
+
+```
+"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.'"
+
+"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.'"
+
+"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.'"
+```
+
+### Response 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.'"
+
+"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.'"
+```
+
+### Information Requests
+
+```
+"What are the requirements for CIS safeguard 1.1?"
+
+"Show me all available CIS safeguards in the inventory domain."
+
+"What's the difference between FULL and PARTIAL capability roles?"
+```
+
+## Advanced Configuration
+
+### Custom Prompts and Instructions
+
+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.
+
+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
+```
+
+### Environment Variables
+
+If deploying with authentication or custom configuration:
+
+```bash
+# Optional environment variables for your deployed API
+NODE_ENV=production
+PORT=8080
+ALLOWED_ORIGINS=https://copilotstudio.microsoft.com,https://your-domain.com
+```
+
+### Rate Limiting and Monitoring
+
+Monitor your API usage through the `/api/metrics` endpoint:
+
+```bash
+curl https://your-api-url.com/api/metrics
+```
+
+Response includes:
+- Request counts by endpoint
+- Error rates
+- Uptime statistics
+- Performance metrics
+
+## Troubleshooting
+
+### Common Issues
+
+**Connection Failed:**
+- Verify your API URL is accessible publicly
+- Check that the `/health` endpoint returns 200
+- Ensure no authentication is required
+
+**Operations Not Working:**
+- Verify the `swagger.json` was imported correctly
+- Check that operation IDs match: `validateVendorMapping`, `analyzeVendorResponse`, etc.
+- Test operations individually in the connector test interface
+
+**Invalid Responses:**
+- Check request body format matches the schema
+- Verify required fields are provided
+- Review API error messages for validation details
+
+**Performance Issues:**
+- Monitor the `/api/metrics` endpoint for high error rates
+- Consider upgrading your cloud deployment plan
+- Check network connectivity from Microsoft's servers
+
+### Testing Checklist
+
+Before going live, test these scenarios:
+
+- [ ] Health check endpoint responds correctly
+- [ ] Validate vendor mapping with FULL claim (domain match)
+- [ ] Validate vendor mapping with FULL claim (domain mismatch - should auto-downgrade)
+- [ ] Analyze vendor response for capability determination
+- [ ] Get safeguard details for a specific safeguard
+- [ ] List all available safeguards
+- [ ] Handle invalid inputs gracefully
+
+### Support Resources
+
+- **Framework MCP Issues**: [GitHub Issues](https://github.com/therealcybermattlee/FrameworkMCP/issues)
+- **Microsoft Copilot Studio Docs**: [Microsoft Documentation](https://docs.microsoft.com/en-us/microsoft-copilot-studio/)
+- **OpenAPI Connector Guide**: [Custom Connectors in Copilot Studio](https://docs.microsoft.com/en-us/connectors/custom-connectors/)
+
+## Best Practices
+
+### Security Considerations
+
+1. **Deploy with HTTPS**: Always use HTTPS for production deployments
+2. **Monitor Usage**: Regularly check the `/api/metrics` endpoint
+3. **Rate Limiting**: Consider implementing rate limiting for high-traffic scenarios
+4. **Access Logs**: Enable logging in production for audit trails
+
+### Performance Optimization
+
+1. **CDN**: Consider using a CDN for global deployments
+2. **Caching**: The API includes intelligent caching for repeated requests
+3. **Scaling**: Use cloud platform auto-scaling for high demand
+4. **Monitoring**: Set up health check monitoring with your cloud provider
+
+### User Experience
+
+1. **Clear Instructions**: Provide users with example prompts
+2. **Error Handling**: Explain what to do when validation fails
+3. **Capability Education**: Help users understand the 5 capability roles
+4. **Domain Validation**: Explain why auto-downgrades occur
+
+## Success Metrics
+
+Track these metrics to measure integration success:
+
+- **Request Volume**: Total API calls per day/week
+- **Error Rate**: Percentage of failed requests (target: <5%)
+- **Response Time**: Average API response time (target: <500ms)
+- **User Satisfaction**: Feedback on capability assessment accuracy
+- **Coverage**: Number of unique safeguards being assessed
+
+## Next Steps
+
+After successful integration:
+
+1. **Train Users**: Provide training on the 5 capability roles and domain validation
+2. **Create Templates**: Develop standard prompts for common assessment scenarios
+3. **Integration Workflows**: Connect with existing GRC tools and processes
+4. **Feedback Loop**: Collect user feedback for continuous improvement
+5. **Scale Usage**: Expand to additional teams and use cases
+
+---
+
+**Questions or Issues?**
+- 📧 Create an issue: [GitHub Issues](https://github.com/therealcybermattlee/FrameworkMCP/issues)
+- 💬 Start a discussion: [GitHub Discussions](https://github.com/therealcybermattlee/FrameworkMCP/discussions)
+- 🐦 Follow updates: [@cybermattlee](https://twitter.com/cybermattlee)

package/README.md

@@ -34,11 +34,12 @@ The server uses the CIS Controls visual framework with color-coded categorizatio
 - **🟡 Yellow Elements**: Sub-taxonomical components
 - **⚫ Gray Elements**: Implementation suggestions and methods
 
-## 🚀 Installation
+## 🚀 Installation & Deployment
 
 ### Prerequisites
 - Node.js 18+
-- Claude Code CLI tool
+- Claude Code CLI tool (for MCP usage)
+- Microsoft Copilot Studio (for custom connector usage)
 
 ### Install from npm
 ```bash
@@ -64,9 +65,32 @@ npm install
 npm run build
 ```
 
+### Cloud Deployment Options
+
+#### Option 1: DigitalOcean App Services
+```bash
+# Deploy using the included configuration
+doctl apps create .do/app.yaml
+```
+
+#### Option 2: Railway
+```bash
+railway login
+railway up
+```
+
+#### Option 3: Render
+Connect your GitHub repository and use:
+- **Build Command**: `npm install && npm run build`
+- **Start Command**: `npm run start:http`
+- **Port**: 8080
+
+#### Option 4: Microsoft Copilot Custom Connector
+Deploy to any cloud platform and use the included `swagger.json` for Copilot integration.
+
 ## ⚙️ Configuration
 
-### Claude Code Integration
+### Claude Code MCP Integration
 
 Add to your MCP configuration file (`~/.config/claude-code/mcp.json`):
 
@@ -82,9 +106,75 @@ Add to your MCP configuration file (`~/.config/claude-code/mcp.json`):
 }
 ```
 
+### Microsoft Copilot Custom Connector Setup
+
+#### Step 1: Deploy HTTP API
+Deploy the Framework MCP HTTP API to any cloud platform (DigitalOcean, Railway, Render, etc.)
+
+#### Step 2: Create Custom Connector in Copilot Studio
+1. Open **Microsoft Copilot Studio**
+2. Navigate to **Data** → **Custom connectors**
+3. Click **+ New custom connector** → **Import from OpenAPI file**
+4. Upload the `swagger.json` file from this repository
+5. Update the **Host** field to your deployed API URL
+6. Save and test the connector
+
+#### Step 3: Configure Connection
+1. Create a new connection using your custom connector
+2. No authentication required (public API)
+3. Test with the `/health` endpoint to verify connectivity
+
+#### Step 4: Create Copilot Actions
+In your Copilot, create actions for capability assessment:
+
+**Primary Action - Validate Vendor Capability:**
+```
+Action: Validate Vendor Mapping
+Description: Validate vendor capability claims against CIS Controls with domain validation
+Connector: Framework MCP Custom Connector
+Operation: validateVendorMapping
+Parameters:
+- vendor_name: {User provided vendor name}
+- safeguard_id: {CIS safeguard ID like "1.1"}  
+- claimed_capability: {full|partial|facilitates|governance|validates}
+- supporting_text: {Vendor response text}
+```
+
+**Secondary Action - Analyze Response:**
+```
+Action: Analyze Vendor Response
+Description: Determine appropriate capability role for vendor response
+Connector: Framework MCP Custom Connector
+Operation: analyzeVendorResponse
+Parameters:
+- vendor_name: {User provided vendor name}
+- safeguard_id: {CIS safeguard ID}
+- response_text: {Vendor response to analyze}
+```
+
+#### Step 5: Example Copilot Prompts
+Once configured, users can interact with your Copilot:
+
+```
+"Validate this vendor capability: CrowdStrike Falcon claims FULL coverage for safeguard 1.1 with this response: 'Our platform provides comprehensive enterprise asset inventory with real-time discovery, automated classification, and continuous monitoring of all hardware and software assets.'"
+
+"Analyze this vendor response for safeguard 5.1: Microsoft Entra ID - 'We provide centralized identity management with automated user provisioning, role-based access controls, and integration with all major business applications.'"
+
+"What are the requirements for CIS safeguard 6.3?"
+```
+
 ### Verify Installation
 ```bash
+# For MCP usage
 claude-code "List available CIS Control safeguards"
+
+# For HTTP API usage  
+curl https://your-api-url.com/health
+
+# For Copilot testing
+curl -X POST https://your-api-url.com/api/validate-vendor-mapping \
+  -H "Content-Type: application/json" \
+  -d '{"vendor_name":"Test Vendor","safeguard_id":"1.1","claimed_capability":"facilitates","supporting_text":"We provide supplemental asset tracking capabilities that enhance existing inventory systems."}'
 ```
 
 ## 📋 Usage Examples
@@ -393,6 +483,9 @@ npm test
 - [API Reference](docs/api-reference.md)
 - [CIS Safeguards Reference](docs/safeguards-reference.md)
 - [Example Usage](examples/example-usage.md)
+- **[Microsoft Copilot Integration Guide](COPILOT_INTEGRATION.md)** - Complete setup guide for custom connectors
+- [Deployment Guide](DEPLOYMENT_GUIDE.md) - Cloud deployment instructions
+- [OpenAPI Specification](swagger.json) - Complete API schema for integrations
 
 ## 🐛 Troubleshooting
 

package/dist/interfaces/http/http-server.js

@@ -55,7 +55,7 @@ export class FrameworkHttpServer {
                 uptime: Math.round((Date.now() - metrics.uptime) / 1000),
                 totalRequests: metrics.totalRequests,
                 errorCount: metrics.errorCount,
-                version: '1.2.0',
+                version: '1.3.1',
                 timestamp: new Date().toISOString()
             });
         });
@@ -181,7 +181,7 @@ export class FrameworkHttpServer {
         this.app.get('/api', (req, res) => {
             res.json({
                 name: 'Framework MCP HTTP API',
-                version: '1.2.0',
+                version: '1.3.1',
                 description: 'Dual-architecture HTTP API for vendor capability assessment against CIS Controls Framework',
                 endpoints: {
                     'POST /api/validate-vendor-mapping': 'Primary capability validation with domain validation',
@@ -259,7 +259,7 @@ export class FrameworkHttpServer {
     }
     start() {
         this.app.listen(this.port, '0.0.0.0', () => {
-            console.log(`🚀 Framework MCP HTTP Server v1.2.0 running on port ${this.port}`);
+            console.log(`🚀 Framework MCP HTTP Server v1.3.1 running on port ${this.port}`);
             console.log(`📊 Health check: http://localhost:${this.port}/health`);
             console.log(`📖 API docs: http://localhost:${this.port}/api`);
             console.log(`🔧 Environment: ${process.env.NODE_ENV || 'development'}`);

package/dist/interfaces/mcp/mcp-server.js

@@ -8,7 +8,7 @@ export class FrameworkMcpServer {
     constructor() {
         this.server = new Server({
             name: 'framework-analyzer',
-            version: '1.2.0',
+            version: '1.3.1',
         });
         this.capabilityAnalyzer = new CapabilityAnalyzer();
         this.safeguardManager = new SafeguardManager();
@@ -245,7 +245,7 @@ export class FrameworkMcpServer {
                         safeguards,
                         total: safeguards.length,
                         framework: 'CIS Controls v8.1',
-                        version: '1.2.0'
+                        version: '1.3.1'
                     }, null, 2),
                 },
             ],
@@ -287,7 +287,7 @@ export class FrameworkMcpServer {
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);
-        console.error('🤖 Framework MCP Server v1.2.0 running via stdio');
+        console.error('🤖 Framework MCP Server v1.3.1 running via stdio');
         console.error('📊 Capability assessment with domain validation enabled');
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "framework-mcp",
-  "version": "1.2.0",
-  "description": "Dual-architecture server (MCP + HTTP API) for determining vendor tool capability roles against CIS Controls Framework with intelligent domain validation. DigitalOcean App Services compatible.",
+  "version": "1.3.1",
+  "description": "Dual-architecture server (MCP + HTTP API) for determining vendor tool capability roles against CIS Controls Framework with intelligent domain validation. Supports Microsoft Copilot custom connectors and DigitalOcean App Services deployment.",
   "main": "dist/interfaces/http/http-server.js",
   "type": "module",
   "scripts": {
@@ -41,7 +41,13 @@
     "vendor-analysis",
     "capability-assessment",
     "cybersecurity",
-    "framework"
+    "framework",
+    "microsoft-copilot",
+    "openapi",
+    "swagger",
+    "custom-connector",
+    "http-api",
+    "cloud-deployment"
   ],
   "author": "Matt Lee <cybermattlee@gmail.com> (https://github.com/therealcybermattlee)",
   "license": "CC-BY-4.0",

package/src/interfaces/http/http-server.ts

@@ -74,7 +74,7 @@ export class FrameworkHttpServer {
         uptime: Math.round((Date.now() - metrics.uptime) / 1000),
         totalRequests: metrics.totalRequests,
         errorCount: metrics.errorCount,
-        version: '1.2.0',
+        version: '1.3.1',
         timestamp: new Date().toISOString()
       });
     });
@@ -235,7 +235,7 @@ export class FrameworkHttpServer {
     this.app.get('/api', (req, res) => {
       res.json({
         name: 'Framework MCP HTTP API',
-        version: '1.2.0',
+        version: '1.3.1',
         description: 'Dual-architecture HTTP API for vendor capability assessment against CIS Controls Framework',
         endpoints: {
           'POST /api/validate-vendor-mapping': 'Primary capability validation with domain validation',
@@ -332,7 +332,7 @@ export class FrameworkHttpServer {
 
   public start(): void {
     this.app.listen(this.port, '0.0.0.0', () => {
-      console.log(`🚀 Framework MCP HTTP Server v1.2.0 running on port ${this.port}`);
+      console.log(`🚀 Framework MCP HTTP Server v1.3.1 running on port ${this.port}`);
       console.log(`📊 Health check: http://localhost:${this.port}/health`);
       console.log(`📖 API docs: http://localhost:${this.port}/api`);
       console.log(`🔧 Environment: ${process.env.NODE_ENV || 'development'}`);

package/src/interfaces/mcp/mcp-server.ts

@@ -20,7 +20,7 @@ export class FrameworkMcpServer {
     this.server = new Server(
       {
         name: 'framework-analyzer',
-        version: '1.2.0',
+        version: '1.3.1',
       }
     );
 
@@ -301,7 +301,7 @@ export class FrameworkMcpServer {
             safeguards,
             total: safeguards.length,
             framework: 'CIS Controls v8.1',
-            version: '1.2.0'
+            version: '1.3.1'
           }, null, 2),
         },
       ],
@@ -355,7 +355,7 @@ export class FrameworkMcpServer {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
     
-    console.error('🤖 Framework MCP Server v1.2.0 running via stdio');
+    console.error('🤖 Framework MCP Server v1.3.1 running via stdio');
     console.error('📊 Capability assessment with domain validation enabled');
   }
 }

package/swagger.json

@@ -0,0 +1,718 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Framework MCP API - CIS Controls Capability Assessment",
+    "description": "Microsoft Copilot-compatible API for vendor capability assessment against CIS Controls Framework. Determines vendor tool roles (FULL, PARTIAL, FACILITATES, GOVERNANCE, VALIDATES) with domain validation and auto-downgrade protection.",
+    "version": "1.3.1",
+    "contact": {
+      "name": "Framework MCP Support",
+      "url": "https://github.com/therealcybermattlee/FrameworkMCP"
+    },
+    "license": {
+      "name": "MIT",
+      "url": "https://opensource.org/licenses/MIT"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://your-deployment.ondigitalocean.app",
+      "description": "Production DigitalOcean App Services deployment"
+    },
+    {
+      "url": "http://localhost:8080",
+      "description": "Local development server"
+    }
+  ],
+  "paths": {
+    "/health": {
+      "get": {
+        "summary": "Health Check",
+        "description": "Check API health status and performance metrics",
+        "operationId": "healthCheck",
+        "tags": ["Monitoring"],
+        "responses": {
+          "200": {
+            "description": "Service is healthy",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HealthResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/validate-vendor-mapping": {
+      "post": {
+        "summary": "Validate Vendor Capability Mapping (PRIMARY)",
+        "description": "Primary endpoint for validating vendor capability claims against CIS safeguards with domain validation and auto-downgrade protection. Use this for evidence-based capability assessment.",
+        "operationId": "validateVendorMapping",
+        "tags": ["Capability Assessment"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/VendorMappingRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Validation completed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Safeguard not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analyze-vendor-response": {
+      "post": {
+        "summary": "Analyze Vendor Response",
+        "description": "Analyze vendor response text to determine appropriate capability role with domain validation",
+        "operationId": "analyzeVendorResponse",
+        "tags": ["Capability Assessment"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AnalysisRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Analysis completed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AnalysisResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Safeguard not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/validate-coverage-claim": {
+      "post": {
+        "summary": "Validate Coverage Claim",
+        "description": "Validate specific FULL or PARTIAL capability claims with supporting evidence",
+        "operationId": "validateCoverageClaim",
+        "tags": ["Capability Assessment"],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CoverageClaimRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Coverage claim validation completed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request parameters",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Safeguard not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/safeguards": {
+      "get": {
+        "summary": "List Available Safeguards",
+        "description": "Get a list of all available CIS Controls v8.1 safeguards (153 total)",
+        "operationId": "listSafeguards",
+        "tags": ["Safeguards"],
+        "responses": {
+          "200": {
+            "description": "List of available safeguards",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SafeguardListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/safeguards/{safeguardId}": {
+      "get": {
+        "summary": "Get Safeguard Details",
+        "description": "Get detailed information about a specific CIS safeguard including governance elements, core requirements, and implementation suggestions",
+        "operationId": "getSafeguardDetails",
+        "tags": ["Safeguards"],
+        "parameters": [
+          {
+            "name": "safeguardId",
+            "in": "path",
+            "required": true,
+            "description": "CIS safeguard ID (e.g., '1.1', '5.1', '12.8')",
+            "schema": {
+              "type": "string",
+              "pattern": "^[0-9]+\\.[0-9]+$",
+              "example": "1.1"
+            }
+          },
+          {
+            "name": "include_examples",
+            "in": "query",
+            "required": false,
+            "description": "Include implementation examples in response",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Safeguard details retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SafeguardDetails"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid safeguard ID format",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Safeguard not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/metrics": {
+      "get": {
+        "summary": "Performance Metrics",
+        "description": "Get API performance metrics and usage statistics",
+        "operationId": "getMetrics",
+        "tags": ["Monitoring"],
+        "responses": {
+          "200": {
+            "description": "Performance metrics",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MetricsResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "CapabilityRole": {
+        "type": "string",
+        "enum": ["full", "partial", "facilitates", "governance", "validates"],
+        "description": "Vendor tool capability roles:\n- FULL: Complete implementation of safeguard (requires domain-appropriate tool)\n- PARTIAL: Limited scope implementation (requires domain-appropriate tool)\n- FACILITATES: Enhancement capabilities (no tool type restrictions)\n- GOVERNANCE: Policy/process management (no tool type restrictions)\n- VALIDATES: Evidence collection and reporting (no tool type restrictions)"
+      },
+      "VendorMappingRequest": {
+        "type": "object",
+        "required": ["vendor_name", "safeguard_id", "claimed_capability", "supporting_text"],
+        "properties": {
+          "vendor_name": {
+            "type": "string",
+            "description": "Name of the vendor or tool being analyzed",
+            "minLength": 1,
+            "maxLength": 100,
+            "example": "CrowdStrike Falcon"
+          },
+          "safeguard_id": {
+            "type": "string",
+            "pattern": "^[0-9]+\\.[0-9]+$",
+            "description": "CIS safeguard ID (format: X.Y)",
+            "example": "1.1"
+          },
+          "claimed_capability": {
+            "$ref": "#/components/schemas/CapabilityRole"
+          },
+          "supporting_text": {
+            "type": "string",
+            "description": "Vendor response or documentation supporting their capability claim",
+            "minLength": 10,
+            "maxLength": 10000,
+            "example": "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."
+          }
+        }
+      },
+      "AnalysisRequest": {
+        "type": "object",
+        "required": ["vendor_name", "safeguard_id", "response_text"],
+        "properties": {
+          "vendor_name": {
+            "type": "string",
+            "description": "Name of the vendor",
+            "minLength": 1,
+            "maxLength": 100,
+            "example": "Microsoft Defender"
+          },
+          "safeguard_id": {
+            "type": "string",
+            "pattern": "^[0-9]+\\.[0-9]+$",
+            "description": "CIS safeguard ID",
+            "example": "5.1"
+          },
+          "response_text": {
+            "type": "string",
+            "description": "Vendor response text to analyze for capability determination",
+            "minLength": 10,
+            "maxLength": 10000,
+            "example": "We provide centralized account management with role-based access controls, automated provisioning and deprovisioning, and integration with Active Directory for enterprise identity management."
+          }
+        }
+      },
+      "CoverageClaimRequest": {
+        "type": "object",
+        "required": ["vendor_name", "safeguard_id", "claimed_capability", "response_text"],
+        "properties": {
+          "vendor_name": {
+            "type": "string",
+            "description": "Name of the vendor",
+            "minLength": 1,
+            "maxLength": 100,
+            "example": "Qualys VMDR"
+          },
+          "safeguard_id": {
+            "type": "string",
+            "pattern": "^[0-9]+\\.[0-9]+$",
+            "description": "CIS safeguard ID",
+            "example": "7.1"
+          },
+          "claimed_capability": {
+            "$ref": "#/components/schemas/CapabilityRole"
+          },
+          "response_text": {
+            "type": "string",
+            "description": "Supporting evidence for the capability claim",
+            "minLength": 10,
+            "maxLength": 10000,
+            "example": "Our vulnerability management platform performs continuous scanning, prioritizes vulnerabilities based on risk, provides automated remediation guidance, and tracks remediation progress across the entire infrastructure."
+          }
+        }
+      },
+      "ValidationResponse": {
+        "type": "object",
+        "properties": {
+          "vendor_name": {
+            "type": "string",
+            "example": "CrowdStrike Falcon"
+          },
+          "safeguard_id": {
+            "type": "string",
+            "example": "1.1"
+          },
+          "claimed_capability": {
+            "$ref": "#/components/schemas/CapabilityRole"
+          },
+          "validated_capability": {
+            "$ref": "#/components/schemas/CapabilityRole"
+          },
+          "validation_status": {
+            "type": "string",
+            "enum": ["SUPPORTED", "QUESTIONABLE", "UNSUPPORTED"],
+            "description": "Overall validation result"
+          },
+          "confidence_score": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100,
+            "description": "Confidence percentage in the assessment"
+          },
+          "domain_validation": {
+            "type": "object",
+            "properties": {
+              "tool_type": {
+                "type": "string",
+                "description": "Detected tool type category"
+              },
+              "domain_appropriate": {
+                "type": "boolean",
+                "description": "Whether tool type is appropriate for claimed capability"
+              },
+              "auto_downgrade_applied": {
+                "type": "boolean",
+                "description": "Whether capability was auto-downgraded due to domain mismatch"
+              }
+            }
+          },
+          "evidence_analysis": {
+            "type": "object",
+            "properties": {
+              "core_requirements_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "governance_elements_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "sub_elements_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "language_consistency_score": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              }
+            }
+          },
+          "reasoning": {
+            "type": "string",
+            "description": "Detailed explanation of the validation decision"
+          },
+          "recommendations": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Actionable recommendations for capability improvement"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "AnalysisResponse": {
+        "type": "object",
+        "properties": {
+          "vendor_name": {
+            "type": "string"
+          },
+          "safeguard_id": {
+            "type": "string"
+          },
+          "determined_capability": {
+            "$ref": "#/components/schemas/CapabilityRole"
+          },
+          "confidence_score": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 100
+          },
+          "domain_validation": {
+            "type": "object",
+            "properties": {
+              "tool_type": {
+                "type": "string"
+              },
+              "domain_appropriate": {
+                "type": "boolean"
+              }
+            }
+          },
+          "analysis_details": {
+            "type": "object",
+            "properties": {
+              "core_coverage": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "implementation_depth": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              },
+              "governance_support": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 100
+              }
+            }
+          },
+          "reasoning": {
+            "type": "string"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SafeguardListResponse": {
+        "type": "object",
+        "properties": {
+          "safeguards": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "example": "1.1"
+                },
+                "title": {
+                  "type": "string",
+                  "example": "Establish and Maintain Detailed Enterprise Asset Inventory"
+                },
+                "implementationGroup": {
+                  "type": "string",
+                  "enum": ["IG1", "IG2", "IG3"],
+                  "example": "IG1"
+                }
+              }
+            }
+          },
+          "total": {
+            "type": "integer",
+            "example": 153
+          },
+          "framework": {
+            "type": "string",
+            "example": "CIS Controls v8.1"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SafeguardDetails": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "example": "1.1"
+          },
+          "title": {
+            "type": "string",
+            "example": "Establish and Maintain Detailed Enterprise Asset Inventory"
+          },
+          "description": {
+            "type": "string",
+            "description": "Detailed description of the safeguard requirements"
+          },
+          "implementationGroup": {
+            "type": "string",
+            "enum": ["IG1", "IG2", "IG3"],
+            "example": "IG1"
+          },
+          "governanceElements": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Governance requirements that MUST be met (Orange elements)"
+          },
+          "coreRequirements": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Core 'what' requirements of the safeguard (Green elements)"
+          },
+          "subTaxonomicalElements": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sub-taxonomical components (Yellow elements)"
+          },
+          "implementationSuggestions": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Implementation methods and suggestions (Gray elements)"
+          }
+        }
+      },
+      "HealthResponse": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "example": "healthy"
+          },
+          "uptime": {
+            "type": "integer",
+            "description": "Uptime in seconds"
+          },
+          "totalRequests": {
+            "type": "integer",
+            "description": "Total requests processed"
+          },
+          "errorCount": {
+            "type": "integer",
+            "description": "Total errors encountered"
+          },
+          "version": {
+            "type": "string",
+            "example": "1.3.1"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "MetricsResponse": {
+        "type": "object",
+        "properties": {
+          "uptime_seconds": {
+            "type": "integer"
+          },
+          "total_requests": {
+            "type": "integer"
+          },
+          "error_count": {
+            "type": "integer"
+          },
+          "error_rate": {
+            "type": "string",
+            "example": "0.5%"
+          },
+          "request_counts": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "integer"
+            }
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Error message"
+          },
+          "details": {
+            "type": "string",
+            "description": "Additional error details"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      }
+    }
+  },
+  "tags": [
+    {
+      "name": "Capability Assessment",
+      "description": "Primary API endpoints for vendor capability assessment against CIS Controls"
+    },
+    {
+      "name": "Safeguards",
+      "description": "CIS Controls safeguards information and details"
+    },
+    {
+      "name": "Monitoring",
+      "description": "Health checks and performance monitoring"
+    }
+  ],
+  "externalDocs": {
+    "description": "Framework MCP GitHub Repository",
+    "url": "https://github.com/therealcybermattlee/FrameworkMCP"
+  }
+}