@compligent-mcp/csf/README.md

Compligent MCP Client - NIST CSF 2.0 with OAuth 2.1 PKCE authentication via Unified Gateway

# Compligent CSF 2.0 MCP Client

[![npm version](https://badge.fury.io/js/%40compligent-mcp%2Fcsf.svg)](https://badge.fury.io/js/%40compligent-mcp%2Fcsf)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A thin MCP client that connects to Compligent's hosted NIST CSF 2.0 compliance database through an OAuth 2.1 authenticated gateway, providing access to 11 cybersecurity framework tools and 12 prompts through the Model Context Protocol.

## ✨ Features

- **🚀 Easy NPX Installation**: Get started in seconds with `npx @compligent-mcp/csf`
- **🔐 OAuth 2.1 Authentication**: Secure GitHub SSO with tier-based access control
- **☁️ Hosted Database**: Connect to Compligent's integrated compliance database
- **🛠️ 11 Tools + 12 Prompts**: Complete CSF 2.0 toolkit via MCP protocol
- **🎯 Tier-Based Access**: Community, Beta, Pro, and Enterprise tiers
- **⚡ Real-time Updates**: Always access the latest cybersecurity framework data
- **🌐 Cross-Framework Integration**: Built-in mappings to SP 800-53, NICE, and other frameworks

## 🎯 Available Tools

### Core Tools (6)
- `list_csf_functions` - List all 6 CSF 2.0 functions (GOVERN, IDENTIFY, PROTECT, DETECT, RESPOND, RECOVER)
- `list_csf_categories` - List categories with function filtering
- `list_csf_subcategories` - List all subcategories with detailed information
- `get_csf_category` - Get detailed category information
- `get_csf_subcategory` - Get specific subcategory with implementation guidance
- `search_csf_subcategories` - Search subcategories by keyword

### Enhanced Tools (5)
- `get_csf_implementation_examples` - Get practical implementation examples
- `generate_csf_assessment_plan` - Generate comprehensive assessment plans
- `analyze_csf_maturity` - Analyze organizational maturity against CSF
- `generate_csf_roadmap` - Generate implementation roadmap
- `map_csf_to_controls` - Map CSF subcategories to security controls

## 🚀 Quick Start

### For Claude Desktop Users

1. **Install and configure** in your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "csf": {
      "command": "npx",
      "args": ["@compligent-mcp/csf"],
      "env": {
        "COMPLIGENT_TOKEN": "your_oauth_token_here"
      }
    }
  }
}
```

2. **Get your OAuth token**:
   - Visit: https://compligent-oauth-gateway-prod.compli.workers.dev/authorize
   - Sign in with GitHub
   - Copy your access token

3. **Restart Claude Desktop** and start using CSF 2.0 tools!

### For Direct MCP Usage

```bash
# Install globally
npm install -g @compligent-mcp/csf

# Or use with npx
npx @compligent-mcp/csf

# Authenticate first
npx @compligent-mcp/csf auth save YOUR_TOKEN

# Test the connection
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx @compligent-mcp/csf
```

## 🔧 Configuration

### Environment Variables

- `COMPLIGENT_TOKEN` (required): OAuth 2.1 access token from GitHub authentication
- `GATEWAY_URL` (optional): Override gateway URL (default: production gateway)
- `NODE_ENV` (optional): Set to `production` for production usage

### Example Usage

```json
// List all control families
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_sp53_control_families",
    "arguments": {}
  },
  "id": 1
}

// Get a specific control
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_sp53_control",
    "arguments": {
      "control_id": "AC-02"
    }
  },
  "id": 2
}

// Search controls
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_sp53_controls",
    "arguments": {
      "keyword": "access control",
      "family": "AC",
      "limit": 5
    }
  },
  "id": 3
}
```

## 📊 Data Coverage

- **CSF 2.0**: 6 functions, 23 categories, 106 subcategories
- **Implementation Examples**: 200+ practical implementation scenarios
- **Cross-Framework Mappings**: Integrated relationships to SP 800-53, NICE, CIS v8, and more
- **Maturity Assessment**: Organizational maturity analysis framework
- **Prompts**: 12 intelligent prompts for compliance guidance

## 🔐 Authentication (Required)

All requests require OAuth 2.1 authentication via GitHub:

### Quick Authentication

```bash
# Authenticate via browser (opens automatically)
npx @compligent-mcp/csf auth save YOUR_TOKEN

# Or set environment variable
export COMPLIGENT_TOKEN="your_token_here"

# Check authentication status
npx @compligent-mcp/csf auth status
```

### OAuth Flow

1. **Authorize**: Visit https://compligent-oauth-gateway-prod.compli.workers.dev/authorize
2. **Sign in**: Complete GitHub OAuth flow
3. **Copy Token**: Get your access token from the response
4. **Save**: Use `auth save` command or set environment variable

### Access Tiers

- **Community**: 50 requests/day, basic tools (list, get, search)
- **Beta**: 500 requests/day, most intelligent tools
- **Pro**: 5,000 requests/day, all tools including SSP/POA&M generation
- **Enterprise**: Unlimited, custom features, white-label support

## 🌟 Why Use This Client?

### ✅ **Advantages of Hosted Database**
- Always up-to-date compliance data
- Cross-framework relationships and mappings
- Premium bridge tools (coming soon)
- High performance and reliability
- No local data management required

### ✅ **Easy Installation**
- Simple NPX command
- No complex setup or configuration
- Works with Claude Desktop out of the box
- Compatible with any MCP client

### ✅ **Enterprise Ready**
- Built for production compliance workflows
- Optional authentication for enhanced features
- Rate limiting and usage analytics
- Professional support available

## 🛠️ Troubleshooting

### Connection Issues
```bash
# Test gateway connectivity
curl https://compligent-oauth-gateway-prod.compli.workers.dev/health

# Check authentication
npx @compligent-mcp/csf auth status

# View client logs
npx @compligent-mcp/csf 2>&1 | head -10
```

### Common Solutions
- **401 Unauthorized**: Authenticate using `npx @compligent-mcp/csf auth save YOUR_TOKEN`
- **403 Forbidden**: Tool requires higher tier - upgrade at https://compligent.io/pricing
- **429 Rate Limited**: Upgrade tier for higher limits
- **Connection Timeout**: Check internet connectivity and firewall settings

## 📈 Performance

- **Tool Listing**: < 100ms
- **Simple Queries**: < 200ms  
- **Complex Analysis**: < 2s
- **Search Operations**: < 500ms

## 🤝 Support

- **Documentation**: [https://compligent.io/docs/csf](https://compligent.io/docs/csf)
- **OAuth Gateway**: [https://compligent-oauth-gateway-prod.compli.workers.dev](https://compligent-oauth-gateway-prod.compli.workers.dev)
- **Issues**: [GitHub Issues](https://github.com/compligent/mcp-platform/issues)
- **Enterprise**: [support@compligent.io](mailto:support@compligent.io)

## 📄 License

MIT © [Compligent](https://compligent.io)

---

**🚀 Get started today:** `npx @compligent-mcp/csf`