Jira Data Center MCP Server

Model Context Protocol (MCP) server for Atlassian Jira Data Center with semantic search and AI-powered workflow automation.

Transform natural language queries into precise Jira API operations. Built for LLMs (Claude, GPT-4, and other MCP-compatible clients) to interact intelligently with Jira Data Center through production-ready semantic search and operation execution.

Why This Exists

Working with Jira's REST API requires knowing exact endpoint names, HTTP methods, and complex JSON schemas. This MCP server solves that problem:

• Semantic Search: Ask "create an issue" → get ranked Jira operations with >90% relevance
• Zero-Config Setup: Interactive 5-minute wizard handles authentication, credentials, and database setup
• Production-Ready: Circuit breakers, rate limiting, retry logic, and secure credential storage (OS keychains)
• Multi-Auth Support: OAuth 2.0, Personal Access Tokens, OAuth 1.0a, or Basic Auth
• Security-First: Automatic data sanitization in logs, sensitive information redaction, and structured logging

Perfect for teams building AI assistants, automation workflows, or LLM integrations with Jira Data Center.

Table of Contents

• Key Features
• Quick Start
  • Docker (Recommended)
  • npm Install
  • From Source
• Usage
  • MCP Tools
  • Common Workflows
• Installation
• Configuration
• MCP Client Configuration
• Project Structure
• Documentation
• Development
• Contributing
• License
• Contributors

Key Features

✅ Semantic Search Engine - Find Jira operations using natural language with >90% relevance (sqlite-vec embeddings)
✅ Three MCP Tools - search_ids, get_id, call_id for discovery, inspection, and execution
✅ Multi-Authentication - OAuth 2.0, Personal Access Tokens, OAuth 1.0a, Basic Auth with secure OS keychain storage
✅ Production Resilience - Circuit breaker pattern, rate limiting, exponential backoff, automatic retries
✅ Zero-Config Setup - Interactive CLI wizard completes full setup in <5 minutes
✅ Structured Logging - JSON logs with correlation IDs, automatic credential redaction, ELK/Datadog ready
✅ Air-Gapped Support - Local embeddings generation, no external API dependencies
✅ Cross-Platform - Linux, macOS, Windows with Node.js 22+

Quick Start

Get up and running in under 5 minutes using Docker, npm, or source installation.

Docker (Recommended)

Fastest path - One command to start the MCP server:

# Pull and run the official image
docker run -it \
  -e JIRA_URL=https://jira.example.com \
  -e JIRA_AUTH_METHOD=pat \
  -e JIRA_TOKEN=your-personal-access-token \
  ghcr.io/guercheLE/jira-dc-mcp:latest

Or use docker-compose for persistent configuration:

# Clone the repo
git clone https://github.com/guercheLE/jira-dc-mcp.git
cd jira-datacenter-mcp-server

# Configure environment variables in docker-compose.yml
# Start the server
docker-compose up -d

Expected Output:

✅ MCP Server started successfully
🔍 Semantic search ready (500+ Jira operations indexed)
🔐 Authentication configured: Personal Access Token
📡 Listening on stdio transport

Troubleshooting: If you see connection errors, verify your JIRA_URL and credentials. See Docker Guide for advanced configuration.

npm Install

Recommended for local development - Global CLI with interactive setup:

# Install globally
npm install -g jira-dc-mcp

# Run setup wizard (interactive prompts)
jira-dc-mcp setup

# Start the MCP server
jira-dc-mcp start

The setup wizard will:

1. Ask for your Jira URL (e.g., https://jira.example.com)
2. Select authentication method (OAuth 2.0, PAT, OAuth 1.0a, Basic)
3. Securely store credentials in OS keychain
4. Download OpenAPI spec and generate embeddings database
5. Validate connection with health check

Expected Output:

🚀 Jira MCP Server Setup Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Jira URL configured: https://jira.example.com
✓ Authentication method: Personal Access Token
✓ Credentials stored securely in system keychain
✓ OpenAPI spec downloaded (500 operations)
✓ Embeddings database generated (768-dim vectors)
✓ Connection validated

Setup complete! Start the server with: jira-dc-mcp start

Troubleshooting: See Setup Issues for common problems.

From Source

For contributors and developers - Build from source:

# Clone repository
git clone https://github.com/guercheLE/jira-dc-mcp.git
cd jira-datacenter-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run setup wizard
npm run setup

# Start the server
npm start

Expected Output: Same as npm install method above.

What's Next?

• Test the connection: Run jira-dc-mcp test-connection to verify connectivity and authentication
• Search for operations: Run jira-dc-mcp search "create issue" to test semantic search
• Get operation details: Run jira-dc-mcp get <operationId> to view operation schema and parameters
• Start the server: Run jira-dc-mcp start to launch the MCP server
• Configure MCP client: Follow MCP Client Configuration to connect Claude Desktop, Cline, or other clients
• Explore MCP tools: See Usage Examples below
• Configure advanced features: Check Configuration Guide

CLI Commands

The jira-dc-mcp CLI provides several commands for setup, testing, and running the MCP server:

Available Commands

| Command | Description | Example | |---------|-------------|---------| | setup | Run interactive setup wizard | jira-dc-mcp setup | | start | Start the MCP server (stdio mode) | jira-dc-mcp start | | test-connection | Test Jira connectivity and authentication | jira-dc-mcp test-connection | | search <query> | Search for operations using semantic search | jira-dc-mcp search "create issue" | | get <operationId> | Get detailed info about a specific operation | jira-dc-mcp get createIssue | | call <operationId> | Execute a Jira operation | jira-dc-mcp call createIssue --param ... | | config <action> | Manage configuration (show, validate, path, reset) | jira-dc-mcp config show | | version | Show version information | jira-dc-mcp version |

Command Details

jira-dc-mcp setup

Run the interactive setup wizard to configure your Jira instance and credentials.

Options:

• --force - Overwrite existing config
• --non-interactive - Use environment variables and defaults

Example:

jira-dc-mcp setup

jira-dc-mcp start

Start the MCP server in stdio mode for use with MCP clients.

Example:

jira-dc-mcp start

Note: This is typically called by your MCP client (Claude Desktop, Cline, etc.) via the client's configuration file.

jira-dc-mcp test-connection

Verify connectivity and authentication to your Jira Data Center instance.

Example:

jira-dc-mcp test-connection

jira-dc-mcp search <query>

Search for Jira operations using natural language queries.

Options:

• --limit <n> - Maximum number of results (default: 5)
• --json - Output results as JSON
• --verbose - Show similarity scores

Example:

jira-dc-mcp search "create issue" --limit 3 --verbose

jira-dc-mcp get <operationId>

Get detailed information about a specific Jira operation including schema, parameters, and examples.

Options:

• --json - Output results as JSON
• --verbose - Show detailed schema and examples

Example:

jira-dc-mcp get createIssue --verbose

Use case: After using search to find operations, use get to inspect the operation's schema before calling it.

jira-dc-mcp call <operationId>

Execute a Jira operation with specified parameters.

Options:

• --param <key=value> - Operation parameters (can be repeated)
• --json - Output raw JSON response
• --dry-run - Validate parameters only, do not execute

Example:

jira-dc-mcp call createIssue \
  --param projectKey=TEST \
  --param summary="New bug report" \
  --param issueType=Bug

jira-dc-mcp config <action>

Manage configuration settings.

Actions:

• show - Display current configuration
• validate - Validate configuration file
• path - Show config file path
• reset - Reset configuration to defaults

Example:

jira-dc-mcp config show
jira-dc-mcp config validate

jira-dc-mcp version

Show version information for the MCP server.

Options:

• --check-updates - Check for available updates

Example:

jira-dc-mcp version --check-updates

Database Regeneration

If you encounter issues with the embeddings database (corrupted data, outdated operations, or compatibility issues), you can regenerate it completely:

Quick Regeneration

# Complete database regeneration (recommended)
cd jira-dc-mcp
rm -f data/embeddings.db* && npm run build:all

Step-by-Step Regeneration

# 1. Remove existing database and auxiliary files
rm data/embeddings.db
rm data/embeddings.db-wal 2>/dev/null || true
rm data/embeddings.db-shm 2>/dev/null || true

# 2. Regenerate from scratch
npm run download-openapi
npm run generate-schemas
npm run generate-embeddings  
npm run populate-db

# 3. Compile the project
npm run build

When to Regenerate

• Outdated data: Database contains operations from old versions with incompatible IDs
• Data contamination: Database contains operations from other MCP servers
• Corruption: Database is corrupted or inaccessible
• API updates: OpenAPI specification has been updated
• Server migration: Switching between different server types

Verification

# Check database was created successfully
ls -lh data/embeddings.db

# Validate database integrity
npm run validate-embeddings

Estimated time:

• MacBook Air M1: ~3 minutes
• GitHub Actions: ~3 hours (not recommended for CI/CD)
• Modern hardware: 3-5 minutes

For detailed troubleshooting, see docs/EMBEDDINGS_REGENERATION.md.

Usage

The MCP server provides both CLI commands for direct interaction and MCP tools for integration with LLM clients.

CLI Commands

The jira-dc-mcp CLI provides several commands for setup, testing, and operation:

Core Commands

# Setup wizard - Interactive configuration
jira-dc-mcp setup

# Start the MCP server in stdio mode
jira-dc-mcp start

# Test connection and authentication
jira-dc-mcp test-connection

# Display version information
jira-dc-mcp version [--check-updates]

Operation Discovery Commands

# Search for operations using semantic search
jira-dc-mcp search "create issue" [--limit 5] [--json] [--verbose]

# Get detailed information about a specific operation
jira-dc-mcp get <operationId> [--json] [--verbose]

# Execute a Jira operation
jira-dc-mcp call <operationId> [--param key=value] [--json] [--dry-run]

Configuration Commands

# Show current configuration
jira-dc-mcp config show

# Validate configuration file
jira-dc-mcp config validate

# Show configuration file path
jira-dc-mcp config path

# Reset configuration to defaults
jira-dc-mcp config reset

Examples

# Search for issue creation operations
jira-dc-mcp search "create issue" --limit 3

# Get detailed schema for createIssue operation
jira-dc-mcp get createIssue --verbose

# Execute an operation (dry-run mode)
jira-dc-mcp call createIssue --param projectKey=TEST --dry-run

# Check for updates
jira-dc-mcp version --check-updates

For comprehensive CLI usage, run: jira-dc-mcp --help

MCP Tools

The MCP server exposes three tools for interacting with Jira Data Center. Use these tools from any MCP client (Claude Desktop, custom LLM applications, etc.).

1. search_ids - Semantic Search for Operations

Find relevant Jira API operations using natural language queries.

Input:

• query (string, required): Natural language description (e.g., "create issue", "update assignee")
• limit (number, optional): Maximum results to return (1-20, default: 5)

Output:

• operations (array): Ranked list of matching operations with:
  • operation_id: Jira API operation identifier
  • summary: Human-readable description
  • similarity_score: Relevance score (0.0-1.0, higher is better)

Example:

{
  "tool": "search_ids",
  "input": {
    "query": "create an issue",
    "limit": 3
  }
}

Response:

{
  "operations": [
    {
      "operation_id": "createIssue",
      "summary": "Create issue in Jira",
      "similarity_score": 0.94
    },
    {
      "operation_id": "createIssues",
      "summary": "Create multiple issues (bulk)",
      "similarity_score": 0.89
    },
    {
      "operation_id": "createIssueLink",
      "summary": "Create link between two issues",
      "similarity_score": 0.82
    }
  ]
}

2. get_id - Retrieve Operation Details

Get complete schema, documentation, and examples for a specific Jira operation.

Input:

• operation_id (string, required): Jira operation ID (from search_ids results)

Output:

• operation_id: Operation identifier
• summary: Brief description
• description: Detailed documentation
• method: HTTP method (GET, POST, PUT, DELETE)
• path: API endpoint path
• parameters: Request parameters schema (path, query, body)
• responses: Response schemas by status code
• examples: Request/response examples (if available)

Example:

{
  "tool": "get_id",
  "input": {
    "operation_id": "createIssue"
  }
}

Response:

{
  "operation_id": "createIssue",
  "summary": "Create issue",
  "method": "POST",
  "path": "/rest/api/3/issue",
  "parameters": {
    "body": {
      "type": "object",
      "required": ["fields"],
      "properties": {
        "fields": {
          "project": { "type": "object" },
          "summary": { "type": "string" },
          "issuetype": { "type": "object" }
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Returned if the request is successful",
      "content": {
        "id": "10000",
        "key": "PROJ-123",
        "self": "https://jira.example.com/rest/api/3/issue/10000"
      }
    }
  }
}

3. call_id - Execute Jira Operation

Execute a Jira API operation with validated parameters and error handling.

Input:

• operation_id (string, required): Jira operation ID
• parameters (object, required): Operation parameters matching the schema from get_id
  • path: Path parameters (e.g., { "issueIdOrKey": "PROJ-123" })
  • query: Query parameters (e.g., { "fields": "summary,status" })
  • body: Request body for POST/PUT operations

Output:

• API response from Jira (varies by operation)

Example - Create Issue:

{
  "tool": "call_id",
  "input": {
    "operation_id": "createIssue",
    "parameters": {
      "body": {
        "fields": {
          "project": { "key": "PROJ" },
          "summary": "Bug: Login page not loading",
          "issuetype": { "name": "Bug" },
          "priority": { "name": "High" }
        }
      }
    }
  }
}

Response:

{
  "id": "10042",
  "key": "PROJ-123",
  "self": "https://jira.example.com/rest/api/3/issue/10042"
}

Example - Get Issue:

{
  "tool": "call_id",
  "input": {
    "operation_id": "getIssue",
    "parameters": {
      "path": { "issueIdOrKey": "PROJ-123" },
      "query": { "fields": "summary,status,assignee" }
    }
  }
}

Common Workflows

Workflow 1: Find and Create an Issue

1. search_ids({ query: "create issue" })
   → Returns: operation_id = "createIssue"

2. get_id({ operation_id: "createIssue" })
   → Returns: Full schema with required fields

3. call_id({
     operation_id: "createIssue",
     parameters: { body: { fields: { ... } } }
   })
   → Returns: Created issue with key PROJ-123

Workflow 2: Update Issue Assignee

1. search_ids({ query: "assign issue to user" })
   → Returns: operation_id = "assignIssue"

2. get_id({ operation_id: "assignIssue" })
   → Returns: Schema showing accountId parameter required

3. call_id({
     operation_id: "assignIssue",
     parameters: {
       path: { issueIdOrKey: "PROJ-123" },
       body: { accountId: "5b10a2..." }
     }
   })
   → Returns: 204 No Content (success)

Workflow 3: Bulk Operations Discovery

1. search_ids({ query: "bulk edit issues", limit: 10 })
   → Returns: Multiple bulk operations ranked by relevance

2. get_id({ operation_id: "bulkEditIssues" })
   → Returns: Schema for bulk edit payload

3. call_id({ ... })
   → Execute bulk operation

See Cookbook for 20+ practical examples and advanced patterns.

Installation

Prerequisites

• Node.js 22+ (LTS recommended) - Download
• npm 9+ (included with Node.js)
• Jira Data Center instance with API access
• Valid credentials: OAuth 2.0, Personal Access Token, OAuth 1.0a, or Basic Auth

Installation Methods

Choose the installation method that fits your workflow:

| Method | Best For | Time | Difficulty | |--------|----------|------|------------| | Docker | Production deployments, containerized environments | 2 min | Easy ⭐ | | npm Global | Local development, CLI usage | 5 min | Easy ⭐ | | From Source | Contributors, custom builds | 10 min | Moderate ⭐⭐ |

Detailed instructions: See Quick Start section above.

Configuration

The server supports four configuration methods (priority order):

1. CLI Flags (highest priority)
2. Environment Variables
3. Config File (~/.jira-dc-mcp/config.yml)
4. Defaults

Environment Variables

# Required
JIRA_URL=https://jira.example.com              # Jira Data Center URL
JIRA_AUTH_METHOD=pat                            # Auth method: oauth2, pat, oauth1, basic
JIRA_TOKEN=your-token                           # Token (for PAT/Basic)

# Optional - API Configuration
JIRA_API_VERSION=3                              # API version: 2 (Jira 8.x), 3 (Jira 9.x+)
                                                # Auto-detected during setup

# Optional - Performance
RATE_LIMIT_MAX_REQUESTS=100                     # Max requests per minute
REQUEST_TIMEOUT_MS=30000                        # Request timeout (milliseconds)
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5             # Failures before circuit opens

# Optional - Logging
LOG_LEVEL=INFO                                  # DEBUG, INFO, WARN, ERROR
LOG_OUTPUT=stdout                               # stdout, file, both
LOG_FILE_PATH=./logs/jira-dc-mcp.log              # Log file location

Config File Example

Create ~/.jira-dc-mcp/config.yml:

jira:
  url: https://jira.example.com
  auth_method: oauth2
  api_version: "3"  # Auto-detected during setup (2 for Jira 8.x, 3 for Jira 9.x+)
  
performance:
  rate_limit: 100
  timeout: 30000
  retry_max_attempts: 3
  
logging:
  level: INFO
  output: stdout
  
circuit_breaker:
  failure_threshold: 5
  timeout: 30000

Run setup wizard to generate config automatically: jira-dc-mcp setup

Full configuration reference: See Configuration Guide

API Version Detection

The server automatically detects which REST API version your Jira instance supports during setup:

• API v2: Jira Server/Data Center 8.x and older
• API v3: Jira Server/Data Center 9.x and newer

The detected version is saved to your configuration and used automatically for all API calls. You can override it using the JIRA_API_VERSION environment variable if needed.

For detailed information, see:

• API Version Detection Guide - Complete guide on API version detection
• API Version FAQ - Frequently asked questions

MCP Client Configuration

Configure the Jira MCP server in your MCP-compatible client (Claude Desktop, Cline, etc.).

Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "jira-datacenter": {
      "command": "npx",
      "args": [
        "-y",
        "jira-dc-mcp@latest",
        "start"
      ],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_AUTH_METHOD": "pat",
        "JIRA_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Option 2: Using Local Installation

{
  "mcpServers": {
    "jira-datacenter": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/jira-dc-mcp/dist/index.js"
      ],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_AUTH_METHOD": "pat",
        "JIRA_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Option 3: Using Source (Development)

{
  "mcpServers": {
    "jira-datacenter-local": {
      "command": "node",
      "args": [
        "/path/to/jira-dc-mcp/dist/index.js"
      ],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_AUTH_METHOD": "pat",
        "JIRA_TOKEN": "your-personal-access-token",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Cline (VS Code Extension)

Add to Cline's MCP settings:

{
  "mcpServers": {
    "jira-datacenter": {
      "command": "npx",
      "args": ["-y", "jira-dc-mcp@latest", "start"],
      "env": {
        "JIRA_URL": "https://jira.example.com",
        "JIRA_AUTH_METHOD": "pat",
        "JIRA_TOKEN": "your-token"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, use the stdio transport:

Command: npx -y jira-dc-mcp@latest start
Transport: stdio
Environment Variables:

• JIRA_URL - Your Jira Data Center URL
• JIRA_AUTH_METHOD - Authentication method (pat, oauth2, oauth1, basic)
• JIRA_TOKEN - Your authentication token
• LOG_LEVEL - Optional: DEBUG, INFO, WARN, ERROR

Verifying Configuration

After configuring your MCP client:

1. Restart the client (Claude Desktop, Cline, etc.)
2. Check for errors in the client's MCP server logs
3. Test the connection by asking: "Search for Jira operations to create an issue"
4. Verify tools appear in the client's available tools list:
   • search_ids - Semantic search for Jira operations
   • get_id - Get operation details and schema
   • call_id - Execute Jira API operations

Troubleshooting MCP Client Issues

Server not appearing in client:

• Verify JSON syntax is valid (no trailing commas, proper quotes)
• Check file path in configuration is correct
• Restart the MCP client completely

Connection errors:

• Verify JIRA_URL is accessible from your machine
• Check JIRA_TOKEN is valid and not expired
• Review MCP server logs: Set LOG_LEVEL=DEBUG for detailed output

Tools not working:

• Ensure embeddings database exists: Run npm run populate-db if needed
• Check permissions: Token must have READ and WRITE scopes
• Verify operation IDs are valid: Use search_ids to find correct IDs

Full troubleshooting guide: See Troubleshooting

Project Structure

jira-dc-mcp/
├── .github/workflows/    # GitHub Actions CI/CD workflows
├── src/                  # Source code (TypeScript)
│   ├── auth/            # Authentication strategies
│   ├── core/            # Core services (config, logger, errors)
│   ├── services/        # Business logic (semantic search, operations)
│   ├── tools/           # MCP tool implementations
│   └── cli/             # CLI utilities (setup wizard, search test)
├── tests/                # Test suites (unit, integration, e2e)
├── scripts/              # Build and automation scripts
├── docs/                 # Project documentation
├── data/                 # Generated data artifacts (gitignored)
└── dist/                 # Compiled output (generated)

Documentation

Comprehensive guides and references:

| Resource | Description | |----------|-------------| | Architecture Overview | System design, components, data flow | | Authentication Guide | OAuth 2.0, PAT, OAuth 1.0a setup and troubleshooting | | API Version Detection | API version detection and configuration guide | | API Version FAQ | Frequently asked questions about API versions | | Cookbook | 20+ practical examples and code snippets | | Docker Deployment | Container setup, environment variables, docker-compose | | Troubleshooting Guide | Common issues and solutions | | API Reference | Complete MCP tools specification | | Testing Strategy | Unit, integration, E2E test patterns | | Observability | Logging, monitoring, alerting setup |

Getting Help

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Request a feature
• ❓ Questions: Discussions
• 📧 Email: Open a GitHub issue for fastest response

Development

Development Commands

npm run build          # Compile TypeScript to dist/
npm run dev            # Watch mode compilation
npm run test           # Execute Vitest test suite
npm run test:benchmark  # Run semantic search relevance benchmark suite
npm run test:coverage  # Generate coverage reports
npm run lint           # Run ESLint checks on src/
npm run format         # Apply Prettier formatting
npm run format:check   # Verify formatting without making changes

CLI Commands (Post-Build)

After building, you can test CLI commands locally:

npm run setup          # Run setup wizard
npm run start          # Start MCP server
node dist/cli.js search "create issue"  # Test search command
node dist/cli.js get createIssue        # Test get command
node dist/cli.js test-connection        # Test connection

OpenAPI Spec Processing

Download and process the Jira Data Center OpenAPI specification:

npm run download-openapi                       # Download from default Atlassian URL
npm run download-openapi -- --url <url>        # Download from a custom URL
npm run download-openapi -- --local <path>     # Load a locally stored spec file

Outputs: data/operations.json and data/schemas.json with metadata.

Semantic Search CLI

Use the interactive CLI to validate semantic search behaviour without running the full benchmark suite:

npm run search "create issue"              # Default settings (limit 5, threshold 0)
npm run search "update assignee" -- --limit 3
npm run search "bulk update" -- --threshold 0.85 --verbose
npm run search "create project" -- --benchmark
npm run search -- --batch queries.txt --limit 8 --benchmark

Key flags:

• --limit <n> limits the maximum number of rows returned (1–100).
• --threshold <score> filters out low-similarity matches (0.0–1.0).
• --verbose adds the full operation description column.
• --benchmark compares the results against precision targets from the benchmark suite and prints Precision@5.
• --batch <file> executes multiple queries listed one per line, skipping blank lines automatically.

Score colours highlight relevance: green ✅ for ≥0.85, yellow ⚠️ for 0.70–0.84, and red ❌ below 0.70. Example output:

Query: create issue
┌──────┬────────────────────────────────────────┬────────────────────────────────────────┬────────────────┐
│ Rank │ Operation ID                           │ Summary                                │ Score          │
├──────┼────────────────────────────────────────┼────────────────────────────────────────┼────────────────┤
│ 1    │ create_reciprocal_remote_issue_link     │ Summary for create issue 1             │ 0.95 ✅         │
│ 2    │ create_issue_link_type                  │ Summary for create issue 2             │ 0.90 ✅         │
└──────┴────────────────────────────────────────┴────────────────────────────────────────┴────────────────┘
Found 5 result(s) matching "create issue" (limit 5, threshold 0.00)
✅ Precision@5: 100.0% (required 85.0%)

Troubleshooting:

• Database not found. Run "npm run populate-db" first. → Seed the embeddings database with npm run populate-db.
• sqlite-vec extension is required to query the embeddings database. → Ensure the extension is installed and accessible to your SQLite build.

Contributing

We welcome contributions! Here's how to get started:

See our full guidelines in CONTRIBUTING.md and please follow our Code of Conduct.

When opening an issue or pull request:

• Use the issue templates for bugs, features, and questions
• Follow the PR template and checklist

Quick Start

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes following Coding Standards
4. Test your changes: npm test (must pass)
5. Lint your code: npm run lint && npm run format:check
6. Commit with conventional commits: feat: add feature or fix: resolve bug
7. Push and open a Pull Request

Development Setup

git clone https://github.com/YOUR_USERNAME/jira-datacenter-mcp-server.git
cd jira-datacenter-mcp-server
npm install
npm run build
npm test

Coding Standards

• ✅ TypeScript strict mode - No any without justification
• ✅ Test coverage ≥80% - All features require tests
• ✅ Conventional commits - Semantic commit messages
• ✅ ESLint + Prettier - Run before committing
• ❌ No console.log - Use Logger (pino)

Full guide: Coding Standards

Testing Requirements

The project has a comprehensive test suite organized into different categories:

Test Types:

• Unit Tests (tests/unit/) - Fast, isolated tests (run by default)
• Integration Tests (tests/integration/) - Service interactions (opt-in)
• E2E Tests (tests/e2e/) - Full MCP protocol flows (opt-in)
• Benchmarks (tests/benchmarks/) - Maintain >85% search precision

Running Tests:

# Unit tests only (default, fast)
npm test

# Unit tests (explicit)
npm run test:unit

# Integration tests (requires Docker for some tests)
npm run test:integration

# E2E tests (requires configured environment)
npm run test:e2e

# All tests (unit + integration + e2e)
npm run test:all

# With coverage
npm run test:coverage

Environment Variables:

• RUN_INTEGRATION_TESTS=true - Enable integration tests
• RUN_E2E_TESTS=true - Enable E2E tests
• E2E_USE_REAL_JIRA=true - Use real Jira instance for E2E

For detailed testing documentation, see tests/README.md

License

LGPL-3.0 License - see LICENSE for details.

✅ Commercial use, modification, distribution, private use, patent use
❌ No liability, no warranty
⚠️ License and copyright notice required, disclose source, state changes
📋 Must keep same license for library, but applications using it can use different licenses

Contributors

Thanks to all our contributors! ✨

• Read our Contributing Guide and follow our Code of Conduct
• See everyone who has contributed on the GitHub contributors page

Acknowledgments

Built with excellent open-source tools:

• @modelcontextprotocol/sdk - MCP implementation by Anthropic
• sqlite-vec - Vector search for SQLite
• @xenova/transformers - Local embeddings
• Zod - TypeScript schema validation
• pino - High-performance JSON logger
• Vitest - Testing framework

Special thanks to the Jira Data Center team for comprehensive API documentation.

Security

Secure Credential Storage

Credentials are never stored in plaintext. The server uses OS-native keychains for secure storage:

• macOS: Keychain Services via Security framework
• Windows: Credential Manager
• Linux: Secret Service API (libsecret)

When OS keychain is unavailable, credentials are encrypted using AES-256-GCM with machine-specific keys before being stored locally.

All credential operations automatically redact sensitive data from logs and error messages.

For authentication setup and credential management details, see:

• Authentication Guide - Comprehensive security features and troubleshooting
• Cookbook - Practical examples for credential management

Resilience & Fault Tolerance

Circuit Breaker Pattern

The server implements a circuit breaker pattern to protect against cascading failures when Jira Data Center is experiencing issues:

• Automatic failure detection: Opens circuit after 5 consecutive failures OR 50% failure rate in 10-second window
• Fail-fast behavior: When circuit is OPEN, requests are rejected immediately without calling Jira
• Self-healing: After 30-second timeout, circuit attempts health check to automatically recover
• Observable: Comprehensive structured logging and metrics for monitoring circuit state

This prevents overwhelming Jira during outages and enables graceful degradation of service.

Configuration: Circuit breaker thresholds can be tuned via environment variables:

CIRCUIT_BREAKER_FAILURE_THRESHOLD=5     # Consecutive failures before opening
CIRCUIT_BREAKER_FAILURE_RATE=0.5        # Failure rate threshold (0-1)
CIRCUIT_BREAKER_WINDOW_SIZE=10000       # Time window in milliseconds
CIRCUIT_BREAKER_TIMEOUT=30000           # Reset timeout in milliseconds

For detailed architecture and troubleshooting, see Backend Architecture - Circuit Breaker.

Logging & Observability

The server provides structured JSON logging with correlation IDs for request tracing and comprehensive observability:

• Structured logs: All logs are JSON with consistent schema for log aggregation tools (ELK, Datadog, Splunk)
• Correlation IDs: Every MCP request gets a unique UUID that propagates through all related logs
• Sensitive data protection: Automatic redaction of passwords, tokens, credentials (replaced with ***)
• Audit trail: All mutations (POST/PUT/DELETE) automatically logged with user, timestamp, and parameters
• Performance metrics: Request latency, cache hit rates, circuit breaker states

Configuration:

# Log level (DEBUG, INFO, WARN, ERROR)
LOG_LEVEL=INFO                       # Default: INFO

# Log output destination
LOG_OUTPUT=stdout                    # Options: stdout, file, both

# File output settings (when LOG_OUTPUT=file or both)
LOG_FILE_PATH=./logs/jira-dc-mcp.log   # Log file location
LOG_ROTATION=daily                   # Options: daily, hourly, size-based
LOG_MAX_SIZE=100                     # Max file size in MB before rotation
LOG_MAX_FILES=7                      # Number of rotated files to keep

Example log entry:

{
  "level": "info",
  "time": 1705320000000,
  "correlation_id": "req-abc-123",
  "service": "jira-dc-mcp",
  "version": "1.0.0",
  "event": "call_id.execution_success",
  "tool_name": "call_id",
  "operation_id": "create_issue",
  "method": "POST",
  "path": "/rest/api/3/issue",
  "status": 201,
  "latency_ms": 342,
  "msg": "Operation executed successfully"
}

Quick troubleshooting:

# Find all logs for a specific request
cat logs/jira-dc-mcp.log | jq 'select(.correlation_id == "req-abc-123")'

# Find all errors
cat logs/jira-dc-mcp.log | jq 'select(.level == "error")'

# Find slow operations (>1 second)
cat logs/jira-dc-mcp.log | jq 'select(.latency_ms > 1000)'

# View audit trail
cat logs/jira-dc-mcp.log | jq 'select(.audit_type == "mutation")'

For comprehensive logging setup, integration with log aggregators, and alert recommendations, see:

• Observability Guide - Complete logging, monitoring, and alerting setup
• Cookbook - Practical logging examples and troubleshooting