jmeter-mcp 1.0.0
MCP server for JMeter performance test log analysis via stdio
License: MIT
Requires Python: >=3.9
Keywords: analysis, cli, jmeter, mcp, model-context-protocol, performance-testing

# jmeter-mcp

**MCP Server for JMeter Performance Test Log Analysis**

A stdio-based Model Context Protocol (MCP) server that enables AI assistants like Claude to analyze JMeter performance test logs and provide actionable insights. Run instantly with `pipx` without installation.

## Features

- 📊 Analyze JMeter logs (JTL format) statelessy
- 🔍 Auto-detect log formats (JMeter, CSV, Apache, distributed traces)
- ⚡ Stateless operation - no local file I/O assumptions
- 🎯 Stdio transport - optimized for LLM integration
- 📦 Zero-install execution via `pipx run`
- 🔧 Extensible tool-based architecture
- 📝 Logs to stderr only - stdout reserved for MCP protocol

## Quick Start

### With pipx (Recommended)

```bash
# Run directly without installation
pipx run jmeter-mcp

# Or in Autogen config (below)
```

### Manual Installation

```bash
pip install jmeter-mcp
jmeter-mcp
```

## Integration with Autogen

Configure your Autogen agent to use this MCP server:

```python
from autogen import UserProxyAgent, AssistantAgent
from autogen.agentchat.contrib.mcp.agent import MCPAgent

# Define the stdio MCP server
mcp_server_config = {
    "type": "stdio",
    "command": "pipx",
    "args": ["run", "jmeter-mcp"],
    "env": {}
}

# Create MCP-enabled assistant
agent = MCPAgent(
    name="jmeter_analyst",
    system_message="You are a performance testing expert. Analyze JMeter logs and provide insights.",
    mcp_server_config=mcp_server_config,
)

# Use as normal
user = UserProxyAgent(name="user")
user.initiate_chat(agent, message="Analyze this JMeter test result...")
```

## Available Tools

### 1. `analyze_jmeter_logs`
Analyzes JMeter performance test logs and calculates key metrics.

**Input:**
- `log_data` (string): JMeter log content in CSV format

**Output:**
```json
{
  "success": true,
  "metrics": {
    "total_requests": 1000,
    "failed_requests": 5,
    "error_rate_percent": 0.5,
    "response_time_avg_ms": 245.3,
    "response_time_min_ms": 50,
    "response_time_max_ms": 1200,
    "samples_analyzed": 1000
  }
}
```

### 2. `detect_log_format`
Identifies the format and structure of log files.

**Input:**
- `log_data` (string): First few lines of log content

**Output:**
```json
{
  "success": true,
  "format": "jmeter_jtl",
  "confidence": 0.95,
  "description": "JMeter JTL format"
}
```

### 3. `get_supported_formats`
Lists all supported log formats.

**Output:**
```json
{
  "success": true,
  "supported_formats": [
    {"format": "jmeter_jtl", "name": "JMeter JTL", "description": "..."},
    {"format": "performance_csv", "name": "Performance CSV", "description": "..."},
    ...
  ]
}
```

## Protocol Details

### Stdio Transport

```bash
# Start server
jmeter-mcp

# MCP client sends JSON-RPC 2.0 requests via stdin
# Server responds via stdout with JSON-RPC 2.0 responses
# Logging only uses stderr
```

### MCP Server Initialization

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "autogen",
      "version": "0.2.0"
    }
  }
}
```

## Architecture

### Stateless Design
- No local filesystem dependencies
- All data passed via JSON parameters
- No temporary files or caching
- Compatible with sandboxed/containerized environments

### Process Lifecycle
1. Client starts: `pipx run jmeter-mcp`
2. Server binds stdin/stdout
3. Server waits for MCP initialize request
4. Client sends tool calls
5. Server processes and responds
6. Client closes stdin → server exits

## Development

### Project Structure
```
jmeter-mcp/
├── jmeter_mcp/
│   ├── __init__.py
│   └── cli.py              # Main entry point
├── pyproject.toml
├── README.md
└── LICENSE
```

### Local Testing
```bash
# Install in editable mode
pip install -e .

# Test the CLI
jmeter-mcp

# Or via pipx
pipx install -e .
pipx run jmeter-mcp
```

### Running Tests
```bash
pip install -e ".[dev]"
pytest tests/
```

## Publishing to PyPI

### Prerequisites
- Python 3.9+
- build package: `pip install build twine`
- PyPI account (free at https://pypi.org)

### Steps

1. **Update version in pyproject.toml**
   ```bash
   vim pyproject.toml  # Change version to X.Y.Z
   ```

2. **Build distribution**
   ```bash
   python -m build
   ```

3. **Upload to PyPI**
   ```bash
   # First time: requires authentication
   python -m twine upload dist/*
   
   # Optionally test on TestPyPI first:
   python -m twine upload --repository testpypi dist/*
   ```

4. **Verify installation**
   ```bash
   pipx run jmeter-mcp
   ```

### Making it Free/Public
- PyPI automatically makes packages public (unless marked private)
- No fee for publishing
- Package is immediately available for `pip install jmeter-mcp`
- Available for `pipx run jmeter-mcp` after ~5 minutes

## Constraints & Limitations

- ✅ **Stdio-only** - No HTTP, sockets, or alternative transports
- ✅ **Stateless** - Each tool call is independent
- ✅ **No file I/O** - All data via JSON parameters
- ✅ **Logs to stderr** - stdout reserved for protocol
- ✅ **No installation required** - Works via `pipx run`
- ✅ **Memory-safe** - Large logs handled as streams
- ✅ **No background processes** - Single synchronous flow

## Troubleshooting

### "Command not found: jmeter-mcp"
```bash
# Ensure pipx is installed
pip install pipx

# Or use full path
~/.local/bin/jmeter-mcp
```

### Server exits immediately
```bash
# Check stderr for errors
jmeter-mcp 2>&1 | head -20

# Ensure MCP client sends initialize before tool calls
```

### Large log analysis is slow
- The server processes logs line-by-line in Python
- For huge files (>100MB), consider preprocessing on client side
- Memory usage is O(1) during streaming

## License

MIT License - See LICENSE file for details

## Support

- Report issues: https://github.com/yourusername/jmeter-mcp/issues
- Discussions: https://github.com/yourusername/jmeter-mcp/discussions

## Acknowledgments

Built with:
- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP](https://github.com/jlowin/fastmcp)