@softspark/jira-mcp 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +73 -0
  2. package/LICENSE +21 -0
  3. package/README.md +261 -0
  4. package/dist/cli.js +176 -0
  5. package/dist/index.d.ts +20 -0
  6. package/dist/index.js +149 -0
  7. package/package.json +81 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,73 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@softspark/jira-mcp` are documented here.
4
+
5
+ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
6
+ Versioning follows [Semantic Versioning](https://semver.org/).
7
+
8
+ ---
9
+
10
+ ## v1.0.0 -- Initial Public Release (2026-04-14)
11
+
12
+ ### MCP Tools (15)
13
+
14
+ - **`sync_tasks`** -- sync Jira tasks to local cache with optional JQL filter
15
+ - **`read_cached_tasks`** -- read tasks from local cache without hitting Jira
16
+ - **`update_task_status`** -- change task status via workflow transition
17
+ - **`update_task`** -- update existing issue fields (summary, description, priority, labels) with ADF conversion
18
+ - **`add_task_comment`** -- add markdown comment (auto-converted to ADF)
19
+ - **`reassign_task`** -- reassign or unassign a task by email
20
+ - **`get_task_statuses`** -- get valid workflow transitions for a task
21
+ - **`get_task_details`** -- get full details with description, comments, and project language
22
+ - **`get_project_language`** -- get configured language for a project (for AI assistants)
23
+ - **`log_task_time`** -- log work time in `"2h 30m"` format
24
+ - **`get_task_time_tracking`** -- get time tracking info (estimate, spent, remaining)
25
+ - **`list_comment_templates`** -- list available comment templates by category
26
+ - **`add_templated_comment`** -- add comment using a template with variable interpolation
27
+ - **`create_task`** -- create a new Jira issue with ADF description, assignee, labels, epic link
28
+ - **`search_tasks`** -- search Jira issues with raw JQL (no caching)
29
+
30
+ ### CLI Commands (17)
31
+
32
+ - **`jira-mcp`** / **`jira-mcp serve`** -- start MCP server (stdio transport)
33
+ - **`jira-mcp config init`** -- initialize global config at `~/.softspark/jira-mcp/`
34
+ - **`jira-mcp config add-project <key> <url>`** -- add a Jira project mapping
35
+ - **`jira-mcp config remove-project <key>`** -- remove a project
36
+ - **`jira-mcp config list-projects`** -- show configured projects with language column
37
+ - **`jira-mcp config set-credentials`** -- set API credentials
38
+ - **`jira-mcp config set-default <key>`** -- set default project
39
+ - **`jira-mcp config set-language <lang>`** -- set global default language
40
+ - **`jira-mcp config set-project-language <key> <lang>`** -- set language for a specific project
41
+ - **`jira-mcp create <path>`** -- create tasks from bulk config file (dry-run by default)
42
+ - **`jira-mcp create-monthly`** -- run monthly admin task templates
43
+ - **`jira-mcp cache sync-workflows`** -- sync workflow status transitions
44
+ - **`jira-mcp cache sync-users`** -- sync user list for reassignment
45
+ - **`jira-mcp cache list-workflows`** -- show cached workflows
46
+ - **`jira-mcp cache list-users`** -- show cached users
47
+
48
+ ### Features
49
+
50
+ - **Multi-instance routing** -- single server manages multiple Jira Cloud/Server instances. Project key determines routing. Connectors deduplicated by URL via InstancePool.
51
+ - **Language configuration** -- global `default_language` with per-project override. Supports: pl, en, de, es, fr, pt, it, nl. AI assistants check language before writing content.
52
+ - **ADF round-trip** -- bidirectional Markdown ↔ Atlassian Document Format conversion. Zero-dependency built-in parsers (~330 lines each). Literal `\n` normalization for MCP tool parameters.
53
+ - **Local caching** -- tasks synced to `~/.softspark/jira-mcp/cache/` with atomic writes. Workflow and user caches for offline status validation and assignee resolution.
54
+ - **Comment templates** -- 8 built-in templates with `{{variable}}` interpolation and `{{#var}}...{{/var}}` conditional blocks.
55
+ - **Bulk task creation** -- JSON config templates with dry-run default, rate limiting, epic link discovery, bilingual support (8 languages), idempotent updates.
56
+ - **Per-instance credentials** -- Format A (single credential) and Format B (per-URL credentials with default fallback). Backward compatible.
57
+ - **Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires. Self-contained 325KB bundle, 1 runtime dep (commander).
58
+ - **Strict TypeScript** -- `strict: true`, no `any`, `readonly` interfaces, Zod validation at all boundaries. 413 tests across 47 test files.
59
+ - **Typed error hierarchy** -- 15 error classes with machine-readable codes. Structured `{ success, error, code }` responses.
60
+
61
+ ### Architecture
62
+
63
+ Four layers -- each depends only on layers below:
64
+
65
+ 1. **Types & Config** (`config/`, `errors/`, `*/types.ts`) -- pure data, zero runtime deps
66
+ 2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`) -- I/O and external APIs
67
+ 3. **Business Logic** (`operations/`, `bulk/`) -- orchestrates infrastructure
68
+ 4. **Entry Points** (`tools/`, `cli/`, `server.ts`) -- thin dispatchers
69
+
70
+ ### AI Toolkit Integration
71
+
72
+ - **Rules file** (`rules/jira-mcp.md`) -- register with `ai-toolkit add-rule` for automatic language checks, sync-first workflow, and tool reference injection.
73
+ - **GitHub Copilot** (`.github/copilot-instructions.md`) -- full project context for Copilot-assisted development.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,261 @@
1
+ # jira-mcp
2
+
3
+ > MCP server for Jira integration -- multi-instance routing, ADF formatting, task caching, and comment templates via the Model Context Protocol.
4
+
5
+ [![CI](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml)
6
+ [![npm](https://img.shields.io/npm/v/@softspark/jira-mcp)](https://www.npmjs.com/package/@softspark/jira-mcp)
7
+ [![version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
9
+
10
+ ---
11
+
12
+ ## What's New in v1.0.0
13
+
14
+ - **15 MCP tools** -- `update_task` for editing issues, `get_project_language` for AI language awareness.
15
+ - **Language configuration** -- global `default_language` + per-project override. Supports: pl, en, de, es, fr, pt, it, nl.
16
+ - **17 CLI commands** -- `config set-default`, `config set-language`, `config set-project-language` added.
17
+ - **Zero runtime dependencies** -- built-in `fetch` client (Jira REST API v3), built-in ADF parsers. Self-contained 325KB bundle.
18
+ - **Per-instance credentials** -- different username/token per Jira instance URL (Format A + Format B).
19
+ - **Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires.
20
+ - **413 tests** across 47 test files with strict TypeScript.
21
+
22
+ See [CHANGELOG.md](CHANGELOG.md) for full details.
23
+
24
+ ---
25
+
26
+ ## Table of Contents
27
+
28
+ - [Install](#install)
29
+ - [Configuration](#configuration)
30
+ - [CLI Commands](#cli-commands)
31
+ - [Available Tools](#available-tools)
32
+ - [Comment Templates](#comment-templates)
33
+ - [Usage with Claude Code](#usage-with-claude-code)
34
+ - [Usage with Other MCP Clients](#usage-with-other-mcp-clients)
35
+ - [Architecture](#architecture)
36
+ - [Key Features](#key-features)
37
+ - [Documentation](#documentation)
38
+ - [Contributing](#contributing)
39
+ - [Security](#security)
40
+ - [License](#license)
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ npm install -g @softspark/jira-mcp
46
+ # or use directly
47
+ npx @softspark/jira-mcp
48
+ ```
49
+
50
+ ## Update
51
+
52
+ ```bash
53
+ npm update -g @softspark/jira-mcp
54
+ ```
55
+
56
+ ## Configuration
57
+
58
+ ### 1. Generate an API token
59
+
60
+ Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) and create a token.
61
+
62
+ ### 2. Initialize global config
63
+
64
+ ```bash
65
+ jira-mcp config init
66
+ jira-mcp config set-credentials
67
+ jira-mcp config add-project
68
+ ```
69
+
70
+ All configuration lives in `~/.softspark/jira-mcp/` (created by `jira-mcp config init`). This is the standard config directory for all SoftSpark open-source tools.
71
+
72
+ ## CLI Commands
73
+
74
+ | Command | Description |
75
+ |---------|-------------|
76
+ | `jira-mcp` | Start MCP server (default) |
77
+ | `jira-mcp serve` | Start MCP server (explicit) |
78
+ | `jira-mcp create <path>` | Create tasks from config file (dry-run by default) |
79
+ | `jira-mcp create-monthly` | Create monthly admin tasks from built-in templates |
80
+ | `jira-mcp config init` | Initialize global config at `~/.softspark/jira-mcp/` |
81
+ | `jira-mcp config add-project <key> <url>` | Add a Jira project to config |
82
+ | `jira-mcp config remove-project <key>` | Remove a project from config |
83
+ | `jira-mcp config list-projects` | List all configured projects with language |
84
+ | `jira-mcp config set-credentials` | Set API credentials |
85
+ | `jira-mcp config set-default <key>` | Set default project |
86
+ | `jira-mcp config set-language <lang>` | Set global default language |
87
+ | `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
88
+ | `jira-mcp cache sync-workflows` | Sync workflow status transitions |
89
+ | `jira-mcp cache sync-users` | Sync user list for reassignment |
90
+ | `jira-mcp cache list-workflows` | Show cached workflows |
91
+ | `jira-mcp cache list-users` | Show cached users |
92
+
93
+ ## Available Tools
94
+
95
+ | Tool | Description | Key Parameters |
96
+ |------|-------------|----------------|
97
+ | `sync_tasks` | Sync tasks from Jira to local cache | `project_key?`, `jql?` |
98
+ | `read_cached_tasks` | Read tasks from cache without hitting Jira | `task_key?` |
99
+ | `update_task_status` | Change task status via workflow transition | `task_key`, `status` |
100
+ | `update_task` | Update existing issue fields (markdown → ADF) | `task_key`, `summary?`, `description?`, `priority?`, `labels?` |
101
+ | `add_task_comment` | Add a markdown comment (auto-converted to ADF) | `task_key`, `comment` |
102
+ | `reassign_task` | Reassign or unassign a task | `task_key`, `assignee_email?` |
103
+ | `get_task_statuses` | Get valid workflow transitions for a task | `task_key` |
104
+ | `get_task_details` | Get full details with description, comments, and language | `task_key` |
105
+ | `get_project_language` | Get configured language for a project | `project_key` |
106
+ | `log_task_time` | Log work time (`"2h 30m"` format, no days) | `task_key`, `time_spent`, `comment?` |
107
+ | `get_task_time_tracking` | Get time tracking info (estimate, spent, remaining) | `task_key` |
108
+ | `list_comment_templates` | List available comment templates | `category?` |
109
+ | `add_templated_comment` | Add comment using a template or raw markdown | `task_key`, `template_id?`, `variables?`, `markdown?` |
110
+ | `create_task` | Create a new Jira issue with ADF description | `project_key`, `summary`, `description?`, `assignee_email?`, `labels?`, `epic_key?` |
111
+ | `search_tasks` | Search Jira issues with JQL (no caching) | `jql`, `max_results?`, `project_key?` |
112
+
113
+ ## Comment Templates
114
+
115
+ 8 built-in templates organized by category:
116
+
117
+ | Template ID | Name | Category | Required Variables |
118
+ |-------------|------|----------|--------------------|
119
+ | `status-update` | Status Update | workflow | `completed`, `next_steps` |
120
+ | `blocker-notification` | Blocker Notification | communication | `blocked_by`, `impact`, `needed_action` |
121
+ | `handoff-transition` | Task Handoff | workflow | `from_person`, `to_person`, `context`, `remaining_work` |
122
+ | `review-request` | Review Request | communication | `reviewer`, `summary`, `link` |
123
+ | `sprint-update` | Sprint Update | reporting | `progress`, `risks` |
124
+ | `bug-report` | Bug Report | development | `steps`, `expected`, `actual` |
125
+ | `deployment-note` | Deployment Note | development | `changes`, `rollback_plan` |
126
+ | `time-log-summary` | Time Log Summary | reporting | `duration`, `work_description` |
127
+
128
+ ### Using Templates
129
+
130
+ Example with Claude Code:
131
+
132
+ > "Add a status update to PROJ-123: completed auth module, next steps are testing, no blockers"
133
+
134
+ The AI will use `add_templated_comment` with `template_id: "status-update"` automatically.
135
+
136
+ ## Usage with Claude Code
137
+
138
+ Add to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json` or project-level):
139
+
140
+ ```json
141
+ {
142
+ "mcpServers": {
143
+ "jira": {
144
+ "command": "npx",
145
+ "args": ["@softspark/jira-mcp"]
146
+ }
147
+ }
148
+ }
149
+ ```
150
+
151
+ Configuration is automatically loaded from `~/.softspark/jira-mcp/`. Run `jira-mcp config init` first to set up.
152
+
153
+ ### AI Toolkit Rules
154
+
155
+ If you use `@softspark/ai-toolkit`, register the Jira rules so that Claude Code automatically follows project conventions (language checks, sync-first workflow, time format, etc.):
156
+
157
+ ```bash
158
+ ai-toolkit rules add jira-mcp --path /path/to/jira-mcp/rules/jira-mcp.md
159
+ ```
160
+
161
+ Or copy `rules/jira-mcp.md` to your ai-toolkit rules directory manually. The rules file covers:
162
+ - **Language first** -- always check project language before writing comments/descriptions
163
+ - **Sync before read** -- cache may be stale
164
+ - **Status transitions** -- check valid transitions before changing status
165
+ - **Time format** -- `"2h 30m"`, never days
166
+ - **All 15 MCP tools** and **17 CLI commands** reference
167
+
168
+ ## Usage with Other MCP Clients
169
+
170
+ Any MCP client that supports stdio transport can use this server:
171
+
172
+ ```json
173
+ {
174
+ "command": "npx",
175
+ "args": ["@softspark/jira-mcp"],
176
+ "transport": "stdio"
177
+ }
178
+ ```
179
+
180
+ Configuration is loaded from `~/.softspark/jira-mcp/` automatically. No environment variables needed.
181
+
182
+ ## Architecture
183
+
184
+ ```
185
+ src/
186
+ adf/ Atlassian Document Format conversion (MD <-> ADF)
187
+ bulk/ Bulk task creator (dry-run, rate limiting, bilingual)
188
+ cache/ Local task, workflow, and user caching (JSON files)
189
+ cli/ CLI entry point and subcommand handlers
190
+ commands/
191
+ cache/ Cache management subcommands
192
+ config/ Config management subcommands
193
+ create.ts Bulk task creation command
194
+ create-monthly.ts Monthly admin task automation
195
+ config/ Configuration loading and Zod validation
196
+ connector/ Jira API client (built-in fetch, instance pool)
197
+ errors/ Typed error hierarchy
198
+ operations/ Business logic (status, comments, time tracking)
199
+ templates/ Comment template system (registry + built-in templates)
200
+ tools/ MCP tool handlers (15 tools, one file per tool)
201
+ types/ Shared TypeScript types
202
+ server.ts MCP server setup and tool registration
203
+ cli.ts CLI entry point
204
+ ```
205
+
206
+ ## Key Features
207
+
208
+ **Multi-instance routing** -- single server manages multiple Jira Cloud/Server instances. Project key determines which instance handles the request. Connectors deduplicated by URL via [InstancePool](kb/reference/architecture.md).
209
+
210
+ **ADF round-trip** -- comments and descriptions use Atlassian Document Format natively. Markdown in, ADF to Jira v3 API, ADF back to readable markdown. Never loses formatting. See [ADF Reference](kb/reference/adf.md).
211
+
212
+ **Local caching** -- tasks synced to `~/.softspark/jira-mcp/cache/` with atomic writes (tmp + rename). Work offline with `read_cached_tasks`, sync on demand. Workflow and user caches for status validation and assignee resolution.
213
+
214
+ **Comment templates** -- 8 built-in templates with `{{variable}}` interpolation and `{{#var}}...{{/var}}` conditional blocks. Status updates, blockers, handoffs, reviews. See [Templates Reference](kb/reference/templates.md).
215
+
216
+ **Language configuration** -- global `default_language` with per-project override. Supports: pl, en, de, es, fr, pt, it, nl. `get_project_language` tool and `language` field in `get_task_details` let AI assistants write content in the correct language. See [Configuration](kb/reference/configuration.md).
217
+
218
+ **Bulk task creation** -- create tasks from JSON configs with dry-run default, rate limiting, epic link discovery, assignee caching, multilingual support (8 languages), and idempotent updates. See [CLI Usage](kb/howto/cli-usage.md).
219
+
220
+ **Per-instance credentials** -- different API tokens per Jira instance URL. Single-credential format still works (backward compatible). See [Configuration](kb/reference/configuration.md).
221
+
222
+ **Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires. Self-contained 325KB bundle, 1 runtime dep (commander).
223
+
224
+ **Typed error hierarchy** -- 15 error classes with machine-readable codes. Every tool returns structured `{ success, error, code }` responses. No stack traces leak to MCP clients.
225
+
226
+ **Strict TypeScript** -- `strict: true`, no `any`, `readonly` interfaces, Zod validation at all boundaries, 413 tests across 47 test files. Self-contained 325KB package.
227
+
228
+ ## Documentation
229
+
230
+ | Document | Description |
231
+ |----------|-------------|
232
+ | [Architecture](kb/reference/architecture.md) | System design and module overview |
233
+ | [API Reference](kb/reference/api.md) | All 15 MCP tools with schemas |
234
+ | [Configuration](kb/reference/configuration.md) | Config files, env vars, multi-instance |
235
+ | [ADF Format](kb/reference/adf.md) | Atlassian Document Format conversion |
236
+ | [Caching](kb/reference/caching.md) | Task, workflow, and user caching |
237
+ | [Templates](kb/reference/templates.md) | Comment and task templates |
238
+ | [Setup Guide](kb/howto/setup.md) | Getting started step-by-step |
239
+ | [CLI Usage](kb/howto/cli-usage.md) | Complete CLI reference |
240
+ | [Multi-Instance](kb/howto/multi-instance.md) | Multiple Jira instances |
241
+ | [Troubleshooting](kb/troubleshooting/common-issues.md) | Common issues and fixes |
242
+
243
+ ## Contributing
244
+
245
+ See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
246
+
247
+ ## Security
248
+
249
+ See [SECURITY.md](SECURITY.md).
250
+
251
+ ## License
252
+
253
+ [MIT](LICENSE) -- SoftSpark
254
+
255
+ ## Changelog
256
+
257
+ See [CHANGELOG.md](CHANGELOG.md).
258
+
259
+ ---
260
+
261
+ Built at [SoftSpark](https://softspark.eu). Designed for AI-assisted Jira workflows.