# SDUI MCP Monti APM Server

A Model Context Protocol (MCP) server that integrates with Monti APM to provide AI assistants with access to your Meteor application's performance monitoring data.

## Overview

This MCP server exposes Monti APM data through the Model Context Protocol, allowing AI assistants like Claude Desktop to:

- Retrieve system metrics (RAM, CPU, network, disk usage)
- Query method execution traces for performance analysis
- Access application errors and exceptions
- Execute custom GraphQL queries against the Monti APM API
- Get application information and configuration

## Features

- **🔐 Secure Authentication**: JWT-based authentication with Monti APM API
- **📊 System Metrics**: Real-time performance monitoring data
- **🔍 Method Tracing**: Detailed execution traces for performance debugging
- **🚨 Error Monitoring**: Application errors and exceptions tracking
- **🛠️ Custom Queries**: Execute custom GraphQL queries against Monti APM
- **📝 Comprehensive Logging**: Structured logging with Winston
- **🔄 Resource Caching**: Efficient data retrieval with smart caching

## Prerequisites

- Node.js 18+ 
- Existing Meteor application with Monti APM monitoring configured
- Monti APM App ID and App Secret credentials

## Installation

### 1. Clone and Install Dependencies

```bash
git clone <repository-url>
cd sdui-mcp-monti-apm
npm install
```

### 2. Environment Configuration

Copy the example environment file and configure your credentials:

```bash
cp .env.example .env
```

Edit `.env` with your Monti APM credentials:

```env
# Monti APM Configuration
MONTI_APP_ID=your_app_id_here
MONTI_APP_SECRET=your_app_secret_here
MONTI_API_URL=https://api.montiapm.com/core
MONTI_AUTH_URL=https://api.montiapm.com/auth

# Server Configuration  
PORT=4002
NODE_ENV=development

# Logging
LOG_LEVEL=info
LOG_FILE=./logs/mcp-monti.log
```

### 3. Build the Project

```bash
npm run build
```

### 4. Test the Server

```bash
npm start
```

## Usage

### With Claude Desktop

Add the server to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "monti-apm": {
      "command": "node",
      "args": ["/path/to/sdui-mcp-monti-apm/dist/index.js"],
      "env": {
        "MONTI_APP_ID": "your_app_id",
        "MONTI_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

### Available Tools

#### 1. Get System Metrics
```
getSystemMetrics(metric: 'RAM_USAGE' | 'CPU_USAGE' | 'NETWORK_IN' | 'NETWORK_OUT' | 'DISK_USAGE')
```
Retrieve system performance metrics with optional filtering by host and time range.

#### 2. Get Method Traces
```
getMethodTraces(options?: { minDuration, maxDuration, host, userId, limit, since, until })
```
Analyze method execution traces to identify performance bottlenecks.

#### 3. Get Application Errors
```
getErrors(options?: { limit, since, until, host, resolved })
```
Retrieve application errors and exceptions for debugging.

#### 4. Run Custom Query
```
runMontiQuery(query: string, variables?: object)
```
Execute custom GraphQL queries against the Monti APM API.

#### 5. Get App Info
```
getAppInfo()
```
Retrieve basic information about your monitored application.

#### 6. Get Available Hosts
```
getAvailableHosts()
```
List all monitored hosts to identify development vs production deployments.

### Host Filtering for Multi-Environment Monitoring

This MCP server supports filtering data by deployment host, perfect for separating development and production monitoring:

```javascript
// List available hosts
getAvailableHosts()
// Returns: Development hosts (e.g., "MBPvonJMichael2.pioneers") and Production hosts

// Development environment monitoring
getSystemMetrics({host: "MBPvonJMichael2.pioneers", metric: "RAM_USAGE"})
getMethodTraces({host: "MBPvonJMichael2.pioneers", limit: 20})
getErrors({host: "MBPvonJMichael2.pioneers", limit: 10})

// Production environment monitoring
getSystemMetrics({host: "plaiground01-plAIground", metric: "RAM_USAGE"})
getMethodTraces({host: "plaiground01-plAIground", limit: 20})
getErrors({host: "plaiground01-plAIground", limit: 10})

// Compare CPU usage across environments
getSystemMetrics({host: "MBPvonJMichael2.pioneers", metric: "CPU_USAGE"})      // Dev
getSystemMetrics({host: "plaiground01-plAIground", metric: "CPU_USAGE"})       // Prod
```

### Available Resources

- `monti://metric/{metric_type}` - Access cached metric data
- `monti://trace/{trace_id}` - Individual method trace details  
- `monti://error/{error_id}` - Specific error details
- `monti://app` - Application information

## Development

### Scripts

```bash
# Development with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Lint code
npm run lint

# Format code
npm run format
```

### Project Structure

```
src/
├── lib/
│   ├── logger.ts          # Winston logging configuration
│   ├── montiAuth.ts       # JWT authentication with Monti APM
│   └── montiClient.ts     # GraphQL client for Monti API
├── mcp/
│   └── schema.ts          # MCP tools and resources definitions
├── server.ts              # Main MCP server implementation
└── index.ts              # Application entry point
```

## Security Considerations

- **Environment Variables**: Never commit `.env` files containing credentials
- **Token Caching**: JWT tokens are cached securely and refreshed automatically  
- **Error Handling**: Sensitive information is not exposed in error messages
- **Logging**: Credentials are never logged in plain text

## Configuration Options

| Variable | Description | Default |
|----------|-------------|---------|
| `MONTI_APP_ID` | Your Monti APM App ID | Required |
| `MONTI_APP_SECRET` | Your Monti APM App Secret | Required |
| `MONTI_API_URL` | Monti APM GraphQL API endpoint | `https://api.montiapm.com/core` |
| `MONTI_AUTH_URL` | Monti APM authentication endpoint | `https://api.montiapm.com/auth` |
| `PORT` | Server port (not used in MCP mode) | `4002` |
| `NODE_ENV` | Environment mode | `development` |
| `LOG_LEVEL` | Logging level | `info` |
| `LOG_FILE` | Log file path | `./logs/mcp-monti.log` |
| `DEV_HOST_PATTERNS` | Development host patterns (comma-separated) | `mbp,macbook,pioneers` |
| `DEFAULT_HOST` | Default host filter for tools | None |
| `DEFAULT_ENV_MODE` | Default environment mode (`dev`, `prod`, `all`) | `all` |

## Troubleshooting

### Authentication Issues

If you're getting authentication errors:

1. Verify your `MONTI_APP_ID` and `MONTI_APP_SECRET` are correct
2. Check that your Meteor app is properly configured with Monti APM
3. Ensure the credentials have appropriate permissions

### Connection Issues

For API connection problems:

1. Check your internet connection and firewall settings
2. Verify the API URLs are accessible
3. Check the server logs for detailed error messages

### MCP Integration Issues

If Claude Desktop isn't recognizing the server:

1. Verify the configuration file syntax is correct
2. Check that the path to the built server is correct
3. Restart Claude Desktop after configuration changes

## Contributing

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

## License

MIT License - see LICENSE file for details.

## Support

For issues specific to this MCP server, please open a GitHub issue.

For Monti APM support, visit [https://docs.montiapm.com](https://docs.montiapm.com).

## Related Projects

- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [Monti APM](https://montiapm.com/) - Application performance monitoring for Meteor
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - TypeScript SDK for MCP