Jira For Agents

Jira for Agents

Prepare Jira issues, comments, and attachments as a Markdown file cache that AI agents can search, inspect, and reason over with normal developer tools.

This project was built by Alloy because the native Jira API is useful for targeted reads, but too limited for deeper agent workflows: semantic search, grep-like search, repeated exploration, local indexing, and attachment-aware context building. The exporter turns Jira project or support history into plain files so agents can work against a fast cache instead of repeatedly querying Jira.

It works especially well with Alloy Storage and Alloy search, but the output is just Markdown and files. You can use it with any agent workspace, retrieval stack, code search tool, or local indexing pipeline.

Two ways to run it:

• CLI export — pulls issues via the Jira REST API and writes them as Markdown.
• REST API server — runs the export as an asynchronous background job over HTTP.

Architecture

The exporter follows a staged pipeline, where each stage takes the typed result of the previous one:

fetch() -> transform() -> filter() -> format() -> write()

Design conventions used throughout the codebase:

• Facade / orchestrator modules — each module folder exposes a single facade function in its index.ts that only orchestrates calls to leaf functions for that pipeline stage.
• Leaf functions — pure and side-effect-free, with no logging; logging happens only in the facade.
• Direct imports, no re-exports — types and functions are imported from their source files; index.ts files are orchestrators, not barrel exports.
• Shared utilities first — common helpers (fs, http, dates, logging, CLI, arrays, parsing) live in shared/utils/ and are reused across modules instead of being reimplemented.
• Strict typing — domain and pipeline types live in types.ts; raw API response types stay local to the file that uses them.

Path aliases

Configured in tsconfig.json:

| Alias | Path | |--------------|-------------| | @shared/* | shared/ | | @jira/* | jira/ | | @server/* | server/ |

import { formatDate } from '@shared/utils/date.js'
import type { JiraConfig } from '@jira/types.js'

Project structure

jira-for-agents/
├── shared/utils/        # Shared helpers: fs, http, date, logger, cli, array, format, parse, progress, shutdown
├── jira/                # Jira export module
│   ├── index.ts         # Entry point / orchestrator
│   ├── config.ts        # CLI + env configuration
│   ├── types.ts         # Domain & pipeline types
│   ├── queries.ts       # Named JQL queries
│   ├── providers/       # REST API data fetching
│   ├── transformers/    # Cleaning & normalization
│   ├── filters/         # Business-rule filtering
│   ├── formatters/      # Date formatting
│   ├── downloaders/     # Media download (parallel, cached)
│   └── writers/         # Markdown output & incremental sync
├── server/              # REST API server (Hono)
│   ├── index.ts         # Entry point
│   ├── routes/          # HTTP endpoints (jira, jobs)
│   ├── jobs/            # Async job runner & persistent store
│   ├── validation/      # Zod request schemas
│   └── ...
├── output/              # Generated Markdown + assets
├── tsconfig.json
├── package.json
└── .env                 # Environment variables (copy from .env.example)

Setup

npm install
cp .env.example .env   # then fill in your credentials

Configuration

Options can be set via .env, passed as CLI flags, or sent in the REST API request body. See .env.example for the full, commented list.

Jira

• JIRA_BASE_URL — Jira base URL (required)
• JIRA_API_TOKEN — REST API token (required)
• JIRA_QUERY — named query from queries.ts to run by default
• JIRA_EMPLOYEE_GROUP_NAME — Jira groups used to mark internal users
• JIRA_BOT_USERNAME — bot account whose service comments are filtered out

Jira Export

Exports issues, comments and attachments to Markdown.

Commands

npm run jira                             # Incremental sync (default)
npm run jira:full                        # Full sync
npm run jira:dry                         # Show plan without writing
npm run jira:list                        # List available JQL queries
npm run jira -- --query=support2025      # Run a specific named query from queries.ts
npm run jira -- --mode=incremental       # Sync mode: incremental | full
npm run jira -- --output=monthly         # Output layout: monthly (default) | single | batch
npm run jira -- --limit=10               # Issue limit (for testing)
npm run jira -- --no-media               # Skip media download
npm run jira -- --no-sanitize            # Disable PII sanitization
npm run jira -- --no-min-comments        # Export all issues (ignore min-comments filter)
npm run jira -- --output-dir=output/dev  # Custom output directory
npm run jira -- --zip                    # Archive output to .tar.gz after export

# Flags can be combined:
npm run jira -- --query=support2025 --limit=50 --output=monthly

Pipeline

fetch() -> transform() -> filter() -> format() -> write()
RawIssue[] -> Issue[]  -> Issue[]  -> FormattedIssue[] -> files

Modules

• providers/ — fetching data from Jira
• rest.ts — REST API with pagination and parallel comment loading
• transformers/ — cleaning and normalization
• strip.ts — remove Jira/Wiki markup
• sanitize.ts — normalize whitespace/formatting and redact PII (emails, phones, IPs, credentials)
• footer.ts — remove email footers
• merge.ts — merge consecutive comments from the same author
• deduplicate.ts — remove summary/description duplicated in the first comment
• filters/ — filtering by business rules (e.g. minimum comments)
• formatters/ — ISO dates to human-readable format
• downloaders/ — media download
• index.ts — parallel download orchestration (p-limit)
• fetch.ts — single-file download
• cache.ts — caching of downloaded files
• limits.ts — size and file-type limits
• paths.ts — media path generation
• writers/ — Markdown output and sync
• single.ts / batch.ts / by-month.ts — output layout strategies
• serialize.ts — issue serialization to Markdown
• registry.ts — registry of exported issues
• last-sync.ts — last-sync timestamp management
• filter-by-registry.ts — skip unchanged issues
• cleanup.ts — remove files of deleted issues and orphaned media

Advanced: upload media to Alloy Storage

By default, media is written to the local output directory. If you use Alloy as the agent workspace, you can upload media files to Alloy Storage instead. Files are deduplicated by SHA-256 hash.

# Provide the key via CLI
npm run jira -- --upload-api --alloy-api-key=YOUR_API_KEY

# With a path prefix (target folder in storage)
npm run jira -- --upload-api --alloy-api-key=YOUR_API_KEY --alloy-upload-prefix=jira/support

# Or configure credentials in .env and just run:
npm run jira -- --upload-api

Related optional configuration:

• ALLOY_API_KEY — API key for Alloy Storage
• ALLOY_API_URL — Alloy API base URL (default: https://api.alloy.cx)
• ALLOY_UPLOAD_PREFIX — target folder prefix in storage

Data types

Defined in jira/types.ts:

• RawIssue, RawComment — raw data from the provider
• Issue, Comment, MergedComment — after transformation
• FormattedIssue, FormattedMergedComment — ready for writing
• JiraConfig — application configuration
• SyncMode — incremental | full
• JiraRegistry, JiraRegistryEntry, JiraLastSyncData — incremental-sync state
• JiraCleanupResult, FilterByRegistryResult — cleanup / filtering results

Output structure

output/jira/
├── .sync/                          # Sync metadata
│   ├── {queryName}.registry.json   # Issue registry (key -> path, updated)
│   └── {queryName}.last_sync.json  # Last sync date
├── 2025-01/                        # Grouping by month (monthly mode)
│   ├── SUPPORT-123.md
│   └── SUPPORT-456.md
└── assets/
    └── SUPPORT-123/                # Per-issue media files
        ├── image.png
        └── document.pdf

Features

• Incremental sync — loads only changed issues by default
• Registry-based tracking — tracks written files to detect changes
• Cleanup on full sync — removes files of issues deleted in Jira
• Safety buffer — 5-minute buffer when building JQL to compensate for timezone skew
• Media handling — attachment download with size and type limits
• PII sanitization — on by default, can be disabled with --no-sanitize

REST API Server

HTTP server (Hono) for running syncs as asynchronous background jobs.

Commands

npm run server                  # Start on port 3005
npm run server:dev              # Start with hot-reload
npm run server -- --port=4000   # Custom port

Endpoints

GET  /health           health check
POST /jira/sync        start a Jira sync
GET  /jobs             list all jobs
GET  /jobs/:id         job status
POST /jobs/:id/cancel  cancel a job

Request examples

# Jira sync (incremental by default)
curl -X POST http://localhost:3005/jira/sync \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://your-domain.atlassian.net",
    "apiToken": "",
    "outputDir": "/tmp/jira",
    "employeeGroupName": "users",
    "jql": "project = SUP"
  }'

# Jira sync (full mode)
curl -X POST http://localhost:3005/jira/sync \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://your-domain.atlassian.net",
    "apiToken": "",
    "outputDir": "/tmp/jira",
    "jql": "project = SUP",
    "mode": "full"
  }'

# Check job status
curl http://localhost:3005/jobs/{jobId}

Features

• Async execution — sync runs in the background and returns a jobId
• Graceful shutdown — job state is saved on SIGINT/SIGTERM
• Persistent store — jobs are saved to disk
• Request logging — colored output with timing
• Secret masking — tokens and keys are redacted in logs

Development

npm run lint        # ESLint check
npm run lint:fix    # Auto-fix

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Alloy-Systems
• Source: Alloy-Systems/jira-for-agents
• License: Apache-2.0
• Homepage: https://alloy.cx

Install and usage instructions live in the source repository linked above.