@houmak/minerva-mcp-server/README.md

Minerva Model Context Protocol (MCP) Server for Microsoft 365 and Azure integrations

# @houmak/minerva-mcp-server

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

> **Minerva MCP Server** - Enhanced Microsoft 365 automation with intelligent orchestration

A powerful Model Context Protocol (MCP) server that provides seamless integration with Microsoft 365 services, including Microsoft Graph API, Azure Resource Management, SharePoint, and PowerShell/PnP automation.

## 🚀 Features

### Core Capabilities
- **Microsoft Graph API Integration** - Full access to Microsoft 365 services
- **Azure Resource Management** - Manage Azure resources programmatically
- **PowerShell/PnP Integration** - Execute PowerShell scripts and PnP commands
- **Circuit Breaker Pattern** - Resilient error handling and recovery
- **Advanced Monitoring** - Comprehensive logging and telemetry
- **CLI M365 Integration** - Microsoft 365 CLI tool integration

### Sprint 4 Features
- **Azure DevOps MCP** - Automate DevOps pipelines and repository operations
- **Azure Bicep MCP** - Infrastructure as Code management and deployment
- **PnP Core SDK** - Advanced SharePoint operations
- **Custom Connectors** - Extensible framework for third-party integrations

## 📦 Installation

### Global Installation
```bash
npm install -g @houmak/minerva-mcp-server
```

### Using npx (Recommended)
```bash
npx @houmak/minerva-mcp-server
```

## 🔧 Configuration

### Claude Desktop Configuration

1. Open Claude Desktop
2. Go to Settings → MCP Servers
3. Add the following configuration:

```json
{
  "mcpServers": {
    "minerva": {
      "command": "npx",
      "args": ["@houmak/minerva-mcp-server"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `NODE_ENV` | Environment mode | `production` |
| `USE_GRAPH_BETA` | Use Graph API beta version | `true` |
| `MINERVA_CONFIG_PATH` | Path to configuration file | `./config.json` |

## 🛠️ Usage

### Basic Usage
```bash
# Start the MCP server
npx @houmak/minerva-mcp-server

# Check version
npx @houmak/minerva-mcp-server --version

# Get help
npx @houmak/minerva-mcp-server --help
```

### Microsoft Graph API
```javascript
// Example: Get users from Microsoft Graph
{
  "apiType": "graph",
  "path": "/users",
  "method": "get",
  "graphApiVersion": "v1.0",
  "fetchAll": true,
  "consistencyLevel": "eventual"
}
```

### Azure Resource Management
```javascript
// Example: List resource groups
{
  "apiType": "azure",
  "path": "/subscriptions/{subscriptionId}/resourcegroups",
  "method": "get",
  "apiVersion": "2021-04-01",
  "subscriptionId": "your-subscription-id"
}
```

### PowerShell Execution
```javascript
// Example: Execute PowerShell command
{
  "command": "Get-Process",
  "parameters": {
    "Name": "node"
  }
}
```

## 🔌 API Reference

### Microsoft Graph Tool
- **Name**: `Minerva-Microsoft`
- **Description**: Interact with Microsoft APIs including Graph and Azure Resource Management

#### Parameters
- `apiType` (string): `"graph"` or `"azure"`
- `path` (string): API endpoint path
- `method` (string): HTTP method (`get`, `post`, `put`, `patch`, `delete`)
- `apiVersion` (string, optional): Azure API version (required for Azure)
- `subscriptionId` (string, optional): Azure Subscription ID
- `queryParams` (object, optional): Query parameters
- `body` (object, optional): Request body
- `graphApiVersion` (string, optional): Graph API version (`v1.0` or `beta`)
- `fetchAll` (boolean, optional): Fetch all pages for list results
- `consistencyLevel` (string, optional): Graph API consistency level

### PowerShell Tool
- **Name**: `Minerva-PowerShell`
- **Description**: Execute PowerShell commands and scripts

#### Parameters
- `command` (string): PowerShell command to execute
- `parameters` (object, optional): Command parameters
- `script` (string, optional): PowerShell script content
- `timeout` (number, optional): Execution timeout in milliseconds

## 🏗️ Architecture

```
Minerva MCP Server
├── Core Services
│   ├── AuthManager (Multi-mode authentication)
│   ├── IntelligentRouter (Dynamic provider selection)
│   ├── CircuitBreaker (Resilience pattern)
│   └── AdvancedMonitoring (Telemetry & logging)
├── Microsoft 365 Integration
│   ├── Microsoft Graph API
│   ├── Azure Resource Management
│   ├── SharePoint/PnP
│   └── CLI M365
├── Sprint 4 Features
│   ├── Azure DevOps MCP
│   ├── Azure Bicep MCP
│   ├── PnP Core SDK
│   └── Custom Connectors
└── Utilities
    ├── Dry-Run Mode
    ├── Caching (Redis)
    └── Migration Tools
```

## 🔒 Security

- **Multi-mode Authentication**: Client Credentials, Managed Identity, Interactive Browser, Certificate-based
- **Secure Token Management**: Automatic token refresh and secure storage
- **Error Handling**: Comprehensive error handling with sensitive data protection
- **Environment Isolation**: Production-ready environment configuration

## 📊 Monitoring

- **OpenTelemetry Integration**: Standardized telemetry collection
- **Application Insights**: Azure monitoring and alerting
- **Structured Logging**: Winston-based logging with multiple transports
- **Performance Metrics**: Response time and throughput monitoring

## 🧪 Testing

```bash
# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run E2E tests
npm run test:e2e

# Run tests in watch mode
npm run test:watch
```

## 🚀 Development

### Prerequisites
- Node.js >= 18.0.0
- npm >= 8.0.0
- TypeScript >= 5.2.2

### Setup
```bash
# Clone the repository
git clone https://github.com/HoussemMak/minerva.git
cd minerva/src/mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Scripts
- `npm run build` - Compile TypeScript to JavaScript
- `npm run start` - Start the production server
- `npm run dev` - Start in development mode with hot reload
- `npm test` - Run unit tests
- `npm run lint` - Run ESLint
- `npm run clean` - Clean build artifacts

## 📈 Performance

- **Response Time**: < 100ms for most operations
- **Throughput**: 1000+ requests per minute
- **Memory Usage**: < 100MB typical usage
- **CPU Overhead**: < 5% for normal operations

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [GitHub Wiki](https://github.com/HoussemMak/minerva/wiki)
- **Issues**: [GitHub Issues](https://github.com/HoussemMak/minerva/issues)
- **Discussions**: [GitHub Discussions](https://github.com/HoussemMak/minerva/discussions)

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) - For the MCP specification
- [Microsoft Graph API](https://docs.microsoft.com/en-us/graph/) - For Microsoft 365 integration
- [PnP PowerShell](https://pnp.github.io/powershell/) - For SharePoint automation
- [Azure SDK](https://github.com/Azure/azure-sdk-for-js) - For Azure integration

## 📊 Statistics

- **Version**: 1.0.0
- **Downloads**: [npm stats](https://www.npmjs.com/package/@houmak/minerva-mcp-server)
- **Stars**: [GitHub stars](https://github.com/HoussemMak/minerva)
- **Contributors**: [GitHub contributors](https://github.com/HoussemMak/minerva/graphs/contributors)

---

**Made with ❤️ by [Houssem Makhlouf](https://github.com/HoussemMak)**