Commit ec099538 authored by MD. SHAHIDUL ISLAM's avatar MD. SHAHIDUL ISLAM

Add comprehensive installation guide

- Installation methods for different use cases
- Configuration for Claude Desktop and Cursor
- Entry point usage (jira-mcp command and python -m jira_mcp)
- Troubleshooting guide and best practices
parent 5adc0162
# Jira MCP Package Installation & Usage Guide
## Project Conversion Summary
The Jira MCP Server has been successfully converted into an installable Python package! 🎉
### What Changed
**Before:** Users had to manually clone, set up virtual environments, and run `python jira_mcp_server.py`
**Now:** Users can install in one command and run the server immediately
---
## Installation Methods
### ✅ Method 1: Direct from Git (Recommended)
```bash
pip install git+https://repo.dohatec.com.bd/ai-solutions/mcp-server-jira.git
```
This will:
- Install the `jira-mcp` package with all dependencies automatically
- Create a `jira-mcp` command-line entry point
- Enable `python -m jira_mcp` execution
### ✅ Method 2: Editable Installation (Development)
```bash
git clone https://repo.dohatec.com.bd/ai-solutions/mcp-server-jira.git
cd mcp-server-jira
pip install -e .
```
This is useful if you want to contribute to the project.
### ✅ Method 3: Build and Install Locally
```bash
git clone https://repo.dohatec.com.bd/ai-solutions/mcp-server-jira.git
cd mcp-server-jira
python3 -m pip install build
python3 -m build
pip install dist/jira_mcp-1.0.0-py3-none-any.whl
```
---
## Running the Server
After installation, you have **two ways** to run the server:
### Option A: Using the CLI Entry Point
```bash
jira-mcp
```
### Option B: Using Python Module Runner
```bash
python -m jira_mcp
```
Both do exactly the same thing. Choose whichever is more convenient for your setup.
---
## Configuration
### Set Environment Variables
```bash
export JIRA_SERVER="http://103.41.111.60:8085"
export JIRA_USERNAME="shahidul"
export JIRA_PASSWORD="your-api-token"
export JIRA_DEFAULT_PROJECT="PCM" # Optional
export JIRA_QA_TESTER="Samia Islam" # Optional
```
Then start the server:
```bash
jira-mcp
# or
python -m jira_mcp
```
### For Claude Desktop
Edit `~/.config/Claude/claude_desktop_config.json` (Mac):
```json
{
"mcpServers": {
"jira-mcp": {
"command": "jira-mcp",
"env": {
"JIRA_SERVER": "http://103.41.111.60:8085",
"JIRA_USERNAME": "shahidul",
"JIRA_PASSWORD": "your-password",
"JIRA_DEFAULT_PROJECT": "PCM",
"JIRA_QA_TESTER": "Samia Islam"
}
}
}
}
```
### For Cursor
1. Open Cursor Settings → Features → **MCP Servers**
2. Add New MCP Server
3. **Command:** `jira-mcp`
4. Ensure environment variables are set in your shell before launching Cursor
---
## Package Structure
```
jira_mcp/
├── __init__.py # Package metadata & version
├── server.py # Main MCP server code (moved from jira_mcp_server.py)
└── __main__.py # Module entry point for python -m execution
pyproject.toml # Modern Python packaging configuration
MANIFEST.in # Distribution file includes
.gitignore # Updated with build artifacts
README.md # Updated with new install instructions
```
---
## Entry Points
The package defines two entry points in `pyproject.toml`:
1. **CLI Command:** `jira-mcp` → runs `jira_mcp.server:main()`
2. **Module Runner:** `python -m jira_mcp` → runs `jira_mcp.__main__:main()`
Both entry points call the same `main()` function, which starts the MCP server with `mcp.run()`.
---
## Key Changes Made
| File | Change |
|------|--------|
| `jira_mcp/server.py` | Moved from `jira_mcp_server.py` + wrapped `mcp.run()` in `main()` function |
| `jira_mcp/__init__.py` | Created with version `1.0.0` |
| `jira_mcp/__main__.py` | Created to enable `python -m jira_mcp` |
| `pyproject.toml` | Created with modern build system config + entry points |
| `MANIFEST.in` | Created to include README/CHANGELOG in distribution |
| `.gitignore` | Updated to exclude build artifacts |
| `README.md` | Updated with new installation & configuration instructions |
---
## Verification Checklist
✅ Package installs from Git URL with `pip install git+https://...`
✅ CLI entry point `jira-mcp` is created and executable
✅ Module runner `python -m jira_mcp` works
✅ Dependencies (mcp, jira) are auto-installed
✅ Environment variables still work as before
✅ No breaking changes to existing code
✅ Tests remain independent (not included in distribution)
---
## Next Steps (Optional)
### For users:
```bash
# Simple installation
pip install git+https://repo.dohatec.com.bd/ai-solutions/mcp-server-jira.git
# Start the server
jira-mcp
```
### For developers:
1. Clone the repo
2. Run `pip install -e .` for development installation
3. Modify code while changes auto-apply
4. Run tests with `python test_mcp.py`
### Future considerations:
- Optional: Publish to PyPI for `pip install jira-mcp` (no git URL needed)
- Optional: Add setup for automatic MCP server registration in Claude/Cursor
---
## Troubleshooting
### `jira-mcp` command not found after installation
```bash
# Check where it was installed
python3 -m pip show -f jira-mcp | grep bin
# Add that directory to your PATH or use full path
/Library/Frameworks/Python.framework/Versions/3.14/bin/jira-mcp
```
### Module import errors
```bash
# Ensure package is installed
python3 -m pip list | grep jira
# Or reinstall
pip install --force-reinstall -e .
```
### Jira connection failures
```bash
# Check environment variables are set
printenv | grep JIRA_
# Export them if missing
export JIRA_SERVER="http://..."
export JIRA_USERNAME="..."
```
---
## Questions?
Refer to the updated [README.md](../README.md) for detailed usage examples and all available MCP tools.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment