jira8_mcp: Instructions file for Claude Code

CLAUDE.md — Project Instructions

Read this file every time you start working on this project. It defines how this codebase works, coding conventions, and how to use the Jira MCP tools.

---

Project Overview

This is jira-run-mcp — a TypeScript MCP server that connects AI agents to an internal Jira 8 instance protected by corporate SSO.

Architecture: Playwright handles SSO login (one-time), persists browser cookies locally. All Jira API calls use a plain HTTP client with those cookies. The MCP server exposes tools over Streamable HTTP transport.

Stack: TypeScript (strict, ESM/NodeNext), @modelcontextprotocol/sdk, Express, Zod, Playwright, Axios, Vitest.

---

Codebase Layout

src/
├── server.ts              # MCP server entry — factory pattern, per-request McpServer
├── config.ts              # Zod-validated env config singleton
├── errors.ts              # McpError class + typed error codes
├── types.ts               # Shared types (SessionFile, JiraIssue, etc.)
├── auth/
│   ├── session-store.ts   # FS layer: read/write/clear .jira/session.json
│   ├── session-manager.ts # Session validation against Jira /rest/api/2/myself
│   └── playwright-auth.ts # Headed browser SSO flow + pre-save validation
├── jira/
│   ├── endpoints.ts       # URL builders for Jira REST API v2
│   ├── mappers.ts         # Raw Jira payloads → stable typed outputs
│   └── http-client.ts     # Cookie-auth axios client with auth-failure detection
├── tools/
│   ├── get-issue.ts       # jira_get_issue: fetch single issue by key
│   └── search-issues.ts   # jira_search_issues: JQL query → compact list
├── cli/
│   ├── auth-login.ts      # Interactive SSO login
│   ├── auth-check.ts      # Validate stored session
│   └── auth-clear.ts      # Remove stored session
└── tests/                 # Vitest unit + regression tests

---

Coding Conventions

TypeScript

• Strict mode — no any, no implicit types, no non-null assertions without justification.
• ESM only — all imports use .js extension (NodeNext resolution): import { foo } from "./bar.js".
• Zod for validation — all external inputs (env vars, tool arguments, API responses) are validated with Zod schemas.
• No classes for tools — tool handlers are pure async functions, not class methods.