McpServer by CervantesSec - MCP Server

MCP Server for Cervantes

A Model Context Protocol (MCP) server implementation that provides seamless integration with the Cervantes penetration testing management platform API. This server enables AI assistants like Claude to interact with Cervantes data through standardized MCP tools.

🎯 Purpose

This MCP server acts as a bridge between AI assistants and the Cervantes platform, allowing users to:

Manage penetration testing projects, clients, and tasks through natural language
Query and manipulate vulnerability data
Generate reports and manage documentation
Handle user and role management
Interact with vault and notes systems

🛠 Technologies

.NET 9.0 - Core framework
Model Context Protocol - Communication standard
HTTP Client - REST API integration
Dependency Injection - Service management

✨ Features

📋 Project Management

Create, read, update, and delete projects
Manage project members and permissions
Handle project notes and attachments
Generate executive summaries

🔍 Vulnerability Management

Complete CRUD operations for vulnerabilities
Vulnerability categorization and CWE mapping
Risk assessment and status tracking
Notes, targets, and attachments management
Template system support

👥 Client Management

Client information management
Avatar upload support
Project association

📝 Task Management

Task creation and assignment
Status tracking and updates
Notes and attachments support
Target association

📊 Reporting

Report generation and management
Template system
Component management
Multiple export formats

🔐 Security & Access

User and role management
Vault for secure credential storage
Permission-based access control

📄 Documentation

Document management system
File upload and organization
Version control support

🔧 Runtime Requirements

.NET 9.0 Runtime or later
Cervantes instance (running and accessible)
Network connectivity to Cervantes API endpoints

📦 Installation

From Source

Clone the repository

git clone https://github.com/CervantesSec/McpServer.git
cd mcpserver-cervantes

Build the project
```
dotnet build --configuration Release
```
Run the server
```
dotnet run --project McpServer
```

⚙️ Configuration

appsettings.json

Configure the server by modifying the appsettings.json file:

{
  "Cervantes": {
    "BaseUrl": "https://your-cervantes-instance.com",
    "Username": "your-username",
    "Password": "your-password",
    "AuthMethod": "BasicAuth"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Environment Variables (Alternative)

You can also configure using environment variables:

# Cervantes API Configuration
CERVANTES__BASEURL=https://your-cervantes-instance.com
CERVANTES__USERNAME=your-username
CERVANTES__PASSWORD=your-password
CERVANTES__AUTHMETHOD=BasicAuth

# Logging Configuration
LOGGING__LOGLEVEL__DEFAULT=Information

MCP Integration

Add the server to your MCP client configuration:

{
  "servers": {
    "cervantes": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/McpServer"],
      "env": {
        "CERVANTES_API_BASE_URL": "https://your-cervantes-instance.com"
      }
    }
  }
}

🚀 Usage

Once configured, the MCP server provides the following tool categories:

Available Tools

ClientTool: Manage client information and avatars
ProjectTool: Handle projects, members, notes, and attachments
VulnerabilityTool: Complete vulnerability lifecycle management
TaskTool: Task management with notes, targets, and attachments
ReportTool: Report generation and template management
DocumentTool: Document management and organization
VaultTool: Secure credential and sensitive data storage
NoteTool: General note-taking and organization
UserTool: User and role management
RoleTool: Permission and access control management

Example Usage with Claude

"Can you show me all high-risk vulnerabilities in the current project?"

"Create a new client named 'Acme Corp' with contact email admin@acme.com"

"Generate a penetration testing report for project ID abc-123"

🤝 How to Contribute

We welcome contributions! Here's how you can help:

Fork the repository

Create a feature branch

git checkout -b feature/amazing-feature

Make your changes and add tests
Commit your changes
```
git commit -m 'Add amazing feature'
```

Push to your branch

git push origin feature/amazing-feature

Open a Pull Request

Development Guidelines

Follow C# coding conventions
Add unit tests for new features
Update documentation as needed
Ensure all builds pass
Use meaningful commit messages

🔒 Security

If you discover a security vulnerability, please send an email to ruben.mesquida@owasp.org. All security vulnerabilities will be promptly addressed.

Security Features

Secure API communication
Input validation and sanitization
Error handling without information disclosure
Structured logging for audit trails

🐛 How to Report Bugs

If you find a bug, please create an issue on GitHub with:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Environment details (.NET version, OS, etc.)
Relevant logs or error messages

📚 Documentation

🏗️ Architecture

The server follows a modular architecture:

McpServer/
├── Models/          # Data models and ViewModels
├── Services/        # API client and business logic
├── Tools/           # MCP tool implementations
└── Program.cs       # Application entry point

Key Components

CervantesApiClient: HTTP client for API communication
Tool Classes: Individual MCP tool implementations
Model Classes: Data transfer objects and ViewModels
Dependency Injection: Service registration and lifetime management

🔄 API Coverage

The server provides comprehensive coverage of the Cervantes API:

✅ Client Management
✅ Project Management
✅ Vulnerability Management
✅ Task Management
✅ Report Generation
✅ Document Management
✅ User & Role Management
✅ Vault Management
✅ Notes System

📊 Supported Operations

Resource	Create	Read	Update	Delete	Special Operations
Clients	✅	✅	✅	✅
Projects	✅	✅	✅	✅	Members, notes, attachments
Vulnerabilities	✅	✅	✅	✅	Templates, categories, CWE
Tasks	✅	✅	✅	✅	Notes, targets, attachments
Reports	✅	✅	✅	✅	Templates, components, generation
Documents	✅	✅	✅	✅	Doc management
Vault	✅	✅	✅	✅
Users	✅	✅	✅	✅	Role assignment

📈 Performance

Async/await throughout for optimal performance
Connection pooling for HTTP requests
Structured logging for observability
Graceful error handling and recovery

📝 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the file for details.

AGPL-3.0 License Summary

The AGPL-3.0 license ensures that:

✅ You can use, modify, and distribute this software freely
✅ You must provide source code for any modifications
✅ Network use is considered distribution - if you run this server for others to access, you must provide the source code
✅ Any derivative works must also be licensed under AGPL-3.0
✅ You must include copyright and license notices

This license is specifically chosen to ensure that improvements to this MCP server remain open source, even when deployed as a service.

🙏 Acknowledgments

CervantesSec for the excellent penetration testing platform
Anthropic for the Model Context Protocol specification
The .NET community for excellent tooling and libraries

📞 Support

📧 Email: ruben.mesquida@owasp.org
💬 GitHub Issues: Create an issue
📖 Documentation: Wiki

Made with ❤️ for the cybersecurity community