freshrelease_mcp by dasscoax - MCP Server

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"

📊 Tools Overview

Category	Key Features
Core Management	Projects, tasks, users, and issue types
Test Management	Test cases, test runs, and execution tracking
Smart Filtering	Advanced task and test case filtering
Lookup & Utilities	Name-to-ID resolution and cache management

🛠️ Available Tools

Core Management

Tool	Purpose	Key Parameters
`fr_get_project`	Get project details	`project_identifier`
`fr_get_task`	Get task by ID/key	`project_identifier`, `key`
`fr_get_all_tasks`	List all project tasks	`project_identifier`
`fr_get_epic_insights`	Get comprehensive AI insights for epics with detailed task analysis	`epic_key`, `fetch_detailed_tasks`, `max_tasks`
`fr_get_issue_type_by_name`	Resolve issue type names	`issue_type_name`
`get_task_default_and_custom_fields`	Get form fields for issue types	`issue_type_name`
`fr_search_users`	Find users by name/email	`search_text`

Test Management

Tool	Purpose	Key Parameters
`fr_list_testcases`	List all test cases	`project_identifier`
`fr_get_testcase`	Get specific test case	`test_case_key`
`fr_get_testcases_by_section`	Get tests by section	`section_name`
`fr_link_testcase_issues`	Link tests to issues	`testcase_keys`, `issue_keys`
`fr_testcase_filter_summary`	Advanced test filtering with AI insights	`filter_rules`
`fr_add_testcases_to_testrun`	Add tests to run	`test_run_id`, `test_case_keys`
`fr_get_testrun_summary`	Get comprehensive test run summary with AI quality analysis	`test_run_id`

Smart Filtering

Tool	Purpose	Key Parameters
`fr_filter_tasks`	Advanced task filtering with native query_hash	`query_hash`, `filter_id`, `include`, pagination
`fr_get_issue_form_fields`	Get issue form schema	`issue_type_id`
`fr_get_testcase_form_fields`	Get test form schema	-
`fr_get_all_issue_type_form_fields`	Get all form schemas	-

Lookup & Utilities

Tool	Purpose	Key Parameters
`fr_get_sprint_by_name`	Find sprint by name	`sprint_name`
`fr_get_release_by_name`	Find release by name	`release_name`
`fr_get_tag_by_name`	Find tag by name	`tag_name`
`fr_get_current_subproject_sprint`	Get active sub-project sprint	`sub_project_name`
`get_subproject_id_by_name`	Resolve sub-project names	`sub_project_name`
`fr_clear_filter_cache`	Clear filter cache	-
`fr_clear_all_caches`	Clear all caches	-

✨ 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?

Check ~/.cursor/mcp.json is valid JSON
Restart Cursor completely
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?
💡 Have ideas?