Metadata-Version: 2.4
Name: mcp-server-r4j
Version: 0.1.1
Summary: MCP server for R4J (Requirements for Jira) — manage folders, issues, and tree structure in Jira Data Center
Author: Christian Epple
License-Expression: MIT
Keywords: atlassian,claude,jira,mcp,model-context-protocol,r4j,requirements-for-jira
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx==0.28.1
Requires-Dist: mcp[cli]==1.27.0
Requires-Dist: pydantic==2.13.1
Description-Content-Type: text/markdown

# R4J Data Center MCP Server

MCP server for **R4J (Requirements for Jira) — Data Center / Server only**. Manage the R4J folder tree, add/move/remove issues, and query the hierarchy. Uses the official R4J REST API 1.0.

> **Jira Cloud is not supported.** The R4J Cloud product exposes a different API shape; this server targets Data Center / Server endpoints only.

## Tools

| Tool | Description |
|------|-------------|
| `r4j_healthcheck` | Validate connectivity, auth, license, and (optionally) a project key |
| `r4j_get_tree` | Get tree structure (folders + issues) for a project or folder |
| `r4j_get_folders` | Get all folders for a project |
| `r4j_get_folder_context` | Get folder metadata, child folders, and issues in one call |
| `r4j_create_folder` | Create a folder (at root or under a parent) |
| `r4j_ensure_folder_path` | Resolve or create a folder path (idempotent) |
| `r4j_rename_folder` | Rename a folder |
| `r4j_delete_folder` | Delete a folder (cascades to descendants) |
| `r4j_move_folder` | Move a folder to another folder (**requires R4J 4.2.2+**) |
| `r4j_add_issue` | Add a Jira issue to a folder (idempotent) |
| `r4j_remove_issue` | Remove an issue from the tree (not from Jira) |
| `r4j_move_issue` | Move an issue between folders |

## Compatibility

Verified against:
- Jira Data Center **10.3.13** (Atlassian Jira Project Management Software)
- R4J (easeRequirements Data Center) **5.3.1-10-jira10**

Other Jira DC / Server and R4J versions are likely to work but are not tested. `r4j_move_folder` requires R4J 4.2.2+.

## Installation

### With uvx (recommended)

```bash
uvx mcp-server-r4j
```

### With pip

```bash
pip install mcp-server-r4j
mcp-server-r4j
```

## Configuration

Set these environment variables before starting the server. The server **fails fast** at startup if required vars are missing or malformed.

| Variable | Required | Default | Description |
|---|---|---|---|
| `R4J_JIRA_URL` | yes | — | Base Jira URL, e.g. `https://jira.example.com/jira`. Must start with `http://` or `https://`. |
| `R4J_JIRA_PAT` | yes | — | Jira Personal Access Token (Bearer). |
| `R4J_PROJECT_KEY` | no | — | Default project key (e.g. `PROJ`). Used when a tool call omits `project_key`. |
| `R4J_TIMEOUT_SECONDS` | no | `30` | HTTP timeout for API calls (must be > 0). |
| `R4J_VERIFY_SSL` | no | `true` | Set to `false` to disable TLS verification (lab / self-signed setups only). |
| `R4J_CA_BUNDLE` | no | — | Path to a custom CA bundle. Overrides `R4J_VERIFY_SSL` when set. |
| `R4J_DEBUG` | no | `false` | If `true`, tool errors include full upstream response bodies. Off by default to avoid leaking internal hostnames / HTML error pages to the LLM. |

```bash
export R4J_JIRA_URL="https://jira.example.com/jira"
export R4J_JIRA_PAT="your-personal-access-token"
export R4J_PROJECT_KEY="PROJ"  # optional default
```

After starting the server, call `r4j_healthcheck` first to verify auth, R4J license, and project reachability.

## Claude Desktop Setup

Edit `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/.config/claude/claude_desktop_config.json` (Linux):

```json
{
  "mcpServers": {
    "r4j": {
      "command": "uvx",
      "args": ["mcp-server-r4j"],
      "env": {
        "R4J_JIRA_URL": "https://jira.example.com/jira",
        "R4J_JIRA_PAT": "your-pat-here",
        "R4J_PROJECT_KEY": "PROJ"
      }
    }
  }
}
```

## Claude Code Setup

```bash
claude mcp add r4j -- uvx mcp-server-r4j
```

To pass env vars so they persist in the Claude Code config:

```bash
claude mcp add r4j \
  -e R4J_JIRA_URL=https://jira.example.com/jira \
  -e R4J_JIRA_PAT=your-pat-here \
  -e R4J_PROJECT_KEY=PROJ \
  -- uvx mcp-server-r4j
```

## Example Workflows

**Create a folder and add issues:**
1. `r4j_ensure_folder_path` → path="Sprint 42"
2. `r4j_add_issue` → issue_key="PROJ-123", folder_path="Sprint 42"

**Move an issue between folders:**
- `r4j_move_issue` → issue_key="PROJ-123", from_folder_path="Sprint 42", to_folder_path="Sprint 43"

**Browse folder structure:**
1. `r4j_get_folder_context` → folder_path="Sprint 42" (structured: child folders, issues, counts)
2. `r4j_get_tree` → folder_path="Sprint 42" (raw tree for deeper inspection)
