git clone <repo-url> && cd jira-mcp-server && npm install

JIRA_BASE_URL=https://jira.company.com
JIRA_PAT=<your-pat-token>
JIRA_DEFAULT_PROJECT=XYZ  # Tùy chọn

npm run build                                    # Stdio transport
HTTP_PORT=3000 MCP_AUTH_TOKEN=secret npm start   # HTTP transport

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_PAT": "your-personal-pat-token"
      }
    }
  }
}

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": ["/path/to/jira-mcp-server/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.company.com",
        "JIRA_PAT": "your-personal-pat-token"
      }
    }
  }
}

npm run inspect    # MCP Inspector at http://localhost:8000

# Xem issues của tôi
list_issues({ statusFilter: "open" })

# Chi tiết issue
get_issue_detail({ issueKey: "PROJ-123" })

# Log 2 tiếng hôm qua
log_work({ 
  issueKey: "PROJ-123", 
  timeSpent: "2h", 
  comment: "Fixed UI bug",
  startedAt: "2026-04-12"
})

# Tổng giờ đã log tháng này (summary)
list_worklogs({})

# Xem detail từng worklog entry (kèm worklogId)
list_worklogs({ detail: true })

# Preview trước khi xoá
delete_worklog({
  issueKey: "PROJ-123",
  worklogIds: ["12345", "12346"],
  dryRun: true
})

# Xoá thật sau khi user xác nhận
delete_worklog({
  issueKey: "PROJ-123",
  worklogIds: ["12345", "12346"]
})

# Chuyển sang Done
update_issue({ 
  issueKey: "PROJ-123", 
  transitionName: "Done", 
  resolution: "Fixed"
})

# Update due date
update_issue({
  issueKey: "PROJ-123",
  dueDate: "2026-06-30"
})

# Gỡ due date
update_issue({
  issueKey: "PROJ-123",
  dueDate: "clear"
})

# Thêm labels
update_issue({
  issueKey: "PROJ-123",
  addLabels: ["backend", "urgent"]
})

# Xoá labels
update_issue({
  issueKey: "PROJ-123",
  removeLabels: ["blocked", "needs-info"]
})

# Xoá toàn bộ labels rồi set lại
update_issue({
  issueKey: "PROJ-123",
  clearLabels: true,
  addLabels: ["triaged", "ready"]
})

# Đổi tiêu đề (summary)
update_issue({
  issueKey: "PROJ-123",
  summary: "Tiêu đề mới rõ ràng hơn"
})

# Replace toàn bộ mô tả (description, wiki markup)
update_issue({
  issueKey: "PROJ-123",
  description: "Mô tả mới\n\n* Bước 1\n* Bước 2"
})

# Combine: labels + assignee + transition
update_issue({
  issueKey: "PROJ-123",
  addLabels: ["urgent"],
  assignee: "hieutv",
  transitionName: "In Progress"
})

# Tạo task mới
create_issue({
  projectKey: "PROJ",
  issueType: "Task",
  summary: "Implement feature",
  description: "Add OAuth support",
  priority: "High"
})

npm run build      # TypeScript → dist/
npm run dev        # Watch mode
npm start          # Run server (stdio or HTTP)
npm run inspect    # MCP Inspector (http://localhost:8000)

src/
├── index.ts              # Entry + transport selection
├── jira/
│   ├── client.ts         # REST API wrapper
│   ├── tools/            # Tool registration split theo concern
│   │   ├── index.ts              # Barrel — registerJiraTools()
│   │   ├── user-tools.ts         # get_current_user
│   │   ├── issue-tools.ts        # list_issues, get_issue_detail, update_issue
│   │   ├── issue-drift-warning.ts # Helper drift heuristic
│   │   ├── create-issue-tool.ts  # create_issue (schema lớn)
│   │   └── worklog-tools.ts      # log_work, list_worklogs, delete_worklog
│   └── formatter.ts      # AI-friendly output
├── transports/
│   ├── stdio-transport.ts
│   └── http-transport.ts # Express + Bearer auth
└── shared/utils.ts       # Error handling, chaining

Client (headers) → Nginx (:443 SSL) → Node.js (:3000) → Jira API

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://mcp.company.com/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-Jira-Base-Url": "https://jira.company.com",
        "X-Jira-Pat": "<your-personal-token>"
      }
    }
  }
}

HTTP_PORT=3000 MCP_AUTH_TOKEN=<secret> npm start