Customer JIRA Tracker

A comprehensive JIRA ticket tracking system with MCP (Model Context Protocol) integration for Cursor IDE. This system allows you to track customer-specific JIRA tickets with full CRUD operations and seamless integration with Cursor's AI assistant.

🚀 Features

Customer Management: Create and manage customer profiles
Ticket Tracking: Add, remove, and track JIRA tickets per customer
Comment System: Add comments to individual tickets
Export Functionality: Export customer data to Markdown format with JIRA integration
MCP Integration: Direct integration with Cursor IDE via MCP protocol
Dual Deployment: Support for both local development and OpenShift production
Flexible Authentication: API key-based authentication with SSL verification control

🏗️ Architecture

The system consists of three main components:

HTTP API Server (local_http_server.py / OpenShift deployment)

FastAPI-based REST API
Customer and ticket management endpoints
JSON file-based data storage
API key authentication

MCP Server (mcp_server.py)

Bridges Cursor IDE to the HTTP API
Exposes MCP tools for customer and ticket operations
Handles SSL verification for different environments
Supports both local and OpenShift deployments

Cursor Integration (cursor-mcp-config.json)

Configuration for Cursor IDE
Environment-specific settings
SSL verification control

🚀 Quick Start

Prerequisites

Podman (for containerized deployment)
Cursor IDE

1. Clone and Setup

git clone <repository-url>
cd jiraTracker

2. Configure MCP Integration

Option A: Interactive Setup (Recommended)

./setup_mcp.sh

The interactive setup will prompt you for:

JIRA Personal Token
GitHub Personal Access Token
OpenShift API URL
OpenShift API Key
SSL verification settings for both local and OpenShift environments

Option B: Manual Configuration

cp cursor-mcp-config.template.json ~/.cursor/mcp.json
# Edit ~/.cursor/mcp.json with your specific values

3. Start the Services

Containerized Local Development (Recommended)

./run_local.sh

This will:

Build the HTTP API server container
Build the MCP server container
Start the HTTP API server
Configure MCP to use containerized services

4. Restart Cursor IDE

After configuration, restart Cursor to load the MCP servers.

📊 Export Functionality

The Customer JIRA Tracker includes powerful export capabilities to generate Markdown reports of customer ticket data.

Export Features

Markdown Format: Clean, readable Markdown tables
JIRA Integration: Optional JIRA data (Status, Priority, Assignee, Last Updated)
Customer Summary: Total tickets, comments, and last updated information
Comments Section: Detailed ticket comments with timestamps
File Storage: Automatic saving to customer data directory

Export API Endpoint

GET /api/customers/{customer_name}/export

Parameters:

format (default: "markdown") - Export format
include_jira (default: false) - Include JIRA information
save_file (default: true) - Save to file in customer data directory

Example Usage:

# Basic export
curl "http://localhost:8080/api/customers/AA/export"

# Export with JIRA data
curl "http://localhost:8080/api/customers/AA/export?include_jira=true"

# Export without saving to file
curl "http://localhost:8080/api/customers/AA/export?save_file=false"

MCP Tool Usage

In Cursor IDE, use the export_customer_data tool:

{
  "customer_name": "AA",
  "format": "markdown",
  "include_jira": true,
  "save_file": true
}

Export Output Example

# Customer: AA

**Last Updated:** 2025-10-02T11:40:36.101729
**Total Tickets:** 2
**Total Comments:** 1

## Notes
Initial ticket for AA customer

## Tickets

| Ticket Key | Added Date | Comments | Status | Priority | Assignee | Last Updated |
| --- | --- | --- | --- | --- | --- | --- |
| `RFE-1234` | 2025-10-02 | 1 | N/A (MCP Integration Pending) | N/A (MCP Integration Pending) | N/A (MCP Integration Pending) | N/A (MCP Integration Pending) |

## Comments

### RFE-1234
**2025-10-02T11:38:25**

This is a test comment for the export functionality

🔧 Configuration

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | CUSTOMER_JIRA_API_URL | HTTP API server URL | http://localhost:8080 | Yes | | CUSTOMER_JIRA_API_KEY | API authentication key | local-dev-key | Yes | | CUSTOMER_JIRA_SSL_VERIFY | Enable/disable SSL verification | true | No |

MCP Server Configuration

The MCP server supports two deployment modes using containerized services:

Local Development (Containerized)

{
  "customer-jira-tracker-local": {
    "command": "podman",
    "args": [
      "run", "-i", "--name=customer-jira-tracker-client",
      "--network=host",
      "-e", "CUSTOMER_JIRA_API_URL=http://localhost:8080",
      "-e", "CUSTOMER_JIRA_API_KEY=local-dev-key",
      "-e", "CUSTOMER_JIRA_SSL_VERIFY=false",
      "localhost/customer-jira-tracker-client:local"
    ],
    "env": {
      "CUSTOMER_JIRA_API_URL": "http://localhost:8080",
      "CUSTOMER_JIRA_API_KEY": "local-dev-key",
      "CUSTOMER_JIRA_SSL_VERIFY": "false"
    }
  }
}

OpenShift Production (Containerized)

{
  "customer-jira-tracker-openshift": {
    "command": "podman",
    "args": [
      "run", "-i", "--name=customer-jira-tracker-client-openshift",
      "-e", "CUSTOMER_JIRA_API_URL=https://customer-jira-tracker-server.apps.your-domain.com",
      "-e", "CUSTOMER_JIRA_API_KEY=your-production-key",
      "-e", "CUSTOMER_JIRA_SSL_VERIFY=true",
      "quay.io/your-org/customer-jira-tracker-client:latest"
    ],
    "env": {
      "CUSTOMER_JIRA_API_URL": "https://customer-jira-tracker-server.apps.your-domain.com",
      "CUSTOMER_JIRA_API_KEY": "your-production-key",
      "CUSTOMER_JIRA_SSL_VERIFY": "true"
    }
  }
}

🔐 Authentication & Security

Local Development

Default: No authentication required
Optional: Set CUSTOMER_JIRA_API_KEY for API key authentication
SSL: Not required for local development

OpenShift Production

Required: API key authentication via CUSTOMER_JIRA_API_KEY
SSL: HTTPS required, but verification can be disabled for self-signed certificates
Security: Use strong, unique API keys

SSL Verification Control

The CUSTOMER_JIRA_SSL_VERIFY environment variable controls SSL certificate verification:

"true" (default): Verify SSL certificates (recommended for production)
"false": Skip SSL verification (useful for self-signed certificates in development)

📚 Available MCP Tools

Once configured, the following tools are available in Cursor:

Customer Management

list_customers - List all customers with ticket counts
get_customer_tickets - Get all tickets for a specific customer

Ticket Operations

add_customer_tickets - Add tickets to a customer
remove_customer_tickets - Remove tickets from a customer
add_ticket_comment - Add a comment to a specific ticket

Customer Updates

update_customer_notes - Update customer notes

🛠️ Development

Project Structure

jiraTracker/
├── Dockerfile                # Main container image (OpenShift HTTP server)
├── Dockerfile.mcp            # MCP server container image
├── mcp_server.py             # MCP server implementation
├── local_http_server.py      # HTTP API server (for local development)
├── cursor-mcp-config.json    # Cursor MCP configuration
├── cursor-mcp-config.template.json  # Template for manual setup
├── setup_mcp.sh             # Interactive setup script
├── run_local.sh             # Local development runner (containerized)
├── openshift/               # OpenShift deployment files
│   ├── http_server.py       # OpenShift HTTP server
│   ├── deployment.yaml      # Kubernetes deployment
│   └── ...
└── customer_jira_data/      # JSON data storage

Container Images

The project uses two main container images:

HTTP API Server (customer-jira-tracker-server:local)

Based on Dockerfile.server
Runs the HTTP API server
Used for both local development and OpenShift production

MCP Client (customer-jira-tracker-client:local)

Based on Dockerfile.client
Runs the MCP server that bridges to the HTTP API
Used by Cursor IDE for MCP integration

Building Container Images

# Build HTTP API server image
podman build -t customer-jira-tracker-server:local -f Dockerfile.server .

# Build MCP client image
podman build -t customer-jira-tracker-client:local -f Dockerfile.client .

# Build for OpenShift production
podman build -t quay.io/your-org/customer-jira-tracker-server:latest -f Dockerfile.server .

🚀 Deployment

Local Development (Containerized)

Run ./run_local.sh to start HTTP API server container
MCP server runs automatically when Cursor connects
Configure MCP with local settings (done automatically by setup script)
Restart Cursor IDE

OpenShift Production

Deploy using the provided OpenShift manifests
Build and push container images to your registry
Configure MCP with production settings
Set CUSTOMER_JIRA_SSL_VERIFY=false for self-signed certificates (default is true)
Restart Cursor IDE

🔍 Troubleshooting

Common Issues

MCP Tools Not Available

Ensure Cursor is restarted after configuration
Check ~/.cursor/mcp.json syntax
Verify MCP server is running

SSL Certificate Errors

Set CUSTOMER_JIRA_SSL_VERIFY=false for self-signed certificates (default is true)
Ensure HTTPS URL is used for OpenShift

API Connection Errors

Verify CUSTOMER_JIRA_API_URL is correct
Check if HTTP API server is running
Validate API key authentication

Validation Errors

Ensure MCP server returns content directly (not wrapped in CallToolResult)
Check MCP protocol compatibility

Debug Mode

# Check container status
podman ps -a

# View HTTP API server logs
podman logs customer-jira-tracker-local

# Test API connectivity
curl -H "Authorization: Bearer your-api-key" http://localhost:8080/api/customers

# Test MCP server manually
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}' | podman run --rm -i -e CUSTOMER_JIRA_API_URL=http://host.containers.internal:8080 -e CUSTOMER_JIRA_API_KEY=local-dev-key -e CUSTOMER_JIRA_SSL_VERIFY=false localhost/customer-jira-tracker-client:local

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📞 Support

For issues and questions:

Check the troubleshooting section
Review the USAGE_GUIDE.md for detailed instructions
Open an issue in the repository

customer-jira-tracker-mcp