jira-pilot 1.1.0 → 2.0.1

package/README.md

@@ -4,24 +4,37 @@
 
 `jira-pilot` is a next-generation Command Line Interface for Jira. It bridges the gap between traditional developer tools and modern AI Agents.
 
-- **For Humans:** A beautiful, interactive CLI to manage issues, sprints, and code without leaving your terminal.
-- **For Agents:** A fully compliant **Model Context Protocol (MCP)** server that lets AI assistants (like Claude Desktop (Claude Desktop) or Gemini) interact with your Jira instance safely.
+- **For Humans:** A beautiful, interactive CLI to manage issues, sprints, boards, and code without leaving your terminal.
+- **For Agents:** A fully compliant **Model Context Protocol (MCP)** server with 8 tools that lets AI assistants (like Claude Desktop or Gemini) interact with your Jira instance safely.
 
-## ✨ Features
+---
+
+## Features at a Glance
 
 ### 👤 Human-Centric Features
-- **Interactive Wizards**: Create and transition issues with `enquirer` prompts. No more remembering complex flags.
-- **Git Integration**: Create feature branches directly from issues with smart naming.
-  - `jira git branch PROJ-123` -> `feature/PROJ-123-fix-login-bug`
-- **Rich Visualization**: Beautiful tables and formatted output.
-- **AI Copilot**:
-  - `jira ai summarize PROJ-123`: Get a TL;DR of long issue threads.
-  - `jira ai draft`: Draft descriptions from bullet points (Coming Soon).
+| Feature | Description |
+|---------|-------------|
+| **Issue Management** | Create, view, list, transition, assign, and comment on issues |
+| **Interactive Wizards** | Step-by-step prompts with `enquirer` — no flags required |
+| **Board & Sprint Management** | List boards, view sprints by state |
+| **Git Integration** | Create feature branches from issues with smart naming |
+| **AI Copilot** | Summarize issues, draft descriptions, get next-action suggestions |
+| **Rich Visualization** | Beautiful tables, spinners, and formatted output |
+| **Export** | Export issues list to JSON or Markdown files |
 
 ### 🤖 Agentic Features (MCP)
-- **Agent Skill**: Run `jira mcp` to start a stdio server.
-- **Standardized Tools**: Exposes `list_issues`, `get_issue`, `create_issue` to any MCP client.
-- **Low-Context Mode**: Optimized JSON outputs for LLM consumption.
+| Feature | Description |
+|---------|-------------|
+| **8 MCP Tools** | list_issues, get_issue, create_issue, transition_issue, assign_issue, add_comment, list_projects, list_sprints |
+| **LLM-Optimized** | Clean, structured JSON responses for efficient token usage |
+| **Stdio Transport** | Standard MCP stdio server — works with any MCP client |
+
+### 🧠 Multi-Provider AI
+| Provider | Model |
+|----------|-------|
+| **OpenAI** | GPT-4o |
+| **Google Gemini** | gemini-2.0-flash |
+| **Anthropic** | claude-sonnet (claude-sonnet-4-20250514) |
 
 ---
 
@@ -32,12 +45,14 @@
 npm install -g jira-pilot
 ```
 
+After installing, the `jira` command is available globally.
+
 ### Local Development
 ```bash
-git clone https://github.com/yourusername/jira-pilot.git
+git clone https://github.com/Aarul5/jira-pilot.git
 cd jira-pilot
 npm install
-npm link
+npm link   # Makes 'jira' command available globally
 ```
 
 ---
@@ -46,80 +61,211 @@ npm link
 
 Before using the tool, set up your credentials. You can get an API Token from [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens).
 
+### Initial Setup
 ```bash
 jira config setup
 ```
 
 You will be prompted for:
-1.  **Jira Site URL**: e.g., `https://your-company.atlassian.net`
-2.  **Email**: Your Atlassian account email.
-3.  **API Token**: The token you generated.
-4.  **AI API Key (Optional)**: Your OpenAI API Key (for `jira ai` commands).
-
-To view current config:
+1. **Jira Site URL** — e.g., `https://your-company.atlassian.net`
+2. **Email** — Your Atlassian account email
+3. **API Token** — The token you generated from Atlassian
+4. **Enable AI** — Toggle AI features on/off
+5. **AI Provider** — Choose between `openai`, `gemini`, or `anthropic`
+6. **AI API Key** — Your API key for the selected provider
+
+### View / Clear Configuration
 ```bash
-jira config view
+jira config view     # Show current configuration (keys are masked)
+jira config clear    # Remove all stored credentials
 ```
 
+> **Note:** Credentials are stored securely using the `conf` library in your system's config directory.
+
 ---
 
 ## 📖 Usage
 
-### Issues
+### 📋 Issue Management
+
+#### List Issues
 ```bash
-# List issues (default: assigned to you, active sprints)
+# List issues assigned to you in active sprints
 jira issue list
 
 # List with custom JQL
 jira issue list --jql "project = PROJ AND priority = High"
 
-# Create a new issue (interactive)
-jira issue create
+# Filter by project, assignee, or status
+jira issue list --project PROJ --assignee "john.doe" --status "In Progress"
+
+# Limit results
+jira issue list --limit 20
 
-# View details
+# Export results to file
+jira issue list --export json    # Creates issues-TIMESTAMP.json
+jira issue list --export md      # Creates issues-TIMESTAMP.md
+
+# Combine filters and export
+jira issue list --project PROJ --status Done --export json
+```
+
+#### View Issue Details
+```bash
 jira issue view PROJ-123
+```
+Displays: summary, status, priority, assignee, description, and recent comments.
+
+#### Create Issue
+```bash
+# Interactive wizard (recommended)
+jira issue create
+
+# Non-interactive with flags
+jira issue create -p PROJ -s "Fix login bug"
+jira issue create -p PROJ -t Bug -s "Crash on save" --priority High
+jira issue create -p PROJ -t Story -s "Add dark mode" -d "Users want a dark theme" -a me
+```
 
-# Transition status (interactive)
+**Interactive Wizard Steps:**
+1. **Select Project** — Choose from your accessible projects
+2. **Select Issue Type** — Bug, Story, Task, Epic, etc.
+3. **Enter Summary** — Required issue title
+4. **Enter Description** — Optional, converted to Jira ADF format
+5. **Select Priority** — High, Medium, Low, etc.
+6. **Assign** — Myself, Unassigned, or search by name/email
+
+#### Transition Issue Status
+```bash
+# Interactive — shows available transitions
 jira issue transition PROJ-123
 
-# Export issues to file
-jira issue list --export json  # Creates issues-TIMESTAMP.json
-jira issue list --export md    # Creates issues-TIMESTAMP.md
+# Direct — specify target status
+jira issue transition PROJ-123 --status "In Progress"
+jira issue transition PROJ-123 -s Done
+```
+
+#### Assign / Reassign Issue
+```bash
+# Interactive — choose Myself, Unassign, or Search
+jira issue assign PROJ-123
 
-# Combine filters and export (Power User)
-jira issue list --project "project-name" --assignee "assignee_name" --status Done --export json
+# Quick assign
+jira issue assign PROJ-123 -a me       # Assign to yourself
+jira issue assign PROJ-123 -a none     # Unassign
 ```
 
-### Projects & Sprints
+#### Add Comment
+```bash
+# Interactive — prompts for comment text
+jira issue comment PROJ-123
+
+# Inline comment
+jira issue comment PROJ-123 -m "Fixed in latest build"
+```
+
+---
+
+### 📂 Projects & Boards
+
+#### List Projects
 ```bash
-# List projects
 jira project list
+```
+Displays: project key, name, lead, and style in a formatted table.
 
-# List sprints for a board
+#### List Boards
+```bash
+# List all boards
+jira board list
+
+# Filter by project
+jira board list -p PROJ
+
+# Filter by type
+jira board list -t scrum
+jira board list -t kanban
+```
+
+#### List Sprints
+```bash
+# List active and future sprints
 jira sprint list --board 5
+
+# List by board name
+jira sprint list --board "My Team Board"
+
+# Filter by state
+jira sprint list --board 5 --state active
+jira sprint list --board 5 --state closed
 ```
 
-### Git Integration
-Create a branch automatically named from the issue summary:
+---
+
+### 🌿 Git Integration
+
+Create feature branches automatically named from the issue summary:
 ```bash
 jira git branch PROJ-123
 # Output: Switched to a new branch 'feature/PROJ-123-fix-login-modal'
 ```
 
-### AI Features
-Summarize a complex issue thread:
+---
+
+### 🤖 AI Features
+
+> **Requires:** AI features must be enabled via `jira config setup` with a valid API key for your chosen provider (OpenAI, Gemini, or Anthropic).
+
+#### Summarize an Issue
+Get an AI-generated TL;DR of long issue threads with comments:
 ```bash
 jira ai summarize PROJ-123
 ```
-*(Requires OpenAI Key in config)*
+
+#### Draft an Issue Description
+Generate a structured issue description from rough notes or bullet points:
+```bash
+# Interactive — prompts for your notes
+jira ai draft
+
+# Inline with issue type context
+jira ai draft -i "login fails, returns 500, only on mobile" -t bug
+jira ai draft -i "add dark mode toggle to settings" -t story
+```
+
+#### Suggest Next Actions
+Analyze an issue and get AI-powered suggestions for what to do next:
+```bash
+jira ai suggest PROJ-123
+```
+Returns: **Immediate Next Action**, **Potential Blockers**, **Suggested Status Transition**, and **Recommendations**.
 
 ---
 
-## 🧠 Using with AI Agents (Claude/Gemini)
+## 🧠 Using with AI Agents (MCP)
 
 `jira-pilot` implements the **Model Context Protocol (MCP)**, making it plug-and-play for AI assistants.
 
+### Starting the MCP Server
+```bash
+jira mcp
+```
+
+### Available MCP Tools
+
+| Tool | Description | Required Args |
+|------|-------------|---------------|
+| `jira_list_issues` | Search issues via JQL | `jql` |
+| `jira_get_issue` | Get full issue details | `issueKey` |
+| `jira_create_issue` | Create a new issue (ADF) | `projectKey`, `summary` |
+| `jira_transition_issue` | List or execute transitions | `issueKey` |
+| `jira_assign_issue` | Assign/unassign an issue | `issueKey` |
+| `jira_add_comment` | Add a comment (ADF) | `issueKey`, `body` |
+| `jira_list_projects` | List accessible projects | — |
+| `jira_list_sprints` | List sprints for a board | `boardId` |
+
 ### Claude Desktop Configuration
+
 Add the following to your `claude_desktop_config.json`:
 
 ```json
@@ -133,12 +279,32 @@ Add the following to your `claude_desktop_config.json`:
 }
 ```
 
-Once connected, you can ask Claude things like:
-> "Check my assigned Jira issues and create a feature branch for the highest priority one."
+### VS Code / Cursor Configuration
+
+Add to your `.vscode/mcp.json` or equivalent:
+
+```json
+{
+  "servers": {
+    "jira-pilot": {
+      "command": "jira",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Example Agent Prompts
+Once connected, you can ask your AI assistant things like:
+- *"Show me my high-priority Jira issues"*
+- *"Create a bug for the login crash on mobile in project PROJ"*
+- *"Transition PROJ-123 to In Progress and assign it to me"*
+- *"Add a comment to PROJ-456 saying the fix is deployed"*
+- *"What sprints are active on board 5?"*
 
 ---
 
-## 🛠️ Testing & Verification
+## 🧪 Testing & Verification
 
 ### Testing the MCP Server
 You can test the MCP server functionality using the official [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
@@ -148,17 +314,60 @@ npx @modelcontextprotocol/inspector node ./bin/jira.js mcp
 ```
 
 This will launch a web interface where you can:
-1.  View available tools (`jira_list_issues`, `jira_get_issue`, `jira_create_issue`).
-2.  Execute tools and view output.
-3.  Inspect request/response logs.
+1. View all 8 available tools and their schemas
+2. Execute tools with custom arguments
+3. Inspect request/response logs
+
+---
+
+## 📦 CLI Command Reference
+
+```
+jira [command]
+
+Commands:
+  config           Configure Jira credentials
+  issue            Manage Jira issues
+  project          Manage Jira projects
+  board            Manage Jira boards
+  sprint           Manage Sprints
+  git              Git integration for Jira
+  ai               AI Helper commands
+  mcp              Start MCP Agent Server (Stdio)
+
+Issue Subcommands:
+  issue list       List issues (JQL, filters, export)
+  issue view       View issue details
+  issue create     Create a new issue (wizard or flags)
+  issue transition Transition issue status
+  issue assign     Assign or reassign an issue
+  issue comment    Add a comment to an issue
+
+AI Subcommands:
+  ai summarize     Summarize an issue using AI
+  ai draft         Draft issue description from notes
+  ai suggest       Suggest next actions for an issue
+
+Board Subcommands:
+  board list       List Jira boards
+
+Sprint Subcommands:
+  sprint list      List sprints for a board
+```
 
 ---
 
-## 🛠️ Project Structure
-- `bin/`: Entry point.
-- `src/commands/`: CLI command definitions (Human UI).
-- `src/server/`: MCP Server implementation (Agent UI).
-- `src/services/`: Core logic (API, AI).
+## 🤝 Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+```bash
+git clone https://github.com/Aarul5/jira-pilot.git
+cd jira-pilot
+npm install
+npm link
+```
 
 ## 📄 License
+
 ISC

package/bin/jira.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { readFileSync } from 'fs';
@@ -19,6 +19,8 @@ program
 Examples:
   $ jira issue list
   $ jira issue view PROJ-123
+  $ jira issue create
+  $ jira board list
   $ jira sprint list --board 123
   $ jira ai summarize PROJ-123
     `);
@@ -27,6 +29,7 @@ import { registerConfigCommand } from '../src/commands/config.js';
 import { registerIssueCommand } from '../src/commands/issue.js';
 import { registerProjectCommand } from '../src/commands/project.js';
 import { registerSprintCommand } from '../src/commands/sprint.js';
+import { registerBoardCommand } from '../src/commands/board.js';
 import { registerGitCommand } from '../src/commands/git.js';
 import { registerAiCommand } from '../src/commands/ai.js';
 import { registerMcpCommand } from '../src/commands/mcp.js';
@@ -36,6 +39,7 @@ registerConfigCommand(program);
 registerIssueCommand(program);
 registerProjectCommand(program);
 registerSprintCommand(program);
+registerBoardCommand(program);
 registerGitCommand(program);
 registerAiCommand(program);
 registerMcpCommand(program);

package/package.json

@@ -1,32 +1,69 @@
 {
     "name": "jira-pilot",
-    "version": "1.1.0",
-    "description": "AI-powered Jira CLI for humans and agents",
+    "version": "2.0.1",
+    "description": "AI-powered Jira CLI for humans and agents — manage issues, sprints, boards with interactive wizards, multi-provider AI (OpenAI/Gemini/Anthropic), and an 8-tool MCP server for AI assistants",
     "main": "src/index.js",
     "type": "module",
     "bin": {
-        "jira": "./bin/jira.js"
+        "jira": "./bin/jira.js",
+        "jira-pilot": "./bin/jira.js"
     },
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1",
+        "start": "node bin/jira.js",
+        "mcp": "node bin/jira.js mcp",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
         "link": "npm link"
     },
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "files": [
+        "bin/",
+        "src/",
+        "README.md",
+        "LICENSE"
+    ],
     "keywords": [
         "jira",
         "cli",
-        "ai",
-        "agent",
-        "mcp",
+        "jira-cli",
         "jira-client",
-        "jiracli",
-        "atlassian",
         "jira-api",
+        "atlassian",
+        "atlassian-jira",
+        "ai",
+        "ai-cli",
+        "openai",
+        "gemini",
+        "anthropic",
+        "claude",
+        "gpt",
+        "mcp",
+        "model-context-protocol",
+        "ai-agent",
+        "agent",
         "issue-tracker",
+        "project-management",
         "task-management",
+        "sprint",
+        "kanban",
+        "scrum",
+        "agile",
         "command-line",
-        "typescript"
+        "interactive",
+        "terminal",
+        "developer-tools",
+        "devtools",
+        "productivity",
+        "workflow",
+        "git-integration"
     ],
-    "author": "Arul",
+    "author": {
+        "name": "Arul",
+        "url": "https://github.com/Aarul5"
+    },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/Aarul5/jira-pilot.git"
@@ -46,5 +83,9 @@
         "open": "^10.0.0",
         "ora": "^8.0.0",
         "table": "^6.8.0"
+    },
+    "devDependencies": {
+        "@vitest/coverage-v8": "^4.0.18",
+        "vitest": "^4.0.18"
     }
 }

package/src/commands/ai.js

@@ -5,6 +5,7 @@ import enquirer from 'enquirer';
 import { api } from '../services/api-service.js';
 import { aiService } from '../services/ai-service.js';
 import { parseADF } from '../utils/adf-parser.js';
+import { validateIssueKey } from '../utils/validators.js';
 
 export function registerAiCommand(program) {
     const aiCmd = new Command('ai')
@@ -22,6 +23,8 @@ Common Actions:
         .description('Summarize an issue using AI')
         .argument('<issueKey>', 'Jira Issue Key')
         .action(async (issueKey) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             const spinner = ora(`Fetching issue ${issueKey}...`).start();
             try {
                 const issue = await api.get(`/issue/${issueKey}?fields=summary,description,comment`);
@@ -141,6 +144,8 @@ Keep it professional and concise. Output in plain text (not markdown headers, us
         .description('Suggest next actions for an issue based on its context')
         .argument('<issueKey>', 'Jira Issue Key')
         .action(async (issueKey) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             const spinner = ora(`Analyzing issue ${issueKey}...`).start();
             try {
                 const issue = await api.get(`/issue/${issueKey}?fields=summary,description,status,assignee,priority,comment,issuetype`);

package/src/commands/board.js

@@ -0,0 +1,66 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { table } from 'table';
+import { api } from '../services/api-service.js';
+import ora from 'ora';
+import { handleCommandError } from '../utils/error-handler.js';
+
+export function registerBoardCommand(program) {
+    const boardCmd = new Command('board')
+        .description('Manage Jira boards')
+        .addHelpText('after', `
+Common Actions:
+  $ jira board list                   # List all boards
+  $ jira board list -p PROJ           # List boards for a project
+        `);
+
+    boardCmd
+        .command('list')
+        .description('List Jira boards')
+        .option('-p, --project <key>', 'Filter by project key')
+        .option('-t, --type <type>', 'Filter by board type (scrum, kanban, simple)')
+        .option('-l, --limit <n>', 'Max results', '50')
+        .action(async (options) => {
+            const spinner = ora('Fetching boards...').start();
+            try {
+                const params = new URLSearchParams();
+                params.set('maxResults', options.limit);
+
+                if (options.project) {
+                    params.set('projectKeyOrId', options.project);
+                }
+                if (options.type) {
+                    params.set('type', options.type);
+                }
+
+                const data = await api.agileGet(`/board?${params.toString()}`);
+                spinner.stop();
+
+                if (!data.values || data.values.length === 0) {
+                    console.log(chalk.yellow('No boards found.'));
+                    return;
+                }
+
+                const tableData = [
+                    [chalk.bold('ID'), chalk.bold('Name'), chalk.bold('Type'), chalk.bold('Project')]
+                ];
+
+                data.values.forEach(b => {
+                    tableData.push([
+                        b.id,
+                        b.name,
+                        b.type,
+                        b.location?.projectKey || '-'
+                    ]);
+                });
+
+                console.log(table(tableData));
+                console.log(chalk.grey(`Showing ${data.values.length} board(s)`));
+
+            } catch (e) {
+                handleCommandError(spinner, e, 'Failed to list boards');
+            }
+        });
+
+    program.addCommand(boardCmd);
+}

package/src/commands/git.js

@@ -4,6 +4,7 @@ import { execSync } from 'child_process';
 import { api } from '../services/api-service.js';
 import ora from 'ora';
 import enquirer from 'enquirer';
+import { validateIssueKey } from '../utils/validators.js';
 
 export function registerGitCommand(program) {
     const gitCmd = new Command('git')
@@ -15,6 +16,8 @@ export function registerGitCommand(program) {
         .argument('<issueKey>', 'Jira Issue Key (e.g., PROJ-123)')
         .option('-t, --type <type>', 'Branch type (feature, bugfix, hotfix)', 'feature')
         .action(async (issueKey, options) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             const spinner = ora(`Fetching issue ${issueKey}...`).start();
             try {
                 const issue = await api.get(`/issue/${issueKey}`);

package/src/commands/issue.js

@@ -6,6 +6,7 @@ import ora from 'ora';
 import enquirer from 'enquirer';
 import { parseADF } from '../utils/adf-parser.js';
 import { textToADF } from '../utils/text-to-adf.js';
+import { validateIssueKey } from '../utils/validators.js';
 
 export function registerIssueCommand(program) {
     const issueCmd = new Command('issue')
@@ -136,6 +137,8 @@ Examples:
   $ jira issue view PROJ-123
         `)
         .action(async (issueKey) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             const spinner = ora(`Fetching issue ${issueKey}...`).start();
             try {
                 const issue = await api.get(`/issue/${issueKey}`);
@@ -464,6 +467,8 @@ Examples:
   $ jira issue transition PROJ-123 -s Done
         `)
         .action(async (issueKey, options) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             const spinner = ora(`Fetching transitions for ${issueKey}...`).start();
             try {
                 // Fetch current issue to show context
@@ -554,6 +559,8 @@ Examples:
   $ jira issue assign PROJ-123 -a none     # Unassign
         `)
         .action(async (issueKey, options) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             try {
                 let assigneeId = options.assignee;
 
@@ -649,6 +656,8 @@ Examples:
   $ jira issue comment PROJ-123 -m "Fixed in latest build"
         `)
         .action(async (issueKey, options) => {
+            const check = validateIssueKey(issueKey);
+            if (!check.valid) { console.error(chalk.red(check.message)); return; }
             try {
                 let commentText = options.message;
 

package/src/commands/sprint.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { table } from 'table';
 import { api } from '../services/api-service.js';
 import ora from 'ora';
+import { handleCommandError } from '../utils/error-handler.js';
 
 export function registerSprintCommand(program) {
     const sprintCmd = new Command('sprint')
@@ -15,57 +16,27 @@ Common Actions:
     sprintCmd
         .command('list')
         .description('List sprints for a board')
-        .requiredOption('-b, --board <id>', 'Board ID')
+        .requiredOption('-b, --board <id>', 'Board ID or name')
         .option('-s, --state <state>', 'State (active, future, closed)', 'active,future')
         .action(async (options) => {
             const spinner = ora(`Fetching sprints for board ${options.board}...`).start();
             try {
-                // Agile API usually involves /rest/agile/1.0
-                // My default ApiService is /rest/api/3. I might need to override or allow full path?
-                // ApiService handles baseURL. I should make it flexible or add Agile support.
-
-                // HACK: ApiService constructor sets base to /rest/api/3. 
-                // I need to use a different client or hack the URL.
-                // Axios allows absolute URLs to override baseURL.
-                // So if I pass full URL it works.
-
-                const { jiraUrl } = (await import('../utils/config.js')).getCredentials();
-                // Assuming api-service exposes client or get method.
-                // But get method prepend baseURL? No, axios usually supports absolute URL.
-
-                // Let's modify ApiService later to support 'type' or just use full path if needed.
-                // Or simpler: /rest/agile/1.0/board/${id}/sprint
-                // But api service baseURL is fixed.
-
-                // To fix this proper: I'll modify ApiService to allow changing API version/path or just use full path.
-                // Using full path:
-                const match = jiraUrl.match(/^https?:\/\/(.+?)(\/|$)/);
-                const domain = match ? match[0].replace(/\/$/, '') : jiraUrl;
-
                 let boardId = options.board;
 
-                // If board option is not a number, try to look it up using the Board Name/Key
+                // If board option is not a number, look it up by name
                 if (isNaN(boardId)) {
                     spinner.text = `Looking up board "${options.board}"...`;
-                    const boardSearchUrl = `${domain}/rest/agile/1.0/board?name=${encodeURIComponent(options.board)}`;
-                    const boardData = await api.get(boardSearchUrl);
+                    const boardData = await api.agileGet(`/board?name=${encodeURIComponent(options.board)}`);
 
                     if (!boardData.values || boardData.values.length === 0) {
-                        // Fallback: It might be a project key. Let's try searching for boards associated with this project.
-                        // But the API doesn't support projectKey filter directly on /board easily without iterating.
-                        // For now, fail if name match doesn't work.
                         throw new Error(`Board with name "${options.board}" not found. Please provide the numeric Board ID.`);
                     }
 
-                    // Strict match or pick first? Let's pick the first one but warn if multiple
                     if (boardData.values.length > 1) {
-                        // Try to find exact match
                         const exact = boardData.values.find(b => b.name.toLowerCase() === options.board.toLowerCase());
                         if (exact) {
                             boardId = exact.id;
                         } else {
-                            // Just pick first? Or error?
-                            // Let's pick first but log
                             console.log(chalk.yellow(`\nMultiple boards found for "${options.board}". Using "${boardData.values[0].name}" (ID: ${boardData.values[0].id}).`));
                             boardId = boardData.values[0].id;
                         }
@@ -75,9 +46,7 @@ Common Actions:
                     spinner.text = `Fetching sprints for board ${options.board} (ID: ${boardId})...`;
                 }
 
-                const fullUrl = `${domain}/rest/agile/1.0/board/${boardId}/sprint?state=${options.state}`;
-
-                const data = await api.get(fullUrl);
+                const data = await api.agileGet(`/board/${boardId}/sprint?state=${options.state}`);
                 spinner.stop();
 
                 if (!data.values || data.values.length === 0) {
@@ -101,17 +70,7 @@ Common Actions:
                 console.log(table(tableData));
 
             } catch (e) {
-                spinner.fail('Failed to list sprints');
-                if (e.response) {
-                    if (e.response.status === 404) {
-                        console.error(chalk.red(`\nError: Board with ID "${options.board}" not found or you do not have permission to view it.`));
-                        console.error(chalk.grey('Tip: Verify the Board ID in your Jira URL: /jira/software/c/projects/KEY/boards/ID'));
-                    } else {
-                        console.error(chalk.red(`Error ${e.response.status}: `), e.response.data);
-                    }
-                } else {
-                    console.error(chalk.red(e.message));
-                }
+                handleCommandError(spinner, e, 'Failed to list sprints');
             }
         });
 

package/src/server/mcp-server.js

@@ -3,7 +3,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { api } from "../services/api-service.js";
 import { textToADF } from "../utils/text-to-adf.js";
-import { getCredentials } from "../utils/config.js";
 
 // Initialize MCP Server
 const server = new Server(
@@ -298,14 +297,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         // ── jira_list_sprints ───────────────────────────────
         if (name === "jira_list_sprints") {
-            const { jiraUrl } = getCredentials();
-            const match = jiraUrl.match(/^https?:\/\/(.+?)(\/|$)/);
-            const domain = match ? match[0].replace(/\/$/, '') : jiraUrl;
-
             const state = args.state || 'active,future';
-            const fullUrl = `${domain}/rest/agile/1.0/board/${args.boardId}/sprint?state=${state}`;
-
-            const data = await api.get(fullUrl);
+            const data = await api.agileGet(`/board/${args.boardId}/sprint?state=${state}`);
 
             const sprints = (data.values || []).map(s => ({
                 id: s.id,

package/src/services/api-service.js

@@ -11,45 +11,59 @@ export class ApiService {
         const { jiraUrl, email, apiToken } = getCredentials();
 
         if (!jiraUrl || !email || !apiToken) {
-            // Don't throw here, allow initialization for 'config' command usage
             this.client = null;
+            this._domain = null;
             return;
         }
 
         const match = jiraUrl.match(/^https?:\/\/(.+?)(\/|$)/);
-        const domain = match ? match[0] : jiraUrl;
+        this._domain = match ? match[0].replace(/\/$/, '') : jiraUrl;
 
+        const authHeader = `Basic ${Buffer.from(`${email}:${apiToken}`).toString('base64')}`;
+
+        // Standard REST API v3 client
         this.client = axios.create({
-            baseURL: `${domain.replace(/\/$/, '')}/rest/api/3`,
+            baseURL: `${this._domain}/rest/api/3`,
+            headers: {
+                'Authorization': authHeader,
+                'Accept': 'application/json',
+                'Content-Type': 'application/json'
+            }
+        });
+
+        // Agile REST API v1 client (for boards, sprints, etc.)
+        this.agileClient = axios.create({
+            baseURL: `${this._domain}/rest/agile/1.0`,
             headers: {
-                'Authorization': `Basic ${Buffer.from(`${email}:${apiToken}`).toString('base64')}`,
+                'Authorization': authHeader,
                 'Accept': 'application/json',
                 'Content-Type': 'application/json'
             }
         });
 
-        // Response interceptor for error handling
-        this.client.interceptors.response.use(
-            response => response,
-            error => {
-                if (error.response) {
-                    if (error.response.status === 401) {
-                        console.error(chalk.red('Authentication failed. Please check your credentials using "jira config".'));
-                    } else if (error.response.status === 403) {
-                        console.error(chalk.red('Access denied. You may not have permission for this resource.'));
-                    } else if (error.response.status === 404) {
-                        // Sometime 404 is valid (issues not found), let caller handle? 
-                        // Or log generic error? For now rethrow with clean message property if possible.
-                    }
+        // Shared response interceptor
+        const errorInterceptor = (error) => {
+            if (error.response) {
+                if (error.response.status === 401) {
+                    console.error(chalk.red('Authentication failed. Please check your credentials using "jira config".'));
+                } else if (error.response.status === 403) {
+                    console.error(chalk.red('Access denied. You may not have permission for this resource.'));
                 }
-                return Promise.reject(error);
             }
-        );
+            return Promise.reject(error);
+        };
+
+        this.client.interceptors.response.use(r => r, errorInterceptor);
+        this.agileClient.interceptors.response.use(r => r, errorInterceptor);
+    }
+
+    /** @returns {string} The Jira domain URL */
+    get domain() {
+        return this._domain;
     }
 
     ensureClient() {
         if (!this.client) {
-            // Try to re-init in case config was just set
             this.init();
             if (!this.client) {
                 throw new Error('Jira credentials not configured. Run "jira config" first.');
@@ -57,25 +71,18 @@ export class ApiService {
         }
     }
 
+    // ── Standard REST API v3 Methods ────────────────────────────────
+
     async get(url, config = {}) {
         this.ensureClient();
-        try {
-            const response = await this.client.get(url, config);
-            return response.data;
-        } catch (e) {
-            // Optional: Wrap error
-            throw e;
-        }
+        const response = await this.client.get(url, config);
+        return response.data;
     }
 
     async post(url, data, config = {}) {
         this.ensureClient();
-        try {
-            const response = await this.client.post(url, data, config);
-            return response.data;
-        } catch (e) {
-            throw e;
-        }
+        const response = await this.client.post(url, data, config);
+        return response.data;
     }
 
     async put(url, data, config = {}) {
@@ -89,6 +96,20 @@ export class ApiService {
         const response = await this.client.delete(url, config);
         return response.data;
     }
+
+    // ── Agile REST API v1 Methods ───────────────────────────────────
+
+    async agileGet(url, config = {}) {
+        this.ensureClient();
+        const response = await this.agileClient.get(url, config);
+        return response.data;
+    }
+
+    async agilePost(url, data, config = {}) {
+        this.ensureClient();
+        const response = await this.agileClient.post(url, data, config);
+        return response.data;
+    }
 }
 
 export const api = new ApiService();

package/src/utils/error-handler.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+
+/**
+ * Standardized error handler for CLI commands.
+ * Stops the spinner and prints a formatted error message.
+ *
+ * @param {object|null} spinner - Ora spinner instance (will be stopped/failed)
+ * @param {Error} error - The error object
+ * @param {string} [context] - Optional context (e.g., "Failed to list issues")
+ */
+export function handleCommandError(spinner, error, context = 'Operation failed') {
+    // Handle user cancellation (Ctrl+C in enquirer)
+    if (error === '' || (error && error.message === '')) {
+        if (spinner) spinner.stop();
+        console.log(chalk.yellow('\nCancelled.'));
+        return;
+    }
+
+    if (spinner) {
+        spinner.fail(context);
+    } else {
+        console.error(chalk.red(`\n${context}:`));
+    }
+
+    if (error.response) {
+        const status = error.response.status;
+        if (status === 404) {
+            console.error(chalk.red('Resource not found. Check the ID or key.'));
+        } else if (status === 400) {
+            const data = error.response.data;
+            const messages = data?.errorMessages?.join(', ') || (data?.errors
+                ? Object.entries(data.errors).map(([k, v]) => `${k}: ${v}`).join(', ')
+                : JSON.stringify(data));
+            console.error(chalk.red(`Bad Request: ${messages}`));
+        } else {
+            console.error(chalk.red(`Error ${status}: `), error.response.data);
+        }
+    } else {
+        console.error(chalk.red(error.message));
+    }
+}

package/src/utils/validators.js

@@ -0,0 +1,88 @@
+/**
+ * Input Validators for CLI commands.
+ * Validates user input before API calls to catch errors early.
+ */
+
+/**
+ * Validates a Jira issue key format (e.g., PROJ-123).
+ * @param {string} key - The issue key to validate.
+ * @returns {{ valid: boolean, message?: string }}
+ */
+export function validateIssueKey(key) {
+    if (!key || typeof key !== 'string') {
+        return { valid: false, message: 'Issue key is required.' };
+    }
+
+    const trimmed = key.trim().toUpperCase();
+    const pattern = /^[A-Z][A-Z0-9_]+-\d+$/;
+
+    if (!pattern.test(trimmed)) {
+        return {
+            valid: false,
+            message: `Invalid issue key "${key}". Expected format: PROJ-123 (letters/numbers, dash, digits).`
+        };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Validates a Jira project key (e.g., PROJ).
+ * @param {string} key - The project key to validate.
+ * @returns {{ valid: boolean, message?: string }}
+ */
+export function validateProjectKey(key) {
+    if (!key || typeof key !== 'string') {
+        return { valid: false, message: 'Project key is required.' };
+    }
+
+    const trimmed = key.trim().toUpperCase();
+    const pattern = /^[A-Z][A-Z0-9_]+$/;
+
+    if (!pattern.test(trimmed)) {
+        return {
+            valid: false,
+            message: `Invalid project key "${key}". Must start with a letter and contain only uppercase letters, digits, or underscores.`
+        };
+    }
+
+    return { valid: true };
+}
+
+/**
+ * Validates a Jira site URL.
+ * @param {string} url - The URL to validate.
+ * @returns {{ valid: boolean, message?: string }}
+ */
+export function validateUrl(url) {
+    if (!url || typeof url !== 'string') {
+        return { valid: false, message: 'URL is required.' };
+    }
+
+    const trimmed = url.trim();
+
+    try {
+        const parsed = new URL(trimmed);
+        if (!['http:', 'https:'].includes(parsed.protocol)) {
+            return { valid: false, message: 'URL must use http or https protocol.' };
+        }
+        return { valid: true };
+    } catch {
+        return { valid: false, message: `Invalid URL: "${url}". Example: https://your-company.atlassian.net` };
+    }
+}
+
+/**
+ * Sanitizes a JQL string by escaping potentially dangerous characters.
+ * This is a basic sanitization — Jira's API does its own validation too.
+ * @param {string} jql - The JQL query string.
+ * @returns {string} The sanitized JQL string.
+ */
+export function sanitizeJql(jql) {
+    if (!jql || typeof jql !== 'string') {
+        return '';
+    }
+
+    // Remove null bytes and control characters
+    return jql.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '').trim();
+}

package/.github/workflows/publish.yml

@@ -1,22 +0,0 @@
-name: Publish Package
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write 
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-      - run: npm ci
-      - run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}