@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):

{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://app.m00n.report",
        "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):

{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://app.m00n.report",
        "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:

{
  "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://app.m00n.report) | | 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:

{
  "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:

{
  "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:

   npm pack @m00nsolutions/mcp-server

2. Transfer m00nsolutions-mcp-server-1.0.0.tgz to the air-gapped machine

3. Install from tarball:

   npm install -g ./m00nsolutions-mcp-server-1.0.0.tgz

4. Configure to use the global installation:

   {
     "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:

{
  "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://m00n.report/docs
• Issues: https://github.com/m00nsolutions/m00nreport/issues
• Email: [email protected]

License

MIT