framework-mcp 1.5.2 → 2.2.2

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

@@ -4,7 +4,9 @@ import express from 'express';
 import cors from 'cors';
 import helmet from 'helmet';
 import compression from 'compression';
+import rateLimit from 'express-rate-limit';
 import { SafeguardManager } from '../../core/safeguard-manager.js';
+import { RateLimitConfig, RateLimitErrorResponse } from '../../shared/types.js';
 
 interface ErrorResponse {
   error: string;
@@ -16,18 +18,54 @@ export class FrameworkHttpServer {
   private app: express.Application;
   private safeguardManager: SafeguardManager;
   private port: number;
+  private rateLimitConfig: RateLimitConfig;
 
   constructor(port: number = 8080) {
     this.app = express();
     this.safeguardManager = new SafeguardManager();
     this.port = port;
-    
+    this.rateLimitConfig = this.parseRateLimitConfig();
+
     this.setupMiddleware();
     this.setupRoutes();
     this.setupErrorHandling();
   }
 
+  private parseRateLimitConfig(): RateLimitConfig {
+    const skipIpsEnv = process.env.RATE_LIMIT_SKIP_IPS;
+    return {
+      windowMs: parseInt(process.env.RATE_LIMIT_WINDOW_MS || '60000', 10),
+      max: parseInt(process.env.RATE_LIMIT_MAX || '100', 10),
+      skipIps: skipIpsEnv ? skipIpsEnv.split(',').map(ip => ip.trim()) : undefined
+    };
+  }
+
   private setupMiddleware(): void {
+    // Rate limiting middleware - must be before other middleware
+    const limiter = rateLimit({
+      windowMs: this.rateLimitConfig.windowMs,
+      max: this.rateLimitConfig.max,
+      standardHeaders: true,
+      legacyHeaders: false,
+      skip: (req) => {
+        if (this.rateLimitConfig.skipIps && req.ip) {
+          return this.rateLimitConfig.skipIps.includes(req.ip);
+        }
+        return false;
+      },
+      message: {
+        error: 'Too many requests',
+        retryAfter: 'See Retry-After header',
+        timestamp: new Date().toISOString()
+      },
+      handler: (req, res, _next, options) => {
+        console.log(`[Rate Limit] IP ${req.ip} exceeded limit`);
+        res.status(429).json(options.message);
+      }
+    });
+
+    this.app.use(limiter);
+
     // Security middleware
     this.app.use(helmet({
       contentSecurityPolicy: {
@@ -68,11 +106,78 @@ export class FrameworkHttpServer {
       res.json({
         status: 'healthy',
         uptime: Math.round(process.uptime()),
-        version: '1.5.2',
+        version: '2.2.2',
         timestamp: new Date().toISOString()
       });
     });
 
+    // Safeguards health check endpoint - validates data completeness
+    this.app.get('/api/health/safeguards', (req, res) => {
+      try {
+        const allSafeguards = this.safeguardManager.getAllSafeguards();
+        const safeguardIds = Object.keys(allSafeguards);
+
+        let totalValidated = 0;
+        let errors: string[] = [];
+        const expectedFields = [
+          'systemPromptFull',
+          'systemPromptPartial',
+          'systemPromptFacilitates',
+          'systemPromptGovernance',
+          'systemPromptValidates'
+        ];
+
+        for (const safeguardId of safeguardIds) {
+          const safeguard = allSafeguards[safeguardId];
+
+          // Check all five capability prompts exist and are complete
+          for (const field of expectedFields) {
+            const prompt = (safeguard as any)[field];
+            if (!prompt) {
+              errors.push(`${safeguardId}: Missing ${field}`);
+              continue;
+            }
+
+            if (!prompt.role || !prompt.context || !prompt.objective ||
+                !prompt.guidelines || !prompt.outputFormat) {
+              errors.push(`${safeguardId}.${field}: Incomplete structure`);
+            }
+          }
+
+          // Check deprecated field is gone
+          if ('systemPrompt' in safeguard) {
+            errors.push(`${safeguardId}: Deprecated systemPrompt field exists`);
+          }
+
+          totalValidated++;
+        }
+
+        res.json({
+          status: errors.length === 0 ? 'healthy' : 'unhealthy',
+          safeguards: {
+            total: totalValidated,
+            expected: 153,
+            complete: totalValidated === 153 && errors.length === 0
+          },
+          capabilityPrompts: {
+            expectedFields: expectedFields.length,
+            validatedFields: expectedFields.length
+          },
+          errors: errors.length,
+          errorDetails: errors.slice(0, 10), // Show first 10 errors only
+          timestamp: new Date().toISOString()
+        });
+
+      } catch (error) {
+        res.status(500).json({
+          status: 'error',
+          message: 'Failed to validate safeguards data',
+          error: error instanceof Error ? error.message : 'Unknown error',
+          timestamp: new Date().toISOString()
+        });
+      }
+    });
+
 
 
     // Get safeguard details endpoint
@@ -117,7 +222,7 @@ export class FrameworkHttpServer {
     this.app.get('/api', (req, res) => {
       res.json({
         name: 'Framework MCP HTTP API',
-        version: '1.5.2',
+        version: '2.2.2',
         description: 'Pure Data Provider serving authentic CIS Controls Framework data',
         endpoints: {
           'GET /api/safeguards': 'List all available CIS safeguards',
@@ -168,7 +273,7 @@ export class FrameworkHttpServer {
 
   public start(): void {
     this.app.listen(this.port, '0.0.0.0', () => {
-      console.log(`🚀 Framework MCP HTTP Server v1.5.2 running on port ${this.port}`);
+      console.log(`🚀 Framework MCP HTTP Server v2.2.0 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

@@ -18,7 +18,7 @@ export class FrameworkMcpServer {
     this.server = new Server(
       {
         name: 'framework-analyzer',
-        version: '1.5.2',
+        version: '2.2.2',
       }
     );
 
@@ -129,7 +129,7 @@ export class FrameworkMcpServer {
             safeguards,
             total: safeguards.length,
             framework: 'CIS Controls v8.1',
-            version: '1.5.2'
+            version: '2.2.2'
           }, null, 2),
         },
       ],
@@ -153,7 +153,7 @@ export class FrameworkMcpServer {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);
     
-    console.error('🤖 Framework MCP Server v1.5.2 running via stdio');
+    console.error('🤖 Framework MCP Server v2.2.0 running via stdio');
     console.error('📊 Pure Data Provider for CIS Controls v8.1');
   }
 }

package/src/shared/types.ts

@@ -1,5 +1,30 @@
 // Shared TypeScript types for dual architecture
 
+// Enhanced relationship type system for v1.5.4+
+export type RelationshipType =
+  | 'dependency'      // Must be implemented for this to work
+  | 'prerequisite'    // Should be implemented first
+  | 'complement'      // Work together synergistically
+  | 'supports'        // Enhanced by this safeguard
+  | 'validates'       // Provides evidence/validation
+  | 'governance'      // Provides oversight/policy
+  | 'sequence';       // Part of logical implementation sequence
+
+export type RelationshipStrength =
+  | 'critical'        // Essential relationship
+  | 'strong'         // Important relationship
+  | 'moderate'       // Useful relationship
+  | 'weak';          // Minor relationship
+
+export interface SafeguardRelationship {
+  id: string;                    // Target safeguard ID
+  type: RelationshipType;        // Why they're related
+  strength: RelationshipStrength; // How important the relationship is
+  context: string;               // Brief human-readable explanation
+  bidirectional: boolean;        // Whether reverse relationship exists
+  controlGroup?: string;         // Optional CIS Control grouping
+}
+
 export interface SafeguardElement {
   id: string;
   title: string;
@@ -12,15 +37,49 @@ export interface SafeguardElement {
   coreRequirements: string[];        // Green - The "what" of the safeguard
   subTaxonomicalElements: string[];  // Yellow - Sub-taxonomical elements
   implementationSuggestions: string[]; // Gray - Suggestions for implementation
+
+  // Backward compatibility - existing consumers still get string[]
   relatedSafeguards: string[];
-  keywords: string[];
-  systemPrompt?: {
+
+  // Enhanced relationships - new optional field for rich relationship data
+  enhancedRelationships?: SafeguardRelationship[];
+
+  // Capability-specific system prompts for different evaluation levels
+  systemPromptFull?: {
     role: string;           // e.g., "asset_inventory_expert", "access_control_specialist"
     context: string;        // Brief context about the safeguard for AI understanding
     objective: string;      // What the AI should accomplish
     guidelines: string[];   // Specific evaluation criteria and methods
     outputFormat: string;   // Expected response structure for n8n processing
   };
+  systemPromptPartial?: {
+    role: string;
+    context: string;
+    objective: string;
+    guidelines: string[];
+    outputFormat: string;
+  };
+  systemPromptFacilitates?: {
+    role: string;
+    context: string;
+    objective: string;
+    guidelines: string[];
+    outputFormat: string;
+  };
+  systemPromptGovernance?: {
+    role: string;
+    context: string;
+    objective: string;
+    guidelines: string[];
+    outputFormat: string;
+  };
+  systemPromptValidates?: {
+    role: string;
+    context: string;
+    objective: string;
+    guidelines: string[];
+    outputFormat: string;
+  };
 }
 
 export interface VendorAnalysis {
@@ -69,3 +128,210 @@ export interface QualityAssessment {
 
 export type CapabilityType = 'full' | 'partial' | 'facilitates' | 'governance' | 'validates';
 
+// Utility functions for enhanced relationship system
+
+/**
+ * Converts SafeguardRelationship[] to string[] for backward compatibility
+ */
+export function relationshipsToStringArray(relationships: SafeguardRelationship[]): string[] {
+  return relationships.map(rel => rel.id);
+}
+
+/**
+ * Converts string[] to basic SafeguardRelationship[] (when migrating legacy data)
+ */
+export function stringArrayToRelationships(
+  ids: string[],
+  defaultType: RelationshipType = 'supports',
+  defaultStrength: RelationshipStrength = 'moderate'
+): SafeguardRelationship[] {
+  return ids.map(id => ({
+    id,
+    type: defaultType,
+    strength: defaultStrength,
+    context: `Legacy relationship to ${id}`,
+    bidirectional: false
+  }));
+}
+
+/**
+ * Validates that all referenced safeguard IDs exist in the provided set
+ */
+export function validateSafeguardReferences(
+  relationships: SafeguardRelationship[],
+  validSafeguardIds: Set<string>
+): ValidationResult {
+  const invalidIds: string[] = [];
+
+  for (const rel of relationships) {
+    if (!validSafeguardIds.has(rel.id)) {
+      invalidIds.push(rel.id);
+    }
+  }
+
+  return {
+    isValid: invalidIds.length === 0,
+    errors: invalidIds.map(id => `Invalid safeguard ID reference: ${id}`)
+  };
+}
+
+/**
+ * Validates bidirectional relationship consistency
+ * Returns relationships that claim to be bidirectional but lack reverse relationships
+ */
+export function validateBidirectionalConsistency(
+  safeguardId: string,
+  relationships: SafeguardRelationship[],
+  allSafeguards: Map<string, SafeguardElement>
+): ValidationResult {
+  const errors: string[] = [];
+
+  for (const rel of relationships) {
+    if (rel.bidirectional) {
+      const targetSafeguard = allSafeguards.get(rel.id);
+      if (!targetSafeguard?.enhancedRelationships) {
+        errors.push(`Bidirectional relationship with ${rel.id} but target has no enhanced relationships`);
+        continue;
+      }
+
+      const reverseRelExists = targetSafeguard.enhancedRelationships.some(
+        reverseRel => reverseRel.id === safeguardId && reverseRel.bidirectional
+      );
+
+      if (!reverseRelExists) {
+        errors.push(`Bidirectional relationship with ${rel.id} but no reverse relationship found`);
+      }
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validates relationship data integrity for a single safeguard
+ */
+export function validateSafeguardRelationships(
+  safeguard: SafeguardElement,
+  allSafeguards: Map<string, SafeguardElement>
+): ValidationResult {
+  const errors: string[] = [];
+
+  if (!safeguard.enhancedRelationships) {
+    // Only validate basic string array consistency
+    if (safeguard.relatedSafeguards.length === 0) {
+      return { isValid: true, errors: [] };
+    }
+
+    const validIds = new Set(allSafeguards.keys());
+    const invalidBasicRefs = safeguard.relatedSafeguards.filter(id => !validIds.has(id));
+    if (invalidBasicRefs.length > 0) {
+      errors.push(...invalidBasicRefs.map(id => `Invalid basic reference: ${id}`));
+    }
+  } else {
+    // Validate enhanced relationships
+    const validIds = new Set(allSafeguards.keys());
+    const refValidation = validateSafeguardReferences(safeguard.enhancedRelationships, validIds);
+    errors.push(...refValidation.errors);
+
+    const bidirValidation = validateBidirectionalConsistency(
+      safeguard.id,
+      safeguard.enhancedRelationships,
+      allSafeguards
+    );
+    errors.push(...bidirValidation.errors);
+
+    // Validate consistency between legacy and enhanced relationships
+    const enhancedIds = new Set(relationshipsToStringArray(safeguard.enhancedRelationships));
+    const legacyIds = new Set(safeguard.relatedSafeguards);
+
+    // Check if legacy array matches enhanced relationships
+    if (enhancedIds.size !== legacyIds.size ||
+        !Array.from(enhancedIds).every(id => legacyIds.has(id))) {
+      errors.push('Mismatch between relatedSafeguards and enhancedRelationships arrays');
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Finds potential circular dependencies in relationships
+ */
+export function detectCircularDependencies(
+  allSafeguards: Map<string, SafeguardElement>
+): ValidationResult {
+  const errors: string[] = [];
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+
+  function dfs(safeguardId: string, path: string[]): void {
+    if (recursionStack.has(safeguardId)) {
+      errors.push(`Circular dependency detected: ${[...path, safeguardId].join(' -> ')}`);
+      return;
+    }
+
+    if (visited.has(safeguardId)) {
+      return;
+    }
+
+    visited.add(safeguardId);
+    recursionStack.add(safeguardId);
+
+    const safeguard = allSafeguards.get(safeguardId);
+    if (safeguard?.enhancedRelationships) {
+      const dependencies = safeguard.enhancedRelationships.filter(
+        rel => rel.type === 'dependency' || rel.type === 'prerequisite'
+      );
+
+      for (const dep of dependencies) {
+        dfs(dep.id, [...path, safeguardId]);
+      }
+    }
+
+    recursionStack.delete(safeguardId);
+  }
+
+  // Check all safeguards for circular dependencies
+  for (const safeguardId of allSafeguards.keys()) {
+    if (!visited.has(safeguardId)) {
+      dfs(safeguardId, []);
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+}
+
+export interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+// Rate Limiting Types (v2.2.0+)
+
+/**
+ * Configuration for rate limiting middleware
+ */
+export interface RateLimitConfig {
+  windowMs: number;      // Time window in milliseconds
+  max: number;           // Maximum requests per window
+  skipIps?: string[];    // IP addresses to exempt from rate limiting
+}
+
+/**
+ * Error response returned when rate limit is exceeded
+ */
+export interface RateLimitErrorResponse {
+  error: string;         // Error message
+  retryAfter?: number;   // Seconds until rate limit resets
+  timestamp: string;     // ISO 8601 timestamp
+}
+

package/swagger.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "Framework MCP API - Pure Data Provider",
     "description": "Microsoft Copilot-compatible API providing authoritative CIS Controls Framework v8.1 data (153 safeguards). Pure Data Provider architecture empowers LLMs with structured safeguards data and AI-driven systemPrompts for sophisticated, context-aware vendor capability analysis and n8n workflow automation.",
-    "version": "1.5.2",
+    "version": "2.0.0",
     "contact": {
       "name": "Framework MCP Support",
       "url": "https://github.com/therealcybermattlee/FrameworkMCP"
@@ -67,7 +67,7 @@
     "/api/safeguards/{safeguardId}": {
       "get": {
         "summary": "Get Safeguard Details",
-        "description": "Get detailed information about a specific CIS safeguard including governance elements, core requirements, implementation suggestions, and AI-driven systemPrompt for n8n workflow integration",
+        "description": "Get detailed information about a specific CIS safeguard including governance elements, core requirements, implementation suggestions, and five capability-specific AI-driven system prompts for n8n workflow integration",
         "operationId": "getSafeguardDetails",
         "tags": ["Safeguards"],
         "parameters": [
@@ -256,40 +256,25 @@
             },
             "description": "Implementation methods and suggestions (Gray elements)"
           },
-          "systemPrompt": {
-            "type": "object",
-            "description": "AI-driven system prompt for n8n workflow automation and vendor analysis",
-            "properties": {
-              "role": {
-                "type": "string",
-                "description": "Expert role for the specific control type",
-                "example": "asset_inventory_expert"
-              },
-              "context": {
-                "type": "string",
-                "description": "Brief context about the safeguard for AI understanding",
-                "example": "You are evaluating enterprise asset inventory solutions against CIS Control 1.1 requirements"
-              },
-              "objective": {
-                "type": "string", 
-                "description": "What the AI should accomplish",
-                "example": "Determine if vendor solution provides complete asset inventory capabilities"
-              },
-              "guidelines": {
-                "type": "array",
-                "items": {
-                  "type": "string"
-                },
-                "description": "Specific evaluation criteria and methods",
-                "example": ["Verify coverage of all asset types", "Confirm data collection accuracy"]
-              },
-              "outputFormat": {
-                "type": "string",
-                "description": "Expected response structure for n8n processing",
-                "example": "Provide structured assessment with capability level (FULL/PARTIAL/FACILITATES/GOVERNANCE/VALIDATES), confidence score, and evidence summary"
-              }
-            },
-            "required": ["role", "context", "objective", "guidelines", "outputFormat"]
+          "systemPromptFull": {
+            "$ref": "#/components/schemas/SystemPromptStructure",
+            "description": "AI-driven system prompt for FULL capability evaluation"
+          },
+          "systemPromptPartial": {
+            "$ref": "#/components/schemas/SystemPromptStructure",
+            "description": "AI-driven system prompt for PARTIAL capability evaluation"
+          },
+          "systemPromptFacilitates": {
+            "$ref": "#/components/schemas/SystemPromptStructure",
+            "description": "AI-driven system prompt for FACILITATES capability evaluation"
+          },
+          "systemPromptGovernance": {
+            "$ref": "#/components/schemas/SystemPromptStructure",
+            "description": "AI-driven system prompt for GOVERNANCE capability evaluation"
+          },
+          "systemPromptValidates": {
+            "$ref": "#/components/schemas/SystemPromptStructure",
+            "description": "AI-driven system prompt for VALIDATES capability evaluation"
           }
         }
       },
@@ -314,7 +299,7 @@
           },
           "version": {
             "type": "string",
-            "example": "1.5.2"
+            "example": "1.5.3"
           },
           "timestamp": {
             "type": "string",
@@ -359,7 +344,7 @@
           },
           "version": {
             "type": "string",
-            "example": "1.5.2"
+            "example": "1.5.3"
           },
           "description": {
             "type": "string",
@@ -405,6 +390,41 @@
             "format": "date-time"
           }
         }
+      },
+      "SystemPromptStructure": {
+        "type": "object",
+        "description": "AI-driven system prompt structure for vendor capability analysis",
+        "properties": {
+          "role": {
+            "type": "string",
+            "description": "Expert role for the specific control type",
+            "example": "asset_inventory_expert"
+          },
+          "context": {
+            "type": "string",
+            "description": "Brief context about the safeguard for AI understanding",
+            "example": "You are evaluating enterprise asset inventory solutions against CIS Control 1.1 requirements"
+          },
+          "objective": {
+            "type": "string",
+            "description": "What the AI should accomplish",
+            "example": "Determine if vendor solution provides complete asset inventory capabilities"
+          },
+          "guidelines": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Specific evaluation criteria and methods",
+            "example": ["Verify coverage of all asset types", "Confirm data collection accuracy"]
+          },
+          "outputFormat": {
+            "type": "string",
+            "description": "Expected response structure for n8n processing",
+            "example": "Provide structured assessment with capability level (FULL/PARTIAL/FACILITATES/GOVERNANCE/VALIDATES), confidence score, and evidence summary"
+          }
+        },
+        "required": ["role", "context", "objective", "guidelines", "outputFormat"]
       }
     }
   },