jira8_mcp AGENTS.md

AGENTS.md — Agent Instructions for jira-run-mcp

This file is the canonical instruction set for any AI agent working on this project. Read this file in full before starting any task.

---

What Is This Project?

jira-run-mcp is a TypeScript MCP (Model Context Protocol) server that provides AI agents with read access to an internal Jira 8 instance. Authentication uses Playwright-based SSO session bootstrap; API calls use HTTP with stored cookies.

Architecture Rules

1. Server uses factory pattern. Each incoming MCP request gets a new McpServer + StreamableHTTPServerTransport pair. Never reuse a server instance across requests.

2. Auth is isolated from tools. Tools call loadAndValidateSession() — they never touch Playwright or browser state. Session validation must not launch a browser.

3. HTTP-first for Jira access. All Jira REST API calls go through src/jira/http-client.ts using Axios. Playwright is used only for the interactive SSO login CLI (jira-auth-login). loadAndValidateSession() never launches a browser: it tries the stored cookie session, then optional HTTP Basic Auth, then returns AUTH_REQUIRED / SESSION_EXPIRED.

4. Zod validates everything. Environment variables (src/config.ts), tool inputs (each tool's schema), and Jira responses are all validated.

Coding Standards

• TypeScript strict mode. No any. No implicit types.
• ESM with .js extensions. All imports must end in .js (NodeNext module resolution).
• Errors use McpError. Every business error must use the McpError class with a typed code. Use factory helpers from src/errors.ts.
• Tool errors set isError: true. MCP clients rely on this flag. Never return an error as normal content.
• 3xx from Jira = session expired. Always treat redirects as auth failure. validateStatus accepts only 2xx.
• Validate before saving sessions. The playwright-auth.ts module validates a candidate session against Jira before writing it to disk.
• Utility functions in src/utils.ts. Shared helpers (e.g. date formatting, string manipulation) must live in src/utils.ts, not inline in tool or handler files.
• Prefer libraries over hand-rolled code. For common tasks (date formatting, duration parsing, HTTP retry, etc.), use well-known npm packages instead of writing custom implementations. Only write a manual helper if the logic is trivially small (< 5 lines) and adding a dependency would be disproportionate.
• Raw API response types in src/types/jira-api.ts. Types that mirror the exact shape of Jira/Tempo REST API responses must live in src/types/jira-api.ts, separate from the normalized application interfaces in src/types.ts. This keeps API contracts independently trackable and supports future API documentation generation.