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_hashformat 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_summarywith concise insights, quality scores, and focused recommendations - ✅ Epic AI Insights: Renamed and enhanced
fr_get_epic_insightswith comprehensive AI analysis including git/PR status, risk assessment, and detailed task analysis - ✅ Test Case AI Summary: Renamed
fr_filter_testcasestofr_testcase_filter_summarywith 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.jsonis 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? Open an issue
💡 Have ideas? Start a discussion
