jc-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

jc-mcp (@maphnet/jc-mcp) is a Jira and Confluence MCP (Model Context Protocol) server focused on optimizing token efficiency for everyday tasks. Unlike general-purpose Atlassian MCP servers, this server is designed to return concise, structured responses that minimize token consumption while preserving the information LLM agents actually need.

Development Commands

npm install          # Install dependencies
npm run build        # Compile TypeScript to dist/
npm start            # Run the compiled server (stdio transport)
npm run dev          # Run with auto-reload (tsx watch)
npm test             # Run tests once (vitest)
npm run test:watch   # Run tests in watch mode
npx tsc --noEmit     # Type-check without emitting

Publishing to npm

npm version patch        # bump version (patch / minor / major)
npm run build            # compile TypeScript
npm publish --access public   # publish @maphnet/jc-mcp (scoped → needs flag)
git push && git push --tags   # push version commit + tag created by npm version

npm version also syncs server.json automatically (via the version script). The server's reported version is read from package.json at runtime; never hard-code it.

Requires npm login if not already authenticated.

Architecture

The server uses @modelcontextprotocol/sdk with stdio transport. Tool implementations live in src/tools/, each exporting a register(server, client) function and a testable handle* function. Transport is stdio by default; JCM_TRANSPORT=http serves MCP Streamable HTTP from src/http-transport.ts (one McpServer per client session, one shared AtlassianClient).

src/
├── index.ts              # Entry: loadConfig → stdio (default) or HTTP (JCM_TRANSPORT=http) + signal handling
├── server.ts             # createServer(client): McpServer — registers all tools (one per stdio process / HTTP session)
├── http-transport.ts     # Streamable HTTP: session map, Host check, idle sweep, close() handle
├── config.ts             # Env var loading (ATLASSIAN_URL, EMAIL, TOKEN, CLOUD_ID)
├── elicitation.ts        # Write-confirmation gate (JCM_CONFIRM_WRITES env flag + MCP elicitation)
├── client.ts             # HTTP client for Jira/Confluence REST APIs (Basic auth)
├── adf-to-markdown.ts    # ADF + Confluence storage format → markdown converter
├── markdown-to-adf.ts        # Markdown → ADF (Jira) & XHTML storage (Confluence) converter
├── types.ts              # Lean response type definitions
├── lean-parent.ts        # toLeanParent: Jira parent → {key, summary, type} | null (shared by getIssue/getIssues/searchIssues)
└── tools/                # One file per MCP tool (25 tools total)
    ├── get-issue.ts      # Priority 1: Jira issue read (flattened, ADF→markdown, incl. parent)
    ├── get-issues.ts     # Batch read ≤50 keys via one JQL search plus one fallback GET per omitted key: request order, {key, error} for keys that stay missing, `movedTo` for moved keys, capped description/last 3 comments + truncation marker
    ├── get-issue-changelog.ts # Field-change history, oldest first, `since` filter + paging ({entries, truncated})
    ├── get-attachment-download-link.ts # On-demand temporary Jira attachment URL (no file bytes)
    ├── get-transitions.ts# Priority 1: Workflow transitions ([{id, name}])
    ├── edit-issue.ts     # Priority 1: Issue field update + incremental `update` ops ({ok, key})
    ├── transition-issue.ts# Priority 1: Workflow state change
    ├── convert-issue-type.ts # Priority 1: Issue type conversion via async bulk move API + queue poll ({ok, keys, issueType, parentKey})
    ├── add-to-active-sprint.ts # Priority 2: Add issue to active scrum sprint via Agile API ({ok, key, sprintId, sprintName, boardId} | skipped | candidates)
    ├── create-issue.ts   # Priority 2: Issue creation ({key, url})
    ├── add-comment.ts    # Priority 2: Comment (markdown → ADF)
    ├── search-issues.ts  # Priority 2: JQL search (lean results incl. type + parent; zero results → jql/parse, invalid JQL throws)
    ├── get-current-user.ts # User info: authenticated user ({accountId, displayName, email, active})
    ├── lookup-user.ts    # User lookup: find user by email ([{accountId, displayName, email, active}])
    ├── create-version.ts # Version management: create release ({id, name})
    ├── list-versions.ts  # Version management: list releases ([{id, name, released, releaseDate}])
    ├── release-version.ts# Version management: mark released ({ok, id, name})
    ├── add-issue-link.ts # Issue links: create link, issueKey is source/outward (A blocks B) ({ok, issueKey, targetKey, linkType})
    ├── remove-issue-link.ts # Issue links: delete link ({ok, linkId})
    ├── get-issue-links.ts# Issue links: list links ([{id, type, inwardIssue?, outwardIssue?}])
    ├── get-article.ts    # Priority 3: Confluence page read
    ├── lookup-space.ts   # Priority 3: Confluence space key → numeric ID ({id, key, name})
    ├── create-article.ts # Priority 3: Confluence page creation
    ├── update-article.ts # Priority 3: Confluence page update
    └── search-articles.ts# Priority 3: Confluence CQL search