Prompts System - skindyk/testrail-mcp-server GitHub Wiki

The TestRail MCP Server features a powerful two-tier prompts system that combines built-in default prompts with user-created custom prompts for maximum flexibility.

Overview

The prompts system allows you to:

  • Use pre-built default prompts for common tasks
  • Create custom prompts tailored to your specific workflows
  • Override default prompts with your own versions
  • Share useful prompts with your team

⚠️ Client Compatibility Note: MCP prompts are a newer feature and not all MCP clients support them yet. If your client doesn't support prompts, you can still use the prompt templates as regular conversation starters by copying the generated content manually.

Using Prompts

Simply type / and you will see all the MCP prompts available.

For example VS Code GitHub Copilot:

Select any prompt and hit enter

Prompt content will be populated

System Architecture

Two-Tier Structure

  1. Default Prompts - Built into the server, maintained by developers
  2. User Prompts - Created by users, stored in user-prompts/ directory
testrail-mcp-server/
├── src/prompts/           # Default prompts (built-in)
└── user-prompts/          # User-created prompts
    ├── test-case-review.json
    ├── sprint-test-summary.json
    └── your-custom-prompt.json

Default Prompts

Available Default Prompts

testrail-welcome

  • Description: Quick start guide for using the MCP server
  • Arguments: None
  • Use Case: Perfect for first-time users to understand available tools

User-Created Prompts

User prompts are stored as JSON files in the user-prompts/ directory and are automatically loaded when the server starts.

Included Examples

test-case-review

  • Description: Comprehensive test case quality review
  • Arguments: project_name (required), focus_area (optional)
  • Use Case: Analyze test case quality, identify gaps, suggest improvements

sprint-test-summary

  • Description: Sprint/milestone test execution summary
  • Arguments: project_name (required), milestone_name (required)
  • Use Case: Generate comprehensive test execution reports for sprints

test-plan-analysis

  • Description: Test plan effectiveness analysis
  • Arguments: project_name (required), plan_name (optional), time_period (optional)
  • Use Case: Optimize test plan structure and execution efficiency

Creating User Prompts

There are two ways to create custom user prompts:

Method 1: Interactive Script (Recommended)

Use the built-in interactive prompt creator:

npm run create-prompt

This will guide you through:

  1. Prompt Name - Kebab-case identifier (e.g., my-analysis)
  2. Description - Brief explanation of what the prompt does
  3. Arguments - Define required/optional parameters
  4. Template - Multi-line template with variable substitution

Example Session:

🚀 TestRail MCP Server - Custom Prompt Creator

📛 Prompt name: bug-analysis
📄 Description: Analyze failed tests to identify bug patterns
📝 Define prompt arguments (press Enter with empty name to finish):
  Argument name: project_name
  Argument description: The TestRail project to analyze
  Is this argument required? (y/N): y
  ✅ Added argument: project_name
  
  Argument name: (Enter to finish)

📝 Template (multi-line, end with a line containing only "END"):
# Bug Pattern Analysis for {{project_name}}

Analyze failed test results in project '{{project_name}}' to identify common bug patterns.

## Steps:
1. Use get_projects to find project ID
2. Use get_runs to get recent test runs
3. Use get_results_for_run to analyze failures
4. Identify patterns and root causes

END

✅ Successfully created prompt: user-prompts/bug-analysis.json

Method 2: Manual JSON Creation

Create a .json file directly in the user-prompts/ directory:

{
  "name": "bug-analysis",
  "description": "Analyze failed tests to identify bug patterns",
  "arguments": [
    {
      "name": "project_name",
      "description": "The TestRail project to analyze",
      "required": true
    },
    {
      "name": "time_period",
      "description": "Analysis time period (e.g., 'last 7 days')",
      "required": false
    }
  ],
  "template": "# Bug Pattern Analysis for {{project_name}}\n\nAnalyze failed test results in project '{{project_name}}'.\nTime period: {{time_period}} (if not specified, analyze recent failures)\n\n## Analysis Steps:\n1. Find project ID for '{{project_name}}'\n2. Get recent test runs and results\n3. Identify failure patterns\n4. Provide actionable insights"
}

Template System

Variable Substitution

Use {{variable_name}} syntax to insert argument values:

{
  "template": "Analyze project {{project_name}} focusing on {{focus_area}}"
}

Handling Optional Parameters

For optional parameters, structure templates to handle empty values gracefully:

{
  "template": "Project: {{project_name}}\nFocus: {{focus_area}} (if not provided, perform general analysis)"
}

Template Limitations

The template system supports simple variable substitution only:

✅ Supported:

  • {{variable_name}} - Simple variable replacement

❌ Not Supported:

  • {{#if variable}}...{{/if}} - Conditionals
  • {{#each items}}...{{/each}} - Loops
  • Complex logic or expressions

Prompt Loading

  • Server Startup: Both default and user prompts are loaded automatically
  • Conflict Resolution: User prompts override default prompts with the same name
  • Error Handling: Invalid prompts are skipped silently
  • Reload: Restart the MCP client to load new user prompts

File Management

Git Integration

The .gitignore is configured to:

  • ✅ Include example prompts (shared with team)
  • ❌ Exclude user customizations (personal prompts)

Directory Structure

user-prompts/
├── test-case-review.json       # Example (tracked)
├── sprint-test-summary.json    # Example (tracked)
├── test-plan-analysis.json     # Example (tracked)
└── my-custom-prompt.json       # User creation (ignored)

Best Practices

Template Design

  • Use clear, structured markdown formatting
  • Include step-by-step instructions
  • Provide expected output format examples
  • Add validation checkpoints for complex workflows

Argument Design

  • Mark arguments as required only when necessary
  • Provide clear descriptions for each argument
  • Use descriptive argument names (kebab-case for prompt names)

Error Handling

  • Include error handling instructions in templates
  • Provide fallback strategies for common issues
  • Add troubleshooting guidance

Documentation

  • Write clear, concise descriptions
  • Test prompts with various argument combinations
  • Include usage examples in templates

Troubleshooting

Common Issues

  1. Prompt not loading

    • Check JSON syntax with a validator
    • Ensure file is in user-prompts/ directory
    • Restart the MCP client after adding new prompts

  2. Template variables not replaced

    • Verify variable names match argument names exactly
    • Use {{variable_name}} syntax (double curly braces)
    • Check for typos in variable names

  3. Name conflicts

    • User prompts override default prompts with the same name
    • Check server logs for conflict information

Validation

Before using a new prompt:

  • ✅ JSON syntax is valid
  • ✅ Variable names match between arguments and template
  • ✅ Required arguments are clearly marked
  • ✅ Template provides clear instructions

Advanced Usage

Prompt Libraries

Consider organizing prompts by category:

  • Analysis: bug-analysis.json, coverage-analysis.json
  • Reporting: sprint-summary.json, milestone-report.json
  • Maintenance: cleanup-review.json, duplicate-finder.json

The prompts system provides a powerful way to customize and extend the TestRail MCP Server for your specific needs while maintaining simplicity and reliability.