Metadata-Version: 2.4
Name: jira-sync-mcp
Version: 0.1.3
Summary: MCP server for Jira Sync App — exposes Jira issues from a local PostgreSQL mirror via FastAPI
Project-URL: Homepage, https://dev.azure.com/sii-ads-jira/Jira/_git/jira-sync-mcp
Project-URL: Repository, https://dev.azure.com/sii-ads-jira/Jira/_git/jira-sync-mcp
License: MIT
Keywords: ai,claude,fastmcp,jira,mcp
Classifier: Development Status :: 3 - Alpha
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: fastmcp<3.0.0,>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# jira-sync-mcp

MCP server for Jira Sync App — exposes Jira issues from a local PostgreSQL mirror as MCP tools for Claude Code and other MCP clients.

[![PyPI](https://img.shields.io/pypi/v/jira-sync-mcp)](https://pypi.org/project/jira-sync-mcp/)

**Repository:** https://dev.azure.com/sii-ads-jira/Jira/_git/jira-sync-mcp

## Requirements

- A running instance of Jira Sync App (FastAPI backend)
- An API token generated in **Admin → API Tokens**

## Installation and usage

```bash
# Run directly via uvx (no installation needed)
uvx jira-sync-mcp

# Or install globally
pip install jira-sync-mcp
jira-sync-mcp
```

## Configuration in Claude Code

Add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "jira-sync-mcp": {
      "command": "uvx",
      "args": ["jira-sync-mcp"],
      "env": {
        "JIRA_SYNC_URL": "http://your-server:8000",
        "JIRA_SYNC_API_TOKEN": "<token from Admin → API Tokens>"
      }
    }
  }
}
```

Claude Code starts and stops the MCP process automatically — no manual startup required. The only service that must be running is the FastAPI backend.

### Alternative: pip install (restricted environments)

If `uvx` is blocked by a security policy (e.g. Windows Defender Application Control), install the package directly into your Python environment and use `python -m` instead:

```bash
pip install jira-sync-mcp
```

Then in `~/.claude.json`:

```json
{
  "mcpServers": {
    "jira-sync-mcp": {
      "command": "python",
      "args": ["-m", "jira_sync_mcp"],
      "env": {
        "JIRA_SYNC_URL": "http://your-server:8000",
        "JIRA_SYNC_API_TOKEN": "<token from Admin → API Tokens>"
      }
    }
  }
}
```

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `JIRA_SYNC_URL` | `http://localhost:8000` | Jira Sync App backend URL |
| `JIRA_SYNC_API_TOKEN` | *(required)* | API token from Admin → API Tokens |

## Available tools

### `get_issue(issue_id)`

Fetches full data for a single Jira issue from the local database.

**Arguments:**

| Argument | Type | Description |
|---|---|---|
| `issue_id` | `string` | Issue key, e.g. `"PROJ-1234"` or `"TEAM-567"` |

**Returns:** a dict with the following fields:

| Field | Description |
|---|---|
| `id`, `summary`, `description` | Basic issue data |
| `issue_type`, `status`, `priority` | Classification |
| `assignee`, `reporter` | People |
| `labels`, `fix_versions` | Tags and release versions |
| `created_at`, `updated_at` | Dates |
| `sprint`, `epic_link`, `product`, `profile`, `linked_pm_key` | Custom fields |
| `issue_links` | Linked issues (list of `{link_type, direction, related_issue_id}`) |
| `worklogs` | Work log entries (list of `{author, time_spent_seconds, started_at, comment}`) |
| `comments` | Comments (list of `{author, body, created_at, updated_at}`) |
| `changelog` | Change history (list of `{author, created_at, field, from_value, to_value}`) |

---

### `search_issues(...)`

Searches issues with optional filters. Returns a paginated list.

**Arguments:**

| Argument | Type | Default | Description |
|---|---|---|---|
| `project_id` | `string` | — | Project key or comma-separated list, e.g. `"PROJ"` or `"PROJ,TEAM"` |
| `status` | `string` | — | Status or comma-separated list, e.g. `"Open"` or `"Open,In Progress"` |
| `assignee` | `string` | — | Assignee display name or comma-separated list |
| `issue_type` | `string` | — | Issue type, e.g. `"Bug"`, `"Story"`, `"Task"` |
| `priority` | `string` | — | Priority, e.g. `"High"`, `"Critical"` |
| `fix_version` | `string` | — | Release version in format `YYYY_Rnn`, e.g. `"2025_R01"` |
| `sprint` | `string` | — | Sprint in format `YYYY_Snn`, e.g. `"2025_S01"` |
| `product` | `string` | — | Product name, e.g. `"product-a"` |
| `profile` | `string` | — | Team profile, e.g. `"team-profile"` |
| `linked_pm_key` | `string` | — | Linked PM project key, e.g. `"PM-1234"` |
| `epic_link` | `string` | — | Epic key, e.g. `"PROJ-100"` |
| `date_from` | `string` | — | Created from date (`YYYY-MM-DD`) |
| `date_to` | `string` | — | Created to date (`YYYY-MM-DD`) |
| `search` | `string` | — | Full-text search across id and summary (case-insensitive) |
| `page` | `int` | `1` | Page number (starting from 1) |
| `page_size` | `int` | `50` | Page size (1–200) |

**Returns:** a dict with:

| Field | Description |
|---|---|
| `items` | List of issues — each with: `id`, `summary`, `issue_type`, `status`, `priority`, `assignee`, `reporter`, `labels`, `created_at`, `updated_at` |
| `total` | Total number of matching issues |
| `page` | Current page |
| `page_size` | Current page size |

---

### `get_projects()`

Returns the list of Jira projects available in the Jira Sync App.

**Returns:** a list of dicts, each with:

| Field | Description |
|---|---|
| `id` | Project key, e.g. `"PROJ"` |
| `name` | Full project name |
| `is_active` | Whether the project is actively synced |
| `last_synced_at` | Timestamp of the last successful sync |

---

### `get_sync_status()`

Returns the history of the last 20 Jira synchronisations.

**Returns:** a list of dicts, each with:

| Field | Description |
|---|---|
| `id` | Sync run ID |
| `project_id` | Project key |
| `status` | `success`, `error`, or `running` |
| `sync_type` | `full`, `incremental`, or `missing` |
| `issues_synced` | Number of issues processed |
| `started_at` | Sync start timestamp |
| `finished_at` | Sync end timestamp |
| `error_message` | Error details (only present when `status` is `error`) |
