jquintero17/CSW-MCP-SERVER

CSW MCP Server

A Model Context Protocol (MCP) server that provides access to Cisco Secure Workload (CSW) API endpoints.

Project Structure

This repository contains two MCP server implementations:

• CSW-MCP-SERVER (Current directory): Basic server with 11 core tools for essential CSW operations
• CSW-MCP-SERVER-USERGUIDE/: Enhanced server with 55 comprehensive tools covering ~95% of CSW API functionality

Overview

This MCP server allows you to interact with Cisco Secure Workload through the Model Context Protocol, providing tools to:

• List and manage scopes
• Search inventory and network flows
• Manage agents and workspaces
• View vulnerabilities
• And much more!

For comprehensive functionality, see the directory.

Installation

1. Install dependencies:

   npm install
   

2. Build the project:

   npm run build
   

Usage

Running the Server

The server can be started in several ways:

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

Direct execution:

node dist/index.js

Configuration

Before using the CSW tools, you must configure the server with your CSW API credentials using the csw_configure tool:

{
  "cluster_url": "https://your-cluster.tetrationcloud.com",
  "api_key": "your_api_key",
  "api_secret": "your_api_secret"
}

Available Tools

Configuration

• csw_configure - Configure CSW connection with API credentials

Scopes Management

• csw_list_scopes - List all available scopes
• csw_get_scope - Get details of a specific scope

Inventory & Search

• csw_list_inventory_filters - List inventory filters
• csw_search_inventory - Search inventory based on filters
• csw_search_flows - Search network flows

Agents Management

• csw_list_agents - List CSW agents
• csw_get_agent - Get details of a specific agent

Workspaces

• csw_list_workspaces - List application policy workspaces
• csw_get_workspace - Get details of a specific workspace

Security

• csw_list_vulnerabilities - List detected vulnerabilities

API Authentication

The server uses CSW's API authentication mechanism with:

• API Key and Secret
• HMAC-SHA256 signature generation
• Timestamp-based authentication

Error Handling

The server includes comprehensive error handling for:

• Network connectivity issues
• Authentication failures
• API rate limiting
• Invalid parameters
• CSW API errors

Development

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── csw-client.ts     # CSW API client
├── config.ts         # Configuration validation
└── types.ts          # TypeScript type definitions

Building

npm run build

Examples

Basic Usage Flow

1. Configure the server:

   # Use the csw_configure tool with your credentials
   

2. List scopes:

   # Use csw_list_scopes to see available scopes
   

3. Search inventory:

   # Use csw_search_inventory with a filter and scope
   

Example API Calls

List Scopes:

{
  "page_num": 1,
  "page_size": 50
}

Search Inventory:

{
  "filter": "ip = 192.168.1.0/24",
  "scope_name": "Production",
  "limit": 100
}

Search Flows:

{
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-01T23:59:59Z",
  "filter": "src_ip = 192.168.1.1",
  "scope_name": "Production"
}

Troubleshooting

Common Issues

1. Authentication Failures

   • Verify API key and secret are correct
   • Check cluster URL format
   • Ensure API credentials have proper permissions

2. Network Issues

   • Verify connectivity to CSW cluster
   • Check firewall rules
   • Validate SSL certificates

3. API Errors

   • Check CSW API documentation for parameter requirements
   • Verify scope names exist
   • Ensure proper filter syntax

Debug Mode

Enable detailed logging by setting the environment variable:

DEBUG=csw-mcp-server npm start

Server Comparison

CSW-MCP-SERVER (Current Directory)

• Tools: 11 core tools
• Focus: Essential CSW operations
• Use Case: Basic automation and scripting
• Coverage: ~65-70% of common CSW API endpoints

CSW-MCP-SERVER-USERGUIDE

• Tools: 55 comprehensive tools
• Focus: Complete CSW API coverage
• Use Case: Advanced management and comprehensive automation
• Coverage: ~95% of CSW API functionality
• Additional Features: VRFs, Users, System Health, Enhanced Workloads, Advanced Policies

Recommendation: Use CSW-MCP-SERVER-USERGUIDE for production environments requiring comprehensive CSW management.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Check the CSW API documentation
• Review error messages in the server logs
• Verify network connectivity and credentials