pnd-jira-mcp 1.0.0__py3-none-any.whl

pnd_jira_mcp/server.py

@@ -0,0 +1,392 @@
+"""
+Jira MCP Server Module
+
+A standalone MCP (Model Context Protocol) server for Jira integration.
+Can be installed via pip and used independently.
+
+Supported MCP Commands:
+- add_comment: Add a comment to a Jira issue
+- transition_issue: Transition an issue to a new status
+- update_fields: Update fields on an issue
+- update_ai_fields: Update AI-related custom fields
+- get_issue: Get issue details
+- get_transitions: Get available transitions
+- search_issues: Search issues using JQL
+- add_label: Add a label to an issue
+- test_connection: Test Jira connection
+- get_boards: Get Jira boards
+- get_sprints: Get sprints for a board
+- get_sprint: Get sprint details
+- get_active_sprint: Get active sprint for a board
+- get_sprint_issues: Get issues in a sprint
+"""
+
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from mcp import types
+from mcp.server import Server
+
+from .client import JiraClient, JiraConfig
+from .tools import get_jira_tools
+
+logger = logging.getLogger("pnd_jira_mcp")
+
+
+async def handle_jira_tool(
+    name: str,
+    arguments: Dict[str, Any],
+    jira_client: Optional[JiraClient] = None
+) -> List[types.TextContent]:
+    """
+    Handle Jira tool calls.
+    
+    Args:
+        name: Tool name
+        arguments: Tool arguments
+        jira_client: Optional pre-configured JiraClient instance
+        
+    Returns:
+        List of TextContent with results
+    """
+    try:
+        client = jira_client or JiraClient()
+        
+        if name == "add_comment":
+            result_data = client.add_comment(
+                issue_key=arguments["issue_key"],
+                body=arguments["body"],
+                add_qain_label=arguments.get("add_qain_label", True)
+            )
+            result = {
+                "status": "success",
+                "message": f"Comment added to {arguments['issue_key']}",
+                "comment_id": result_data.get("id")
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "transition_issue":
+            success = client.transition_issue(
+                issue_key=arguments["issue_key"],
+                transition_id=arguments["transition_id"],
+                fields=arguments.get("fields"),
+                comment=arguments.get("comment")
+            )
+            result = {
+                "status": "success" if success else "failed",
+                "message": f"Issue {arguments['issue_key']} transitioned" if success else "Transition failed"
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "update_fields":
+            success = client.update_fields(
+                issue_key=arguments["issue_key"],
+                fields=arguments["fields"]
+            )
+            result = {
+                "status": "success" if success else "failed",
+                "message": f"Fields updated on {arguments['issue_key']}" if success else "Update failed"
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "update_ai_fields":
+            success = client.update_ai_fields(
+                issue_key=arguments["issue_key"],
+                ai_used=arguments.get("ai_used", True),
+                agent_name=arguments.get("agent_name"),
+                efficiency_score=arguments.get("efficiency_score"),
+                duration_ms=arguments.get("duration_ms")
+            )
+            result = {
+                "status": "success" if success else "failed",
+                "message": f"AI fields updated on {arguments['issue_key']}" if success else "Update failed"
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_issue":
+            issue = client.get_issue(
+                issue_key=arguments["issue_key"],
+                fields=arguments.get("fields")
+            )
+            if issue:
+                result = {
+                    "status": "success",
+                    "issue": {
+                        "key": issue.key,
+                        "id": issue.id,
+                        "summary": issue.summary,
+                        "status": issue.status,
+                        "issue_type": issue.issue_type,
+                        "description": issue.description,
+                        "assignee": issue.assignee,
+                        "priority": issue.priority,
+                        "labels": issue.labels
+                    }
+                }
+            else:
+                result = {
+                    "status": "not_found",
+                    "message": f"Issue {arguments['issue_key']} not found"
+                }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_transitions":
+            transitions = client.get_transitions(arguments["issue_key"])
+            result = {
+                "status": "success",
+                "issue_key": arguments["issue_key"],
+                "transitions": [
+                    {"id": t["id"], "name": t["name"]}
+                    for t in transitions
+                ]
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "search_issues":
+            issues = client.search_issues(
+                jql=arguments["jql"],
+                max_results=arguments.get("max_results", 50),
+                fields=arguments.get("fields")
+            )
+            result = {
+                "status": "success",
+                "count": len(issues),
+                "issues": [
+                    {
+                        "key": issue.key,
+                        "summary": issue.summary,
+                        "status": issue.status,
+                        "issue_type": issue.issue_type
+                    }
+                    for issue in issues
+                ]
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "add_label":
+            success = client.add_label(
+                issue_key=arguments["issue_key"],
+                label=arguments["label"]
+            )
+            result = {
+                "status": "success" if success else "failed",
+                "message": f"Label '{arguments['label']}' added to {arguments['issue_key']}" if success else "Failed to add label"
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "test_connection":
+            success = client.test_connection()
+            result = {
+                "status": "success" if success else "failed",
+                "message": "Jira connection successful" if success else "Jira connection failed",
+                "config": client.config.to_dict() if success else None
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_boards":
+            boards = client.get_boards(
+                project_key=arguments.get("project_key"),
+                board_type=arguments.get("board_type")
+            )
+            result = {
+                "status": "success",
+                "count": len(boards),
+                "boards": [
+                    {
+                        "id": board["id"],
+                        "name": board["name"],
+                        "type": board.get("type", "unknown")
+                    }
+                    for board in boards
+                ]
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_sprints":
+            sprints = client.get_sprints(
+                board_id=arguments["board_id"],
+                state=arguments.get("state"),
+                max_results=arguments.get("max_results", 50)
+            )
+            result = {
+                "status": "success",
+                "count": len(sprints),
+                "sprints": [
+                    {
+                        "id": sprint["id"],
+                        "name": sprint["name"],
+                        "state": sprint["state"],
+                        "startDate": sprint.get("startDate"),
+                        "endDate": sprint.get("endDate"),
+                        "goal": sprint.get("goal")
+                    }
+                    for sprint in sprints
+                ]
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_sprint":
+            sprint = client.get_sprint(arguments["sprint_id"])
+            if sprint:
+                result = {
+                    "status": "success",
+                    "sprint": {
+                        "id": sprint["id"],
+                        "name": sprint["name"],
+                        "state": sprint["state"],
+                        "startDate": sprint.get("startDate"),
+                        "endDate": sprint.get("endDate"),
+                        "goal": sprint.get("goal"),
+                        "originBoardId": sprint.get("originBoardId")
+                    }
+                }
+            else:
+                result = {
+                    "status": "not_found",
+                    "message": f"Sprint {arguments['sprint_id']} not found"
+                }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_active_sprint":
+            sprint = client.get_active_sprint(arguments["board_id"])
+            if sprint:
+                result = {
+                    "status": "success",
+                    "sprint": {
+                        "id": sprint["id"],
+                        "name": sprint["name"],
+                        "state": sprint["state"],
+                        "startDate": sprint.get("startDate"),
+                        "endDate": sprint.get("endDate"),
+                        "goal": sprint.get("goal")
+                    }
+                }
+            else:
+                result = {
+                    "status": "not_found",
+                    "message": f"No active sprint found for board {arguments['board_id']}"
+                }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        elif name == "get_sprint_issues":
+            issues = client.get_sprint_issues(
+                sprint_id=arguments["sprint_id"],
+                fields=arguments.get("fields"),
+                max_results=arguments.get("max_results", 200)
+            )
+            result = {
+                "status": "success",
+                "count": len(issues),
+                "issues": [
+                    {
+                        "key": issue.key,
+                        "summary": issue.summary,
+                        "status": issue.status,
+                        "issue_type": issue.issue_type,
+                        "assignee": issue.assignee,
+                        "priority": issue.priority
+                    }
+                    for issue in issues
+                ]
+            }
+            return [types.TextContent(type="text", text=json.dumps(result, indent=2))]
+        
+        else:
+            return [types.TextContent(
+                type="text",
+                text=json.dumps({"status": "error", "message": f"Unknown tool: {name}"})
+            )]
+    
+    except Exception as e:
+        logger.error(f"Error handling Jira tool {name}: {e}")
+        return [types.TextContent(
+            type="text",
+            text=json.dumps({"status": "error", "message": str(e)})
+        )]
+
+
+class JiraMCPServer:
+    """
+    Standalone MCP server for Jira operations.
+    
+    Can be run independently without any other dependencies.
+    Communicates via stdio for Claude Desktop compatibility.
+    
+    Environment Variables:
+        JIRA_BASE_URL: Jira instance URL (e.g., https://your-domain.atlassian.net)
+        JIRA_EMAIL: Jira account email
+        JIRA_API_TOKEN: Jira API token
+    """
+    
+    def __init__(
+        self,
+        name: str = "jira-mcp",
+        config: Optional[JiraConfig] = None
+    ):
+        """
+        Initialize the Jira MCP server.
+        
+        Args:
+            name: Server name for MCP identification
+            config: Optional JiraConfig for custom configuration
+        """
+        self.server = Server(name=name)
+        self.config = config
+        self._jira_client: Optional[JiraClient] = None
+        self._register_tools()
+    
+    @property
+    def jira_client(self) -> JiraClient:
+        """Get or create the Jira client."""
+        if self._jira_client is None:
+            self._jira_client = JiraClient(config=self.config)
+        return self._jira_client
+    
+    def _register_tools(self):
+        """Register all Jira tools."""
+        jira_tools = get_jira_tools()
+        
+        @self.server.list_tools()
+        async def list_tools() -> List[types.Tool]:
+            """List all Jira tools."""
+            return jira_tools
+        
+        @self.server.call_tool()
+        async def call_tool(
+            name: str,
+            arguments: Dict[str, Any]
+        ) -> List[types.TextContent]:
+            """Handle Jira tool calls."""
+            return await handle_jira_tool(name, arguments, self.jira_client)
+    
+    async def run(self):
+        """Run the MCP server via stdio."""
+        from mcp.server.stdio import stdio_server
+        
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """Main entry point for standalone Jira MCP server."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    server = JiraMCPServer()
+    await server.run()
+
+
+def main_sync():
+    """Synchronous entry point for CLI."""
+    import asyncio
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    main_sync()

pnd_jira_mcp/tools.py

@@ -0,0 +1,295 @@
+"""
+Jira MCP Tools Module
+
+Defines the MCP tool specifications for Jira operations.
+These tools are exposed via the Jira MCP server for Claude Desktop/Code integration.
+"""
+
+from mcp import types
+from typing import List
+
+
+def get_jira_tools() -> List[types.Tool]:
+    """
+    Get the list of Jira MCP tools.
+    
+    Returns:
+        List of MCP Tool definitions for Jira operations.
+    """
+    return [
+        types.Tool(
+            name="add_comment",
+            description="Add a comment to a Jira issue. Supports markdown formatting which is converted to Atlassian Document Format (ADF).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "body": {
+                        "type": "string",
+                        "description": "Comment body in markdown format"
+                    },
+                    "add_qain_label": {
+                        "type": "boolean",
+                        "description": "Whether to add the qAIn label to the issue (default: true)",
+                        "default": True
+                    }
+                },
+                "required": ["issue_key", "body"]
+            }
+        ),
+        types.Tool(
+            name="transition_issue",
+            description="Transition a Jira issue to a new status. Use get_transitions first to see available transitions.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "transition_id": {
+                        "type": "string",
+                        "description": "ID of the transition to perform (get from get_transitions)"
+                    },
+                    "comment": {
+                        "type": "string",
+                        "description": "Optional comment to add during transition"
+                    },
+                    "fields": {
+                        "type": "object",
+                        "description": "Optional fields to update during transition"
+                    }
+                },
+                "required": ["issue_key", "transition_id"]
+            }
+        ),
+        types.Tool(
+            name="update_fields",
+            description="Update fields on a Jira issue. Supports both standard and custom fields.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "fields": {
+                        "type": "object",
+                        "description": "Dictionary of field names/IDs to values"
+                    }
+                },
+                "required": ["issue_key", "fields"]
+            }
+        ),
+        types.Tool(
+            name="update_ai_fields",
+            description="Update AI-related custom fields on a Jira issue. Convenience method for updating AI tracking fields.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "ai_used": {
+                        "type": "boolean",
+                        "description": "Whether AI was used (default: true)",
+                        "default": True
+                    },
+                    "agent_name": {
+                        "type": "string",
+                        "description": "Name of the AI agent"
+                    },
+                    "efficiency_score": {
+                        "type": "number",
+                        "description": "Effectiveness score (0-100)"
+                    },
+                    "duration_ms": {
+                        "type": "number",
+                        "description": "Duration in milliseconds"
+                    }
+                },
+                "required": ["issue_key"]
+            }
+        ),
+        types.Tool(
+            name="get_issue",
+            description="Get details of a Jira issue by key.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "fields": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional list of specific fields to retrieve"
+                    }
+                },
+                "required": ["issue_key"]
+            }
+        ),
+        types.Tool(
+            name="get_transitions",
+            description="Get available transitions for a Jira issue. Use this to find valid transition IDs before calling transition_issue.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    }
+                },
+                "required": ["issue_key"]
+            }
+        ),
+        types.Tool(
+            name="search_issues",
+            description="Search for Jira issues using JQL (Jira Query Language).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "jql": {
+                        "type": "string",
+                        "description": "JQL query string (e.g., 'project = PROJ AND status = Open')"
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Maximum number of results to return (default: 50)",
+                        "default": 50
+                    },
+                    "fields": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional list of specific fields to retrieve"
+                    }
+                },
+                "required": ["jql"]
+            }
+        ),
+        types.Tool(
+            name="add_label",
+            description="Add a label to a Jira issue.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "issue_key": {
+                        "type": "string",
+                        "description": "Jira issue key (e.g., 'PROJ-123')"
+                    },
+                    "label": {
+                        "type": "string",
+                        "description": "Label to add to the issue"
+                    }
+                },
+                "required": ["issue_key", "label"]
+            }
+        ),
+        types.Tool(
+            name="test_connection",
+            description="Test the Jira connection and verify credentials.",
+            inputSchema={
+                "type": "object",
+                "properties": {}
+            }
+        ),
+        types.Tool(
+            name="get_boards",
+            description="Get all Jira boards, optionally filtered by project or type.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project_key": {
+                        "type": "string",
+                        "description": "Optional project key to filter boards (e.g., 'PROJ')"
+                    },
+                    "board_type": {
+                        "type": "string",
+                        "description": "Optional board type filter",
+                        "enum": ["scrum", "kanban"]
+                    }
+                }
+            }
+        ),
+        types.Tool(
+            name="get_sprints",
+            description="Get sprints for a Jira board. Use get_boards first to find the board ID.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "board_id": {
+                        "type": "integer",
+                        "description": "Board ID (get from get_boards)"
+                    },
+                    "state": {
+                        "type": "string",
+                        "description": "Optional sprint state filter",
+                        "enum": ["active", "closed", "future"]
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Maximum number of results (default: 50)",
+                        "default": 50
+                    }
+                },
+                "required": ["board_id"]
+            }
+        ),
+        types.Tool(
+            name="get_sprint",
+            description="Get details of a specific sprint by ID.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sprint_id": {
+                        "type": "integer",
+                        "description": "Sprint ID"
+                    }
+                },
+                "required": ["sprint_id"]
+            }
+        ),
+        types.Tool(
+            name="get_active_sprint",
+            description="Get the currently active sprint for a board.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "board_id": {
+                        "type": "integer",
+                        "description": "Board ID (get from get_boards)"
+                    }
+                },
+                "required": ["board_id"]
+            }
+        ),
+        types.Tool(
+            name="get_sprint_issues",
+            description="Get all issues in a sprint.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "sprint_id": {
+                        "type": "integer",
+                        "description": "Sprint ID"
+                    },
+                    "fields": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional list of specific fields to retrieve"
+                    },
+                    "max_results": {
+                        "type": "integer",
+                        "description": "Maximum number of results (default: 200)",
+                        "default": 200
+                    }
+                },
+                "required": ["sprint_id"]
+            }
+        ),
+    ]