Freshrelease MCP Server

An MCP server that enables AI models to interact with Freshrelease through powerful tools for complete project and test management.

🚀 Key Features

• 🤖 AI-Native: Built specifically for AI model integration via MCP protocol

• 🔧 Complete Management: Projects, tasks, test cases, test runs, and user management

• 🧠 Smart Resolution: Automatically converts names to IDs (users, sprints, projects, etc.)

• 📋 Native Filtering: Full support for Freshrelease's native query_hash format

• 🌲 Hierarchical Navigation: Navigate through 7-level deep section hierarchies

• ⚡ Performance Optimized: Built-in caching, connection pooling, and batch processing

• 🎯 Label-Based Filtering: Use intuitive field names like "Owner" instead of "owner_id"

Related MCP server: Freshservice MCP Server

📊 Tools Overview

🛠️ Available Tools

Core Management

Test Management

Smart Filtering

Lookup & Utilities

✨ Smart Features

• 🧠 Name-to-ID Resolution: Converts user names, sprint names, issue types, etc. to IDs automatically

• 📋 Native Query Format: Full support for Freshrelease's query_hash format with all operators

• 🌲 Hierarchical Sections: Navigate up to 7 levels deep section hierarchies (e.g., "Level1 > Level2 > Level3")

• 🔄 API Compatibility: Handles both nested {"users": [...]} and direct array response formats

• ⚡ Performance Optimized: Multi-level caching, connection pooling, optimized batch processing

• 🔗 Flexible Project IDs: Accept both project keys ("FS") and numeric IDs (123)

• 🎯 Custom Field Support: Auto-detects and handles custom fields with "cf_" prefixing

• 📊 Multiple Query Formats: Native query_hash, comma-separated strings, or JSON objects

🚀 Quick Start

1. Install

# Easy install (no Python needed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or with Python: uv tool install freshrelease-mcp

2. Get Credentials

• API Key: Freshrelease → Profile → API Key

• Domain: company.freshrelease.com (your domain)

• Project Key: e.g., "FS", "PROJ" (optional)

3. Configure Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "freshrelease-mcp": {
      "command": "uvx",
      "args": ["freshrelease-mcp"],
      "env": {
        "FRESHRELEASE_API_KEY": "your_api_key",
        "FRESHRELEASE_DOMAIN": "company.freshrelease.com",
        "FRESHRELEASE_PROJECT_KEY": "FS"
      }
    }
  }
}

4. Restart Cursor

✅ You'll see Freshrelease tools available!

💡 Usage Examples

🎯 Task Management

Get project overview:

"Show me all tasks in the FS project"

Get specific task details:

"Get details for task FS-123"

Get comprehensive epic insights with AI analysis:

"Show me detailed insights for epic FS-223786 including git status and risk assessment"

The AI will automatically:

• Fetch the epic details and all child tasks with full information

• Analyze git/PR development status from task descriptions

• Provide AI-powered insights on completion rates, team distribution, and timeline risks

• Provide status breakdown and progress summary

• Show assignee distribution and priority breakdown

📋 Advanced Task Filtering

Use natural language filtering:

"Find all high priority tasks owned by John Doe that are currently in progress"

The AI understands both:

• Friendly labels: "Owner", "Status", "Priority"

• Technical names: "owner_id", "status_id", "priority_id"

Native Freshrelease filtering with existing filters:

"Filter tasks using saved filter ID 102776 with custom fields and date ranges"

Sprint and date-based filtering:

"Show me all bugs in Sprint 1 created between Dec 2024 and Aug 2025"

🧪 Test Case Management

Filter test cases naturally:

"Find all high and medium severity functional tests in the Authentication section"

Navigate hierarchical sections:

"Get all test cases from Authentication > Login Tests > Positive Cases section"

The AI can navigate up to 7 levels deep in section hierarchies automatically.

Get concise test run summary with AI insights:

"How is test run 150183 performing?"

Response example: "23/25 tests executed (92% complete). 21 passed, 2 failed. Quality score: Good. Fix 2 failing test cases."

🛠️ Development Tools

Code Quality Assurance

This project includes comprehensive tools to maintain code quality and prevent common issues:

📋 Code Quality Guide (CODE_QUALITY_GUIDE.md)

• Complete indentation standards and best practices

• Project-specific code patterns and templates

• Common mistakes to avoid with examples

• Performance optimization guidelines

• Pre-commit checklist for developers

🔍 Automated Quality Checker (quality_check.py)

Run quality checks on any Python file:

python3 quality_check.py src/freshrelease_mcp/server.py

Features:

• ✅ Indentation validation (4-space standard)

• ✅ MCP tool structure verification

• ✅ Function docstring checks

• ✅ Async/await pattern validation

• ✅ Error handling analysis

Example output:

✅ No issues found in src/freshrelease_mcp/server.py

🆕 Latest Updates

v1.9.7 - Optimized AI Insights & Code Quality

• ✅ Optimized Test Run AI: Simplified fr_get_testrun_summary with concise insights, quality scores, and focused recommendations

• ✅ Epic AI Insights: Renamed and enhanced fr_get_epic_insights with comprehensive AI analysis including git/PR status, risk assessment, and detailed task analysis

• ✅ Test Case AI Summary: Renamed fr_filter_testcases to fr_testcase_filter_summary with intelligent insights and automation analysis

• ✅ Code Quality Tools: Added comprehensive code quality guide (CODE_QUALITY_GUIDE.md) and automated quality checker (quality_check.py)

• ✅ Enhanced Field Mapping: Fixed filtering issues with improved field label resolution

• ✅ Better Error Handling: Comprehensive logging and error messages for debugging

• ✅ Issue Key Resolution: Support for parent_id and epic_id filtering using issue keys

v1.8.4 - Filter Bug Fixes

• ✅ Fixed Fields Mapping Error: Resolved "Failed to get project fields mapping: 0" error

• ✅ API Response Handling: Better handling of nested vs. direct array responses

• ✅ Common Field Mappings: Added support for "Parent", "Epic", "Owner" field labels

🔧 Troubleshooting

Not seeing tools in Cursor?

1. Check ~/.cursor/mcp.json is valid JSON

2. Restart Cursor completely

3. Verify credentials: uvx freshrelease-mcp --help

Environment Variables:

FRESHRELEASE_API_KEY="your_api_key"      # Required
FRESHRELEASE_DOMAIN="company.freshrelease.com"  # Required  
FRESHRELEASE_PROJECT_KEY="FS"            # Optional default project

📄 License

MIT License - see LICENSE file for details.

⭐ Like this project? Give it a star on GitHub!
🐛 Found a bug? Open an issue
💡 Have ideas? Start a discussion