framework-mcp 1.1.3 → 1.3.0

package/DEPLOYMENT_GUIDE.md

@@ -0,0 +1,335 @@
+# Framework MCP Deployment Guide
+
+## Dual Architecture: MCP + HTTP API
+
+Framework MCP v1.1.3 features a **dual architecture** that solves the DigitalOcean App Services stdio vs HTTP mismatch:
+
+- **MCP Interface**: stdio-based for Claude Code integration
+- **HTTP Interface**: REST API for cloud deployment
+
+---
+
+## Local Development
+
+### MCP Server (stdio)
+```bash
+# For Claude Code integration
+npm run start:mcp
+
+# Development with auto-rebuild
+npm run dev
+```
+
+### HTTP Server (Express.js)
+```bash
+# For web/cloud integration
+npm run start:http
+
+# Development with auto-rebuild  
+npm run dev:http
+```
+
+### Test Both Interfaces
+```bash
+# Build the project
+npm run build
+
+# Test MCP interface (requires Claude Code)
+npm run start:mcp
+
+# Test HTTP interface
+npm run start:http
+curl http://localhost:8080/health
+```
+
+---
+
+## Cloud Deployment
+
+### DigitalOcean App Services
+
+**The HTTP interface solves the stdio binding issue.**
+
+#### 1. Deploy via GitHub Integration
+
+1. Push your code to GitHub
+2. In DigitalOcean Dashboard:
+   - Create New App
+   - Connect GitHub repository
+   - Select branch: `feature/dual-architecture-http-api` 
+   - Use provided `.do/app.yaml` configuration
+
+#### 2. Deploy via doctl CLI
+
+```bash
+# Install doctl
+snap install doctl
+
+# Authenticate
+doctl auth init
+
+# Deploy app
+doctl apps create .do/app.yaml
+```
+
+#### 3. Manual Configuration
+
+If not using app.yaml:
+
+```yaml
+name: framework-mcp-api
+services:
+- name: api
+  run_command: npm run start:http
+  environment_slug: node-js
+  http_port: 8080
+  health_check:
+    http_path: /health
+  envs:
+  - key: NODE_ENV
+    value: production
+```
+
+### Alternative Cloud Platforms
+
+The HTTP interface is compatible with any Node.js cloud platform:
+
+#### Railway
+```bash
+railway login
+railway init
+railway up
+```
+
+#### Render
+1. Connect GitHub repository
+2. Environment: Node.js
+3. Build Command: `npm run build`
+4. Start Command: `npm run start:http`
+
+#### AWS App Runner
+1. Source: GitHub repository
+2. Runtime: Node.js 18
+3. Build command: `npm run build`
+4. Start command: `npm run start:http`
+
+---
+
+## Environment Variables
+
+### Production Configuration
+
+```bash
+# Required
+NODE_ENV=production
+PORT=8080
+
+# Optional
+ALLOWED_ORIGINS=https://your-domain.com,https://app.your-domain.com
+```
+
+### Local Development
+
+```bash
+# Optional
+NODE_ENV=development
+PORT=8080
+```
+
+---
+
+## API Endpoints
+
+### Health Check
+```bash
+GET /health
+# Returns server status and metrics
+```
+
+### Primary Validation
+```bash
+POST /api/validate-vendor-mapping
+{
+  "vendor_name": "AssetMax Pro",
+  "safeguard_id": "1.1", 
+  "claimed_capability": "full",
+  "supporting_text": "Comprehensive asset management..."
+}
+```
+
+### Capability Analysis
+```bash
+POST /api/analyze-vendor-response
+{
+  "vendor_name": "VendorName",
+  "safeguard_id": "5.1",
+  "response_text": "Our identity management solution..."
+}
+```
+
+### Safeguards
+```bash
+GET /api/safeguards              # List all safeguards
+GET /api/safeguards/1.1         # Get safeguard details
+GET /api/safeguards/1.1?include_examples=true
+```
+
+### Performance
+```bash
+GET /api/metrics                # Performance metrics
+```
+
+---
+
+## Architecture Benefits
+
+### HTTP Interface Advantages
+- ✅ **DigitalOcean Compatible**: Uses HTTP instead of stdio
+- ✅ **REST API**: Standard HTTP endpoints
+- ✅ **Health Checks**: Platform monitoring support
+- ✅ **CORS Enabled**: Web application integration
+- ✅ **Production Ready**: Error handling, security, compression
+
+### 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
+
+### Shared Core Benefits
+- ✅ **Identical Functionality**: Both interfaces use same logic
+- ✅ **Domain Validation**: Auto-downgrade protection in both
+- ✅ **Performance**: 95% cache optimization in both
+- ✅ **Consistency**: Same capability assessment results
+
+---
+
+## Migration Guide
+
+### From MCP-Only to Dual Architecture
+
+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
+
+### Use Case Guidelines
+
+**Use MCP Interface When:**
+- Integrating with Claude Code
+- Local development and testing
+- Tool-based LLM interactions
+
+**Use HTTP Interface When:**
+- Cloud deployment required
+- Web application integration
+- API-based access needed
+- DigitalOcean App Services deployment
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Build Errors**
+```bash
+# Clean rebuild
+rm -rf dist node_modules
+npm install
+npm run build
+```
+
+**Port Conflicts**
+```bash
+# Use different port
+PORT=3000 npm run start:http
+```
+
+**Health Check Failures**
+- Ensure `/health` endpoint is accessible
+- Check server startup logs
+- Verify PORT environment variable
+
+**CORS Issues**
+```bash
+# Update allowed origins
+ALLOWED_ORIGINS=https://your-domain.com npm run start:http
+```
+
+### DigitalOcean Specific
+
+**App Won't Start**
+- Check build logs for TypeScript errors
+- Verify `npm run start:http` command works locally
+- Ensure package.json scripts are correct
+
+**Health Check Fails**
+- Verify `/health` endpoint returns 200 status
+- Check `http_port: 8080` configuration
+- Review app startup time (may need longer initial_delay_seconds)
+
+**Environment Variables**
+- Set `NODE_ENV=production` in app configuration
+- Configure `PORT=8080` if not auto-detected
+
+---
+
+## Performance Optimization
+
+### Production Settings
+```bash
+NODE_ENV=production  # Enables performance logging
+```
+
+### Caching
+- Safeguard details: 5-minute TTL
+- Safeguard lists: 10-minute TTL  
+- Automatic cleanup: Every 10 minutes
+
+### Monitoring
+- Built-in performance metrics at `/api/metrics`
+- Request counting and error tracking
+- Execution time monitoring
+
+---
+
+## Security
+
+### CORS Configuration
+```javascript
+// Configurable via environment
+ALLOWED_ORIGINS=https://your-domain.com,https://app.your-domain.com
+```
+
+### Input Validation
+- Request size limits (10MB)
+- Text length validation (10-10,000 characters)
+- Capability enum validation
+- XSS prevention
+
+### Rate Limiting
+```javascript
+// Add rate limiting middleware (optional)
+npm install express-rate-limit
+```
+
+---
+
+## Success Criteria
+
+### HTTP Deployment Successful When:
+- ✅ Health check returns 200 status
+- ✅ `/api/validate-vendor-mapping` accepts POST requests
+- ✅ Domain validation auto-downgrade works correctly
+- ✅ All 5 capability roles determined accurately
+- ✅ Performance metrics show >95% cache efficiency
+
+### Ready for Production When:
+- ✅ Build completes without errors
+- ✅ Both MCP and HTTP interfaces tested
+- ✅ DigitalOcean deployment successful
+- ✅ API endpoints return expected capability analysis results
+
+---
+
+**🎉 Framework MCP v1.1.3 solves the DigitalOcean stdio vs HTTP architecture mismatch while preserving full MCP functionality!**

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