npm package: @m00nsolutions/mcp-server
Description: MCP server for M00n Report - enables AI assistants like Claude and Cursor to query test analytics
Author: M00n Solutions
Latest version: 1.4.4

# @m00nsolutions/mcp-server

MCP (Model Context Protocol) server for M00n Report. Enables AI assistants like **Claude** and **Cursor** to query your test analytics.

## Features

- 📊 **Query test trends** - Pass rates, failing tests, flaky tests over time
- 📈 **Get launch statistics** - Test run summaries with filtering
- 📁 **Manage test cases** - Create, update, delete, and organize test cases
- 🗂️ **Organize with folders** - Full folder/suite hierarchy management
- 📋 **Test collections** - Manage manual test runs and executions
- 🚀 **Release management** - Track releases with linked test runs
- 🔒 **Secure** - Uses your MCP key with your permissions
- 🏢 **Self-hosted ready** - Works with self-hosted M00n Report instances
- 🏷️ **Tool annotations** - MCP 2025 spec compliant with safety hints
- 📖 **Resources** - Read-only data access for summaries and reports
- 🎯 **Prompts** - Guided workflow templates for common tasks (NEW!)

## Quick Start

### 1. Get an MCP Key

1. Log in to M00n Report
2. Go to **Settings → MCP Keys**
3. Create a new MCP key
4. Copy the key (starts with `m00n_mcp_`)

### 2. Configure Cursor

Add to your Cursor MCP configuration (`~/.cursor/mcp.json` or workspace `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://m00nreport.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here"
      }
    }
  }
}
```

### 3. Configure Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://m00nreport.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here"
      }
    }
  }
}
```

## Available Resources (8)

Resources provide **read-only data** that AI clients can access directly without tool calls. They're perfect for summaries, reports, and structured data.

| Resource URI | Name | Format | Description |
|--------------|------|--------|-------------|
| `m00n://projects` | All Projects | JSON | List of all accessible projects with counts |
| `m00n://projects/{projectId}/summary` | Project Health | JSON | Pass rates, flaky count, latest run info |
| `m00n://projects/{projectId}/flaky-tests` | Flaky Tests | Markdown | Flaky tests report with patterns |
| `m00n://projects/{projectId}/failing-tests` | Failing Tests | Markdown | Currently failing tests from latest run |
| `m00n://projects/{projectId}/folder-tree` | Folder Tree | JSON | Hierarchical folder/suite structure |
| `m00n://launches/{launchId}/report` | Launch Report | Markdown | Full test run report with failures |
| `m00n://cases/{caseId}/content` | Test Case | Markdown | Test case with steps and metadata |
| `m00n://releases/{releaseId}/summary` | Release Summary | JSON | Release health with test run stats |

**Example prompts using resources:**
- "Show me the project health summary"
- "What's in the flaky tests report for project X?"
- "Get the full launch report for the latest run"
- "Show me the test case TC-001 content"

---

## Available Prompts (6)

Prompts are **guided workflow templates** that provide context and instructions for common tasks. They help AI assistants perform complex multi-step operations effectively.

| Prompt | Description |
|--------|-------------|
| `analyze_flaky_tests` | Investigate flaky tests, identify patterns, and suggest fixes |
| `debug_test_failure` | Debug a test failure by analyzing errors and history |
| `release_readiness` | Assess if a release is ready to ship |
| `generate_test_cases` | Generate test cases from a feature description |
| `weekly_health_report` | Generate a comprehensive weekly test health report |
| `investigate_regression` | Investigate when and why a test started failing |

### Prompt Arguments

**analyze_flaky_tests**
- `projectId` (required) - Project UUID to analyze
- `days` (optional) - Lookback period in days (default: 14)

**debug_test_failure**
- `launchId` (required) - Launch/run UUID containing the failure
- `testSearch` (optional) - Test name or path to search for

**release_readiness**
- `releaseId` (required) - Release UUID to assess

**generate_test_cases**
- `featureDescription` (required) - Description of the feature to test
- `folderId` (required) - Target folder UUID
- `testType` (optional) - functional, edge-cases, negative, security, performance

**weekly_health_report**
- `projectId` (required) - Project UUID to report on

**investigate_regression**
- `projectId` (required) - Project UUID
- `testTitlePath` (required) - Full or partial test title path

**Example usage:**
- "Use the analyze_flaky_tests prompt for project abc-123"
- "Help me debug the test failures in run xyz-456"
- "Is release v2.1.0 ready to ship?"
- "Generate test cases for the user registration feature"

---

## Available Tools (41)

All tools include **MCP 2025 annotations** to help AI clients understand tool safety characteristics.

### Analytics & AI Tools (Read-Only)
| Tool | Description |
|------|-------------|
| `list_projects` | List all accessible projects |
| `get_launches_trends` | Get pass rate, flaky, failing test trends |
| `get_launches_statistics` | Get test run summaries with filtering |
| `get_launch_tests` | Get all tests from a specific run |
| `get_test_history` | Get execution history for a test |
| `search_tests` | Search tests by title or file path |
| `run_health_check` | 🆕 Get overall project health score (0-100) with recommendations |
| `get_coverage_gaps` | 🆕 Identify test cases without linked autotests |
| `suggest_test_cases` | 🆕 Generate test case suggestions from feature description |
| `export_report` | 🆕 Generate markdown reports (summary, failures, trends, release) |

### Bulk Operations
| Tool | Annotations | Description |
|------|-------------|-------------|
| `bulk_update_cases` | ✏️ update | 🆕 Update multiple test cases at once (status, priority, tags) |

### Test Case Management
| Tool | Annotations | Description |
|------|-------------|-------------|
| `list_test_cases` | 🔒 read-only | List test cases with filtering |
| `get_test_case` | 🔒 read-only | Get full test case details |
| `create_test_case` | ✏️ create | Create a new test case |
| `update_test_case` | ✏️ update | Update an existing test case |
| `delete_test_case` | ⚠️ destructive | Archive a test case |
| `move_test_case` | ✏️ update | Move to different folder |
| `link_autotest_to_case` | 🔗 link | Link automated test to case |

### Folder Management
| Tool | Annotations | Description |
|------|-------------|-------------|
| `list_folders` | 🔒 read-only | List all folders/suites |
| `get_folder` | 🔒 read-only | Get folder details |
| `create_folder` | ✏️ create | Create folder or suite |
| `update_folder` | ✏️ update | Rename or move folder |
| `delete_folder` | ⚠️ destructive | Archive folder and contents |
| `get_folder_statistics` | 🔒 read-only | Get folder statistics |

### Test Collections (Manual Runs)
| Tool | Annotations | Description |
|------|-------------|-------------|
| `list_test_collections` | 🔒 read-only | List manual test runs |
| `get_test_collection` | 🔒 read-only | Get collection with execution status |
| `create_test_collection` | ✏️ create | Create a manual test run |
| `update_test_collection` | ✏️ update | Update collection metadata |
| `add_cases_to_collection` | 🔗 link | Add cases to collection |
| `remove_cases_from_collection` | ⚠️ remove | Remove cases from collection |
| `delete_test_collection` | ⚠️ destructive | Archive collection |

### Release Management
| Tool | Annotations | Description |
|------|-------------|-------------|
| `list_releases` | 🔒 read-only | List releases with stats |
| `get_release` | 🔒 read-only | Get release with test runs |
| `create_release` | ✏️ create | Create a new release |
| `update_release` | ✏️ update | Update release metadata |
| `delete_release` | ⚠️ destructive | Archive release |
| `link_runs_to_release` | 🔗 link | Link manual runs to release |
| `link_launches_to_release` | 🔗 link | Link automated runs to release |
| `unlink_run_from_release` | ⚠️ remove | Remove run from release |
| `unlink_launch_from_release` | ⚠️ remove | Remove launch from release |

## Tool Annotations

All tools include MCP 2025 spec-compliant annotations that help AI assistants understand tool behavior:

| Annotation | Meaning |
|------------|---------|
| `readOnlyHint: true` | 🔒 Tool only reads data, no side effects |
| `destructiveHint: true` | ⚠️ Tool may delete or archive data |
| `idempotentHint: true` | 🔄 Safe to call repeatedly with same args |
| `openWorldHint: false` | 📦 Tool operates only on known entities |

**Example annotation:**
```json
{
  "name": "delete_test_case",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
```

AI assistants use these hints to:
- Warn users before executing destructive operations
- Batch read-only operations without confirmation
- Safely retry idempotent operations on failure

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `M00N_API_URL` | ✅ | - | M00n Report API URL (e.g., `https://m00nreport.com`) |
| `M00N_API_KEY` | ✅ | - | MCP key from Settings → MCP Keys |
| `M00N_INSECURE_SSL` | | `false` | Skip SSL verification (for self-signed certs) |
| `M00N_DEBUG` | | `false` | Enable verbose logging |
| `M00N_TIMEOUT_MS` | | `30000` | Request timeout in milliseconds |

## Self-Hosted Installation

### Standard Installation

Works with any self-hosted M00n Report instance:

```json
{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://your-m00n-instance.company.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here"
      }
    }
  }
}
```

### Self-Signed Certificates

For self-hosted instances with self-signed SSL certificates:

```json
{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://your-m00n-instance.company.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here",
        "M00N_INSECURE_SSL": "true"
      }
    }
  }
}
```

⚠️ **Security Note:** Only use `M00N_INSECURE_SSL=true` for trusted internal servers with self-signed certificates.

### Offline/Air-Gapped Installation

For environments without internet access:

1. On a machine with internet, create a tarball:
   ```bash
   npm pack @m00nsolutions/mcp-server
   ```

2. Transfer `m00nsolutions-mcp-server-1.0.0.tgz` to the air-gapped machine

3. Install from tarball:
   ```bash
   npm install -g ./m00nsolutions-mcp-server-1.0.0.tgz
   ```

4. Configure to use the global installation:
   ```json
   {
     "mcpServers": {
       "m00n": {
         "command": "m00n-mcp",
         "env": {
           "M00N_API_URL": "https://your-m00n-instance.company.com",
           "M00N_API_KEY": "m00n_mcp_your_key_here"
         }
       }
     }
   }
   ```

## Troubleshooting

### "Cannot connect to M00n Report API"

- Verify `M00N_API_URL` is correct and accessible
- Check network connectivity to the M00n Report server
- For self-hosted: ensure the API port (default 4000) is accessible

### "Authentication failed: Invalid or expired MCP key"

- Verify `M00N_API_KEY` starts with `m00n_mcp_`
- Check the key hasn't been revoked in Settings → MCP Keys
- Ensure you're using an MCP key, not a project API key

### "SSL certificate error"

- For self-signed certificates, set `M00N_INSECURE_SSL=true`
- Verify the certificate chain if using a private CA

### "No tools available"

- Check your MCP key has appropriate permissions
- Verify your user account has access to at least one project

### Enable Debug Logging

Set `M00N_DEBUG=true` to see detailed logs:

```json
{
  "env": {
    "M00N_API_URL": "...",
    "M00N_API_KEY": "...",
    "M00N_DEBUG": "true"
  }
}
```

## Example Prompts

Once configured, try these prompts in Claude or Cursor:

### Analytics & Health
- "List my M00n Report projects"
- "Show me the test pass rate trends for the last 30 days"
- "What are the top 10 flaky tests in project X?"
- "Get me the failed test runs from this week"
- "Which tests are taking the longest to run?"
- "Run a health check on my project"
- "What's the overall health score for project X?"

### Coverage Analysis (NEW!)
- "Show me the test coverage gaps in my project"
- "Which test cases don't have automated tests?"
- "Which folders have low automation coverage?"

### AI-Assisted (NEW!)
- "Suggest test cases for the user login feature"
- "Generate test case ideas for: users can upload profile pictures up to 5MB"
- "Create edge case tests for the payment checkout flow"

### Bulk Operations (NEW!)
- "Update all test cases TC-001, TC-002, TC-003 to status Approved"
- "Add the 'regression' tag to all selected test cases"
- "Set priority to High for these 5 test cases"

### Reporting (NEW!)
- "Generate a summary report for my project"
- "Export a failures report for the last 7 days"
- "Show me the trends report in markdown format"
- "Generate a release status report for release v2.1.0"

## Support

- **Documentation:** https://m00nreport.com/documentation/getting-started
- **Issues:** https://github.com/m00nsolutions/m00nreport/issues
- **Email:** support@m00nreport.com

## License

MIT