jira2mcp 0.1.0__tar.gz

jira2mcp-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.3
+Name: jira2mcp
+Version: 0.1.0
+Summary: MCP server exposing Jira Cloud tools via FastMCP
+Author: en-ver
+Requires-Dist: fastmcp>=3.1.0
+Requires-Dist: jira2py==0.4.0
+Requires-Dist: marklassian>=0.1.0
+Requires-Dist: pathvalidate>=3.3.1
+Requires-Dist: pyadf>=0.3.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# jira2mcp
+
+MCP server for Jira Cloud — gives AI assistants like Claude the ability to read, create, edit, search, and comment on Jira issues.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) and [jira2py](https://pypi.org/project/jira2py/).
+
+## Setup
+
+### 1. Get your Jira credentials
+
+You need three values from your Jira Cloud instance:
+
+| Variable | Description |
+|---|---|
+| `JIRA_URL` | Your Jira instance URL (e.g. `https://yourcompany.atlassian.net`) |
+| `JIRA_USER` | Your Jira account email |
+| `JIRA_API_TOKEN` | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |
+
+### 2. Install uv (if not already installed)
+
+`uvx` is part of [uv](https://docs.astral.sh/uv/), a fast Python package manager:
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 3. Add to Claude Code
+
+```bash
+claude mcp add jira -- uvx jira2mcp
+```
+
+### 4. Configure credentials
+
+**Option A: Shell environment variables**
+
+Export them in your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+export JIRA_URL="https://yourcompany.atlassian.net"
+export JIRA_USER="you@company.com"
+export JIRA_API_TOKEN="your-api-token"
+```
+
+The MCP configuration stays minimal:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["jira2mcp"]
+    }
+  }
+}
+```
+
+**Option B: Inline in MCP configuration**
+
+If you prefer not to set global environment variables, provide them directly in the `env` section:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["jira2mcp"],
+      "env": {
+        "JIRA_URL": "https://yourcompany.atlassian.net",
+        "JIRA_USER": "you@company.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `jira_read` | Read a Jira issue by key with full details |
+| `jira_search` | Search issues using JQL |
+| `jira_create` | Create a new issue |
+| `jira_edit` | Update an existing issue |
+| `jira_comment` | Add a comment to an issue |
+| `jira_comments` | List comments with pagination |
+| `jira_fields` | Get field metadata for create/edit screens |
+| `jira_projects` | List accessible projects |
+| `jira_users` | Search users by name or email |
+| `jira_attachment` | Download an attachment |
+| `jira_add_link` | Create a link between two issues |
+| `jira_delete_link` | Delete an issue link |
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `data://jira/link-types` | Available issue link types in your Jira instance |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `jql_syntax` | JQL syntax reference for building search queries |
+
+## Key features
+
+- **Markdown in, Markdown out** — write descriptions and comments in Markdown; they're auto-converted to Atlassian Document Format (ADF). ADF fields from Jira are converted back to Markdown.
+- **Field discovery** — use `jira_fields` to discover required and available fields before creating or editing issues.
+- **User lookup** — use `jira_users` to resolve display names to account IDs for assignment.
+- **Extra fields** — request additional fields on `jira_read` beyond the standard set; rich-text fields are auto-converted.
+- **Link management** — read the `data://jira/link-types` resource to discover available link types, then create or delete links between issues.
+
+## License
+
+MIT

jira2mcp-0.1.0/README.md

@@ -0,0 +1,121 @@
+# jira2mcp
+
+MCP server for Jira Cloud — gives AI assistants like Claude the ability to read, create, edit, search, and comment on Jira issues.
+
+Built with [FastMCP](https://github.com/jlowin/fastmcp) and [jira2py](https://pypi.org/project/jira2py/).
+
+## Setup
+
+### 1. Get your Jira credentials
+
+You need three values from your Jira Cloud instance:
+
+| Variable | Description |
+|---|---|
+| `JIRA_URL` | Your Jira instance URL (e.g. `https://yourcompany.atlassian.net`) |
+| `JIRA_USER` | Your Jira account email |
+| `JIRA_API_TOKEN` | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |
+
+### 2. Install uv (if not already installed)
+
+`uvx` is part of [uv](https://docs.astral.sh/uv/), a fast Python package manager:
+
+```bash
+# macOS / Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+### 3. Add to Claude Code
+
+```bash
+claude mcp add jira -- uvx jira2mcp
+```
+
+### 4. Configure credentials
+
+**Option A: Shell environment variables**
+
+Export them in your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
+
+```bash
+export JIRA_URL="https://yourcompany.atlassian.net"
+export JIRA_USER="you@company.com"
+export JIRA_API_TOKEN="your-api-token"
+```
+
+The MCP configuration stays minimal:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["jira2mcp"]
+    }
+  }
+}
+```
+
+**Option B: Inline in MCP configuration**
+
+If you prefer not to set global environment variables, provide them directly in the `env` section:
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "uvx",
+      "args": ["jira2mcp"],
+      "env": {
+        "JIRA_URL": "https://yourcompany.atlassian.net",
+        "JIRA_USER": "you@company.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `jira_read` | Read a Jira issue by key with full details |
+| `jira_search` | Search issues using JQL |
+| `jira_create` | Create a new issue |
+| `jira_edit` | Update an existing issue |
+| `jira_comment` | Add a comment to an issue |
+| `jira_comments` | List comments with pagination |
+| `jira_fields` | Get field metadata for create/edit screens |
+| `jira_projects` | List accessible projects |
+| `jira_users` | Search users by name or email |
+| `jira_attachment` | Download an attachment |
+| `jira_add_link` | Create a link between two issues |
+| `jira_delete_link` | Delete an issue link |
+
+## Resources
+
+| Resource | Description |
+|---|---|
+| `data://jira/link-types` | Available issue link types in your Jira instance |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `jql_syntax` | JQL syntax reference for building search queries |
+
+## Key features
+
+- **Markdown in, Markdown out** — write descriptions and comments in Markdown; they're auto-converted to Atlassian Document Format (ADF). ADF fields from Jira are converted back to Markdown.
+- **Field discovery** — use `jira_fields` to discover required and available fields before creating or editing issues.
+- **User lookup** — use `jira_users` to resolve display names to account IDs for assignment.
+- **Extra fields** — request additional fields on `jira_read` beyond the standard set; rich-text fields are auto-converted.
+- **Link management** — read the `data://jira/link-types` resource to discover available link types, then create or delete links between issues.
+
+## License
+
+MIT

jira2mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "jira2mcp"
+version = "0.1.0"
+description = "MCP server exposing Jira Cloud tools via FastMCP"
+readme = "README.md"
+authors = [
+    { name = "en-ver" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "fastmcp>=3.1.0",
+    "jira2py==0.4.0",
+    "marklassian>=0.1.0",
+    "pathvalidate>=3.3.1",
+    "pyadf>=0.3.0",
+    "pydantic>=2.12.5",
+]
+
+[project.scripts]
+jira2mcp = "jira2mcp:main"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.4",
+    "ty>=0.0.20",
+]

jira2mcp-0.1.0/src/jira2mcp/__init__.py

@@ -0,0 +1,32 @@
+"""Jira MCP Server — Model Context Protocol server for Jira Cloud."""
+
+from importlib.metadata import version as _pkg_version
+
+from fastmcp import FastMCP
+
+from .tools import tools
+
+mcp = FastMCP(
+    "jira2mcp",
+    version=_pkg_version("jira2mcp"),
+    instructions=(
+        "Jira Cloud integration server. All tools are prefixed with 'jira_'.\n"
+        "Key workflows:\n"
+        "- Before creating: use jira_fields with project_key + issue_type to discover required fields\n"
+        "- Before assigning: use jira_users to look up account IDs\n"
+        "- Descriptions and comments accept markdown (auto-converted to ADF)\n"
+        "- Use the extra_fields parameter on jira_read to request additional fields by ID\n"
+        "- Extra fields are returned with display names; rich-text fields are auto-converted from ADF to markdown\n"
+        "- Read the data://jira/link-types resource before creating issue links\n"
+        "- Use jira_comments to read comments (jira_read only shows the count)\n"
+        "- Use the jql_syntax prompt for JQL syntax reference when building search queries"
+    ),
+    mask_error_details=True,
+    on_duplicate="error",
+)
+mcp.mount(tools, namespace="jira")
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    mcp.run(transport="stdio")

jira2mcp-0.1.0/src/jira2mcp/adf.py

@@ -0,0 +1,167 @@
+"""ADF (Atlassian Document Format) conversion utilities.
+
+Uses pyadf for ADF→Markdown (reading from Jira)
+and marklassian for Markdown→ADF (writing to Jira).
+"""
+
+import logging
+from typing import Any
+
+from marklassian import AdfDocument, AdfNode
+from marklassian import markdown_to_adf as _markdown_to_adf
+from pyadf import Document
+
+logger = logging.getLogger(__name__)
+
+
+def adf_to_markdown(adf: Any) -> str:
+    """Convert ADF JSON to Markdown.
+
+    Args:
+        adf: ADF document as a dictionary, or None.
+
+    Returns:
+        Markdown string, or "(none)" if input is empty/invalid.
+    """
+    if not adf or not isinstance(adf, dict):
+        return "(none)"
+
+    try:
+        doc = Document(adf)
+        md = doc.to_markdown()
+        return md.strip() if md else "(none)"
+    except Exception:
+        logger.exception("ADF to Markdown conversion failed, using plain text fallback")
+        return _extract_text_fallback(adf)
+
+
+def markdown_to_adf(markdown: str) -> AdfDocument:
+    """Convert Markdown to ADF JSON.
+
+    Args:
+        markdown: Markdown string.
+
+    Returns:
+        ADF document as a TypedDict.
+    """
+    if not markdown or not markdown.strip():
+        return AdfDocument(type="doc", version=1, content=[])
+
+    try:
+        return _markdown_to_adf(markdown)
+    except Exception:
+        logger.exception("Markdown to ADF conversion failed, wrapping as plain text")
+        return AdfDocument(
+            type="doc",
+            version=1,
+            content=[
+                AdfNode(
+                    type="paragraph",
+                    content=[AdfNode(type="text", text=markdown)],
+                )
+            ],
+        )
+
+
+# --- ADF field detection ---
+
+# System fields known to use ADF format
+_ADF_SYSTEM_FIELDS: set[str] = {"description", "environment"}
+
+# Custom field schema suffix indicating ADF (rich-text paragraph)
+_ADF_CUSTOM_SUFFIX = ":textarea"
+
+
+def is_adf_value(value: Any) -> bool:
+    """Check if a value looks like an ADF document.
+
+    ADF documents are dicts with ``{"type": "doc", "version": 1, "content": [...]}``.
+    """
+    return isinstance(value, dict) and value.get("type") == "doc"
+
+
+def is_adf_field(field_id: str, custom_schema: str = "") -> bool:
+    """Check if a field is known to use ADF format.
+
+    Detection is based on:
+    - Known system fields (description, environment)
+    - Custom field schema containing ':textarea'
+    """
+    if field_id in _ADF_SYSTEM_FIELDS:
+        return True
+    if custom_schema and _ADF_CUSTOM_SUFFIX in custom_schema:
+        return True
+    return False
+
+
+def convert_adf_values(data: dict[str, Any]) -> dict[str, Any]:
+    """Convert any ADF values in a dict to markdown strings.
+
+    Iterates over all values and converts those that look like ADF documents.
+    Non-ADF values are left unchanged.
+    """
+    result = {}
+    for key, value in data.items():
+        if is_adf_value(value):
+            result[key] = adf_to_markdown(value)
+        else:
+            result[key] = value
+    return result
+
+
+def detect_adf_field_ids(fields_metadata: list[dict[str, Any]]) -> set[str]:
+    """Build a set of field IDs that use ADF format.
+
+    Examines field metadata from the Jira fields API and identifies
+    fields that use ADF based on known system fields and custom textarea schema.
+
+    Args:
+        fields_metadata: List of field dicts from ``api.fields.get_fields()``.
+
+    Returns:
+        Set of field IDs that expect ADF format.
+    """
+    adf_ids = set(_ADF_SYSTEM_FIELDS)
+    for field in fields_metadata:
+        field_id = field.get("id", "")
+        schema = field.get("schema", {}) or {}
+        custom = schema.get("custom", "")
+        if custom and _ADF_CUSTOM_SUFFIX in custom:
+            adf_ids.add(field_id)
+    return adf_ids
+
+
+def convert_markdown_fields(
+    fields: dict[str, Any],
+    adf_field_ids: set[str],
+) -> dict[str, Any]:
+    """Convert markdown string values to ADF for known ADF fields.
+
+    Only converts values that are plain strings and whose field ID
+    is in the provided set of ADF field IDs.
+    """
+    result = {}
+    for key, value in fields.items():
+        if key in adf_field_ids and isinstance(value, str):
+            result[key] = markdown_to_adf(value)
+        else:
+            result[key] = value
+    return result
+
+
+def _extract_text_fallback(adf: dict[str, Any]) -> str:
+    """Extract plain text from ADF as a last resort."""
+    texts: list[str] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            if node.get("type") == "text" and "text" in node:
+                texts.append(node["text"])
+            for child in node.get("content", []):
+                walk(child)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(adf)
+    return " ".join(texts).strip() or "(none)"