Metadata-Version: 2.4
Name: freshrelease-mcp
Version: 1.7.5
Summary: An MCP server for Freshrelease - enables Cursor AI to interact with Freshrelease projects
Author-email: Kalidass mani <kalidass.mani@freshworks.com>
License-File: LICENSE
Keywords: ai,assistant,cursor,freshrelease,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.3.0
Requires-Dist: pydantic>=2.10.6
Description-Content-Type: text/markdown

# Freshrelease MCP Server

[![PyPI version](https://badge.fury.io/py/freshrelease-mcp.svg)](https://badge.fury.io/py/freshrelease-mcp)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

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.)
- **📋 Advanced Filtering**: Support for both user-friendly labels and technical field names
- **⚡ 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_create_task` | Create new tasks/issues | `title`, `project_identifier`, `issue_type_name`, `user` |  
| `fr_get_task` | Get task by ID/key | `project_identifier`, `key` |
| `fr_get_all_tasks` | List all project tasks | `project_identifier` |
| `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_filter_testcases` | Advanced test filtering | `filter_rules` |
| `fr_add_testcases_to_testrun` | Add tests to run | `test_run_id`, `test_case_keys` |
| `fr_get_testrun_details` | Get test run insights | `test_run_id` |

### **Smart Filtering**  
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `fr_filter_tasks` | Advanced task filtering | `query`, field labels/names |
| `fr_save_filter` | Save reusable filters | `label`, `query_hash` |
| `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
- **📋 Label-Based Filtering**: Use "Owner" instead of "owner_id", "Status" instead of "status_id"  
- **⚡ Performance Optimized**: Multi-level caching, connection pooling, 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**: Comma-separated strings or JSON objects

## 🚀 Quick Start

### 1. Install
```bash
# 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`:

```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

### 🎯 Create & Manage Tasks
**Ask AI to create a bug report:**
> "Create a bug ticket titled 'Fix login issue' in the FS project, assign it to john@example.com, and set the status to In Progress"

The AI will automatically:
- Find your FS project
- Convert "john@example.com" to the correct user ID
- Set the issue type as "Bug"
- Resolve "In Progress" to the proper status ID

**Get project overview:**
> "Show me all tasks in the FS project"

### 📋 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"

**Sprint-based filtering:**
> "Show me all bugs in Sprint 1"

### 🧪 Test Case Management
**Filter test cases naturally:**
> "Find all high and medium severity functional tests in the Authentication section"

**Get test run insights:**
> "How is test run 150183 performing?"

**Response example:**
*"Test run has 8 total tests, all 8 passed successfully. Great job!"*

## 🔧 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:**
```bash
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](../../issues)  
💡 **Have ideas?** [Start a discussion](../../discussions)

