jira-mcp: Instructions file for Claude Code

jira-mcp

Overview

Stdio MCP server (@softspark/jira-mcp) that lets AI agents and MCP clients (Claude Code, Cursor) drive Jira across multiple instances: sync, read, search, comment, transition status, log time, reassign, create, and delete tasks, with markdown to ADF conversion and a local task cache.

Tech Stack

• Language: TypeScript, strict mode, ESM, Node >= 18. No any, import type for types, .js import specifiers, moduleResolution: bundler.
• Framework: @modelcontextprotocol/sdk (server) and commander (CLI). Zod for schema validation, tsup for build, Vitest for tests, ESLint for lint.
• Database: none. Config, credentials, cache, and templates are JSON files under ~/.softspark/jira-mcp/. The Jira REST API is the system of record; the cache is a local read mirror.

Commands

npm run dev          # run the CLI from source (tsx src/cli.ts)
npm test             # vitest run     (test:coverage for the 70% gate, test:watch to iterate)
npm run lint         # eslint src/ tests/   (lint:fix to autofix)
npm run typecheck    # tsc --noEmit
npm run build        # tsup, flat-bundles src into dist/
# pre-commit gate:
npm run typecheck && npm run lint && npm test && npm run build

Key Conventions

Only the non-obvious rules live here. Full agent rules in rules/jira-mcp.md and AGENTS.md; deep docs in kb/.

• Fixed config path: everything persistent is under ~/.softspark/jira-mcp/ via GLOBAL_CONFIG_DIR (src/config/paths.ts). No env vars and no manual paths in MCP client setup.
• Project key routes the instance: the Jira project key selects which instance and credentials are used (multi-instance map in config.json). One key maps to exactly one instance.
• Language first: call get_project_language(projectKey) (or read language from get_task_details) before writing any comment, description, or task. Write content in the project's configured language. Never assume Polish or English.
• ADF round-trip never throws: markdownToAdf() on writes, adfToMarkdown() on reads. Malformed input degrades gracefully instead of raising.
• Dual-write: after a Jira mutation, update the local cache, then return the API result.
• Guarded destructive ops: dry-run is the default and the CLI needs --execute. delete_task (creator only) and delete_comment (author only) also require user_approved=true.
• Time format: "2h 30m", hours and minutes only, never days.
• Status transitions: call get_task_statuses first; only the offered transitions are valid for that issue.
• Supply-chain hygiene: commander is the only runtime dependency; everything else (Zod included) is bundled into dist/ by tsup. No install scripts (ignore-scripts).
• Layered, deps point down only: types/config, then infrastructure (connector, cache, adf, templates), then business logic (operations, bulk), then entry points (tools, cli, server.ts).
• DI for tests: handlers take an optional deps parameter so tests inject fakes (tests/fixtures/mocks.ts). Tests never hit real Jira and never write to ~/.softspark/.
• Prose style for generated content: plain, workmanlike tone, no em dash and no -- separator in comments, descriptions, or docs.