Content
# UpGuard CyberRisk MCP Server
A Model Context Protocol (MCP) server for integrating with UpGuard's CyberRisk API. This server provides comprehensive security risk assessment and management capabilities through a standardized interface.
## Features
- **67 API Tools** across 13 categories for comprehensive security management
- **25 Comprehensive Prompts** including 8 advanced workflow prompts for complex operations
- **Real-time Risk Assessment** with vendor monitoring and breach detection
- **Automated Documentation Generation** with multiple output formats
- **Interactive API Explorer** with Swagger UI and Redoc interfaces
- **Comprehensive Schema Validation** with 22 Zod schema definitions
- **CI/CD Integration** with automated documentation deployment
## Enhanced Prompts (New in v1.4.0)
The server now includes **25 comprehensive prompts** (8 enhanced + 17 existing) that provide guided workflows for complex security operations:
### 🔴 **Risk Management Prompts**
- `upguard_comprehensive_risk_assessment` - Complete risk assessment workflows
- `upguard_risk_trend_analysis` - Multi-period risk trend analysis
- `upguard_account_risk_dashboard`: Create a risk dashboard for your account.
- `upguard_risk_trend_analysis_original`: Analyze risk trends over a given period.
- `upguard_risk_severity_analysis`: Analyze risks by severity.
- `upguard_critical_risk_prioritization`: Prioritize critical risks.
- `upguard_risk_type_analysis`: Analyze risks by type.
- `upguard_monthly_risk_report`: Generate a monthly risk report.
- `upguard_risk_mitigation_planning`: Create a risk mitigation plan.
- `upguard_executive_risk_summary`: Create an executive-level risk summary.
### 📊 **Compliance & Reporting**
- `upguard_compliance_reporting_suite` - Automated compliance report generation
### 🌐 **Asset Management**
- `upguard_domain_lifecycle_management` - Complete domain lifecycle workflows
- `upguard_bulk_asset_management` - Large-scale asset management operations
- `upguard_network_security_assessment` - Comprehensive network security analysis
- `upguard_check_domain_risks`: Check the risks for a specific domain.
- `upguard_review_typosquatting_for_domain`: Review typosquatting information for a domain.
- `upguard_manage_bulk_hostnames_simple`: A simple workflow to add and remove hostnames in bulk.
### 🪝 **Operations & Monitoring**
- `upguard_setup_comprehensive_alerting` - Complete alerting infrastructure setup
- `upguard_security_dashboard_setup` - Role-based security dashboard configuration
### 🏢 **Vendor & Organization Prompts**
- `upguard_get_my_organization_risks`: Get a list of all risks for your organization.
- `upguard_monitor_new_vendor`: Start monitoring a new vendor.
- `upguard_assess_vendor_risks`: Perform a risk assessment for a specific vendor.
- `upguard_get_my_organization_details`: Retrieve your organization's details.
- `upguard_list_vendors_with_critical_risks`: List all vendors with critical risks.
- `upguard_full_vendor_risk_profile`: Get a full risk profile for a vendor.
- `upguard_monitor_new_vendor_and_send_questionnaire`: Monitor a new vendor and send them a questionnaire.
### 🚨 **Breach & Report Prompts**
- `upguard_investigate_breaches`: Investigate breaches for a specific domain.
- `upguard_generate_report`: Generate a report.
- `upguard_investigate_identity_breach_for_domain`: Investigate identity breaches for a domain.
- `upguard_generate_vendor_report_and_track`: Generate a vendor report and track its status.
**Benefits:**
- **Step-by-step guidance** for complex security workflows
- **Multi-tool orchestration** combining multiple API endpoints
- **Role-based workflows** for different stakeholders (CISO, analysts, compliance)
- **Best practices integration** with built-in security recommendations
📖 **See [ENHANCED_PROMPTS.md](./ENHANCED_PROMPTS.md) for detailed documentation and examples.**
## Quick Start
### Prerequisites
- Node.js 18+
- npm or yarn
- UpGuard CyberRisk API credentials
### Installation
```bash
git clone https://github.com/leroylim/upguard-cyberrisk-mcp-server-nodejs.git
cd upguard-cyberrisk-mcp-server-nodejs
npm install
```
### Configuration
Create a `.env` file with your UpGuard credentials:
```env
UPGUARD_API_KEY=your_api_key_here
```
### Running the Server
```bash
npm start
```
## MCP Configuration
To use this server with Claude Desktop or other MCP-compatible clients, you need to add it to your MCP configuration file.
### For Claude Desktop (Windows/Mac/Linux)
Add the following configuration to your `claude_desktop_config.json` file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"upguard-mcp": {
"command": "node",
"args": [
"/path/to/your/upguard-cyberrisk-mcp-server/src/index.js"
],
"env": {
"UPGUARD_API_KEY": "your_upguard_api_key_here"
}
}
}
}
```
### For Cursor IDE
Add the following configuration to your `mcp.json` file in your Cursor settings directory:
**Windows:** `%APPDATA%\Cursor\User\mcp.json`
**Mac:** `~/Library/Application Support/Cursor/User/mcp.json`
**Linux:** `~/.config/Cursor/User/mcp.json`
```json
{
"mcpServers": {
"upguard-mcp": {
"command": "node",
"args": [
"/path/to/your/upguard-cyberrisk-mcp-server/src/index.js"
],
"env": {
"UPGUARD_API_KEY": "your_upguard_api_key_here"
}
}
}
}
```
### Configuration Notes
- **Replace the path**: Update `/path/to/your/upguard-cyberrisk-mcp-server/src/index.js` with the actual path to your installation
- **Replace the API key**: Update `your_upguard_api_key_here` with your actual UpGuard API key
- **Server name**: You can change `upguard-mcp` to any name you prefer
### Getting Your UpGuard API Key
**Prerequisites:**
- An UpGuard account with administrator access (only administrators can access API tokens)
- Access to the UpGuard platform at [cyber-risk.upguard.com](https://cyber-risk.upguard.com)
**Step-by-step instructions:**
1. **Log in to your UpGuard account** at [https://cyber-risk.upguard.com](https://cyber-risk.upguard.com)
2. **Click the Settings icon** in UpGuard's top-right corner
3. **Navigate to the API tab** in the settings menu
4. **Create or manage API keys:**
- Any existing API keys will be listed here
- Click **"Create new API key"** to generate a new key
- You can also delete existing keys from this tab if needed
5. **Copy your API key** - it will be an alphanumeric string
6. **Paste the key** into your MCP configuration file
**Testing your API key (optional):**
You can verify your API key works by testing it with curl:
```bash
curl -H "Authorization: YOUR_API_KEY" "https://cyber-risk.upguard.com/api/public/vendors"
```
**Security Notes:**
- Keep your API key secure and don't share it publicly
- Only administrators can create and manage API keys
- You can create multiple API keys and delete them as needed
- The API base URL is: `https://cyber-risk.upguard.com/api/public`
For more detailed information, see the [official UpGuard API authentication guide](https://help.upguard.com/en/articles/8060003-how-to-authenticate-with-your-upguard-api-key).
### Restart Required
After updating your MCP configuration, restart Claude Desktop or your IDE for the changes to take effect.
## Documentation System
This project features a comprehensive documentation generation system that creates multiple formats from the source code:
### 📚 Available Documentation Formats
- **📊 Interactive Documentation Hub** - Central navigation with statistics
- **🚀 Swagger UI** - Interactive API explorer for testing endpoints
- **📚 Redoc** - Beautiful, professional API documentation
- **📖 Markdown** - Human-readable documentation with examples
- **🔧 OpenAPI Specification** - Machine-readable API spec for tooling
### 🛠️ Documentation Commands
```bash
# Generate complete documentation pipeline
npm run docs:full
# Individual generation steps
npm run docs:extract # Extract tools from source code
npm run docs:generate # Generate OpenAPI and Markdown
npm run docs:html # Generate HTML documentation
npm run docs:test # Validate generated documentation
# Utility commands
npm run docs:clean # Clean generated files
npm run docs:build # Generate with mock fallback
```
### 📊 Documentation Statistics
- **67 API Tools** documented across 13 categories
- **22 Schema Definitions** with Zod validation
- **54 Tools with Schemas** (80% schema coverage)
- **195KB OpenAPI Specification** with comprehensive examples
- **37KB Markdown Documentation** with authentication guides
### 🌐 Viewing Documentation
After running `npm run docs:full`, open any of these files in your browser:
- **Documentation Hub**: `docs/generated/index.html`
- **Swagger UI**: `docs/generated/swagger.html`
- **Redoc**: `docs/generated/redoc.html`
- **Markdown**: `docs/generated/API.md`
- **OpenAPI Spec**: `docs/generated/openapi.json`
## API Categories
### 🛡️ Risk Management (10 tools)
- Get available risks and risk details
- Account and vendor risk monitoring
- Risk filtering and categorization
### 🏢 Vendor Management (16 tools)
- Monitor and manage vendor security
- Vendor risk assessments
- Bulk vendor operations
### 🌐 Domain Management (9 tools)
- Domain monitoring and analysis
- Subdomain discovery
- Domain risk assessment
### 🔍 IP Management (5 tools)
- IP address monitoring
- Network security analysis
- IP risk evaluation
### 📊 Report Generation (7 tools)
- Custom security reports
- Automated report scheduling
- Report data export
### 🚨 Breach Monitoring (2 tools)
- Data breach detection
- Breach impact analysis
### ⚡ Bulk Operations (6 tools)
- Batch processing capabilities
- Mass vendor updates
- Bulk data operations
### 🔗 Webhook Management (5 tools)
- Event notification setup
- Webhook configuration
- Real-time alerts
### 📋 Additional Categories
- **Questionnaire Management** (1 tool)
- **Typosquat Detection** (1 tool)
- **Label Management** (1 tool)
- **Notification Management** (1 tool)
- **General** (3 tools)
## Development
### Project Structure
```
├── src/
│ ├── tools/ # API tool implementations
│ │ ├── schemas/ # Zod schema definitions
│ │ ├── risks.js # Risk management tools
│ │ ├── vendors.js # Vendor management tools
│ │ └── ... # Other tool categories
│ └── utils/
│ ├── doc-generator.js # Documentation generator
│ └── logger.js # Logging utility
├── scripts/
│ ├── extract-tools-direct.js # Tool extraction
│ ├── generate-docs.js # Documentation generation
│ ├── generate-html-docs.js # HTML documentation
│ └── test-docs.js # Documentation testing
├── docs/
│ ├── generated/ # Generated documentation
│ └── extracted-tools.json # Extracted tool data
└── .github/workflows/
└── docs.yml # CI/CD documentation pipeline
```
### Adding New Tools
1. Create tool implementation in appropriate category file
2. Add schema definitions to `src/tools/schemas/index.js`
3. Run `npm run docs:full` to update documentation
4. Test with `npm run docs:test`
### Schema Validation
All tools use Zod schemas for input validation:
```javascript
const { z } = require('zod');
const { vendorHostname, labels } = require('./schemas');
// Tool with schema validation
server.tool('tool_name', 'Description', {
hostname: vendorHostname,
labels: labels.optional()
}, async (args) => {
// Implementation
});
```
## CI/CD Integration
The project includes automated documentation generation via GitHub Actions:
- **Triggers**: Push to main/master, tool file changes, manual dispatch
- **Generates**: All documentation formats automatically
- **Deploys**: GitHub Pages with interactive documentation
- **Artifacts**: Documentation files with 30-day retention
## Testing
```bash
# Run all tests
npm test
# Lint code
npm run lint
npm run lint:fix
# Test documentation
npm run docs:test
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tools with proper schemas
4. Update documentation with `npm run docs:full`
5. Test changes with `npm run docs:test`
6. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- **GitHub Issues**: [Report bugs or request features](https://github.com/leroylim/upguard-cyberrisk-mcp-server-nodejs/issues)
- **Documentation**: Available in multiple formats in `docs/generated/`
- **API Reference**: Interactive Swagger UI and Redoc interfaces
---
**UpGuard CyberRisk MCP Server** v1.4.0 | Licensed under MIT | [View Documentation](docs/generated/index.html)
