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

1. Clone the repository

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

2. Build the project

   dotnet build --configuration Release

3. 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 [email protected]"

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

🤝 How to Contribute

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

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes and add tests
4. Commit your changes

   git commit -m 'Add amazing feature'

5. Push to your branch

   git push origin feature/amazing-feature

6. 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 [email protected]. 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

• MCP Protocol Documentation
• Cervantes API Documentation
• .NET 9.0 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 LICENSE 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: [email protected]
• 💬 GitHub Issues: Create an issue
• 📖 Documentation: Wiki

---

Made with ❤️ for the cybersecurity community