jira-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Jira MCP (Model Control Protocol) connector written in Go that enables AI assistants like Claude to interact with Atlassian Jira. The project provides a comprehensive set of tools for managing Jira issues, sprints, comments, worklogs, and more through structured MCP tool calls.

Development Commands

# Build the project
go build -o jira-mcp .

# Run in development mode with HTTP server (requires .env file)
go run . --env .env --http_port 3002

# Run tests
go test ./...

# Install locally
go install

# Use go doc to understand packages and types
go doc <pkg>
go doc <sym>[.<methodOrField>]

Architecture Overview

Core Structure

• main.go - Entry point that initializes the MCP server, validates environment variables, and registers all tools
• services/ - Service layer containing Jira client setup and authentication
• tools/ - Tool implementations organized by functionality (issues, sprints, comments, etc.)
• util/ - Utility functions for error handling and response formatting

Key Dependencies

• github.com/ctreminiom/go-atlassian - Go client library for Atlassian APIs
• github.com/mark3labs/mcp-go - Go implementation of Model Control Protocol
• github.com/joho/godotenv - Environment variable loading

Tool Implementation Pattern

Each Jira operation follows this consistent pattern using typed handlers:

1. Input Struct - Define typed input with validation tags
2. Registration Function (RegisterJira<Category>Tool) - Creates tool definitions and registers them with the MCP server
3. Typed Handler Function - Processes tool calls with compile-time type safety

Example tool structure:

// 1. Define input struct with validation
type GetIssueInput struct {
    IssueKey string `json:"issue_key" validate:"required"`
    Fields   string `json:"fields,omitempty"`
    Expand   string `json:"expand,omitempty"`
}

// 2. Registration function
func RegisterJiraIssueTool(s *server.MCPServer) {
    tool := mcp.NewTool("jira_get_issue",
        mcp.WithDescription("..."),
        mcp.WithString("issue_key", mcp.Required(), mcp.Description("...")),
        mcp.WithString("fields", mcp.Description("...")),
    )
    s.AddTool(tool, mcp.NewTypedToolHandler(jiraGetIssueHandler))
}

// 3. Typed handler with automatic validation
func jiraGetIssueHandler(ctx context.Context, request mcp.CallToolRequest, input GetIssueInput) (*mcp.CallToolResult, error) {
    client := services.JiraClient()
    // Direct access to validated parameters - no type assertions needed
    issue, response, err := client.Issue.Get(ctx, input.IssueKey, fields, expand)
    if err != nil {
        return nil, fmt.Errorf("failed to get issue: %v", err)
    }
    return mcp.NewToolResultText(util.FormatIssue(issue)), nil
}