Jira MCP Server

Instructions

Implementation Reference

• src/mcp_server_jira/server.py:259-317 (handler)

  Primary handler implementing the get_jira_projects MCP tool: paginates through all projects via v3 API, maps to output models.

  async def get_jira_projects(self) -> List[JiraProjectResult]:
      """Get all accessible Jira projects using v3 REST API"""
      logger.info("Starting get_jira_projects...")
      all_projects_data = []
      start_at = 0
      max_results = 50
      page_count = 0
  
      while True:
          page_count += 1
          logger.info(
              f"Pagination loop, page {page_count}: startAt={start_at}, maxResults={max_results}"
          )
  
          try:
              response = await self._v3_api_client.get_projects(
                  start_at=start_at, max_results=max_results
              )
  
              projects = response.get("values", [])
              if not projects:
                  logger.info("No more projects returned. Breaking pagination loop.")
                  break
  
              all_projects_data.extend(projects)
  
              if response.get("isLast", False):
                  logger.info("'isLast' is True. Breaking pagination loop.")
                  break
  
              start_at += len(projects)
  
              # Yield control to the event loop to prevent deadlocks in the MCP framework.
              await asyncio.sleep(0)
  
          except Exception as e:
              logger.error(
                  "Error inside get_jira_projects pagination loop", exc_info=True
              )
              raise
  
      logger.info(
          f"Finished get_jira_projects. Total projects found: {len(all_projects_data)}"
      )
  
      results = []
      for p in all_projects_data:
          results.append(
              JiraProjectResult(
                  key=p.get("key"),
                  name=p.get("name"),
                  id=str(p.get("id")),
                  lead=(p.get("lead") or {}).get("displayName"),
              )
          )
          logger.info(f"Added project {p.get('key')} to results")
      logger.info(f"Returning {len(results)} projects")
      sys.stdout.flush()  # Flush stdout to ensure it's sent to MCP, otherwise hang occurs
      return results

• src/mcp_server_jira/server.py:96-101 (schema)

  Pydantic output model defining project structure returned by the tool.

  class JiraProjectResult(BaseModel):
      key: str
      name: str
      id: str
      lead: Optional[str] = None

• src/mcp_server_jira/server.py:1181-1185 (registration)

  Registers the tool in MCP server's list_tools() with name, description, and parameterless input schema.

      name=JiraTools.GET_PROJECTS.value,
      description="Get all accessible Jira projects",
      inputSchema={"type": "object", "properties": {}, "required": []},
  ),
  Tool(

• src/mcp_server_jira/server.py:1411-1417 (registration)

  Dispatches tool calls to the handler in the MCP call_tool() method.

  case JiraTools.GET_PROJECTS.value:
      logger.info("About to AWAIT jira_server.get_jira_projects...")
      result = await jira_server.get_jira_projects()
      logger.info(
          f"COMPLETED await jira_server.get_jira_projects. Result has {len(result)} items."
      )

• src/mcp_server_jira/jira_v3_api.py:176-242 (helper)

  Low-level paginated API call to Jira v3 /project/search endpoint, invoked by the handler.

  async def get_projects(
      self,
      start_at: int = 0,
      max_results: int = 50,
      order_by: Optional[str] = None,
      ids: Optional[list] = None,
      keys: Optional[list] = None,
      query: Optional[str] = None,
      type_key: Optional[str] = None,
      category_id: Optional[int] = None,
      action: Optional[str] = None,
      expand: Optional[str] = None,
  ) -> Dict[str, Any]:
      """
      Get projects paginated using the v3 REST API.
  
      Returns a paginated list of projects visible to the user using the
      /rest/api/3/project/search endpoint.
  
      Args:
          start_at: The index of the first item to return (default: 0)
          max_results: The maximum number of items to return per page (default: 50)
          order_by: Order the results by a field:
                   - category: Order by project category
                   - issueCount: Order by total number of issues
                   - key: Order by project key
                   - lastIssueUpdatedDate: Order by last issue update date
                   - name: Order by project name
                   - owner: Order by project lead
                   - archivedDate: Order by archived date
                   - deletedDate: Order by deleted date
          ids: List of project IDs to return
          keys: List of project keys to return
          query: Filter projects by query string
          type_key: Filter projects by type key
          category_id: Filter projects by category ID
          action: Filter by action permission (view, browse, edit)
          expand: Expand additional project fields in response
  
      Returns:
          Dictionary containing the paginated response with projects and pagination info
  
      Raises:
          ValueError: If the API request fails
      """
      params = {
          "startAt": start_at,
          "maxResults": max_results,
          "orderBy": order_by,
          "id": ids,
          "keys": keys,
          "query": query,
          "typeKey": type_key,
          "categoryId": category_id,
          "action": action,
          "expand": expand,
      }
  
      params = {k: v for k, v in params.items() if v is not None}
  
      endpoint = "/project/search"
      print(
          f"Fetching projects with v3 API endpoint: {endpoint} with params: {params}"
      )
      response_data = await self._make_v3_api_request("GET", endpoint, params=params)
      print(f"Projects API response: {json.dumps(response_data, indent=2)}")
      return response_data