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.

$3

Fastest path - One command to start the MCP server:

``bash


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:

`bash


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.

$3

Recommended for local development - Global CLI with interactive setup:

`bash


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.

$3

For contributors and developers - Build from source:

`bash


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.

$3

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

$3

| 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 | Search for operations using semantic search | jira-dc-mcp search "create issue" |
| get | Get detailed info about a specific operation | jira-dc-mcp get createIssue |
| call | Execute a Jira operation | jira-dc-mcp call createIssue --param ... |
| config | Manage configuration (show, validate, path, reset) | jira-dc-mcp config show |
| version | Show version information | jira-dc-mcp version |

$3

#### 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:
`bash
jira-dc-mcp setup
`

#### jira-dc-mcp start

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

Example:
`bash
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:
`bash
jira-dc-mcp test-connection
`

#### jira-dc-mcp search

Search for Jira operations using natural language queries.

Options:
- --limit - Maximum number of results (default: 5)
- --json - Output results as JSON
- --verbose - Show similarity scores

Example:
`bash
jira-dc-mcp search "create issue" --limit 3 --verbose
`

#### jira-dc-mcp get

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:
`bash
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

Execute a Jira operation with specified parameters.

Options:
- --param - Operation parameters (can be repeated)
- --json - Output raw JSON response
- --dry-run - Validate parameters only, do not execute

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

#### jira-dc-mcp config

Manage configuration settings.

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

Example:
`bash
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:
`bash
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:

$3

`bash


Complete database regeneration (recommended)


cd jira-dc-mcp
rm -f data/embeddings.db* && npm run build:all
`

$3

`bash


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
`

$3

- 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

$3

`bash


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.

$3

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

#### Core Commands

`bash


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

`bash


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 [--json] [--verbose]

Execute a Jira operation

jira-dc-mcp call [--param key=value] [--json] [--dry-run]
`

#### Configuration Commands

`bash


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

`bash


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

---

$3

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:
`json
{
"tool": "search_ids",
"input": {
"query": "create an issue",
"limit": 3
}
}
`

Response:
`json
{
"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:
`json
{
"tool": "get_id",
"input": {
"operation_id": "createIssue"
}
}
`

Response:
`json
{
"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:
`json
{
"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:
`json
{
"id": "10042",
"key": "PROJ-123",
"self": "https://jira.example.com/rest/api/3/issue/10042"
}
`

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

---

$3

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

$3

- 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

$3

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

$3

`bash


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
`

$3

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

`yaml
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

$3

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.).

$3

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)

`json
{
"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

`json
{
"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)

`json
{
"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"
}
}
}
}
`

$3

Add to Cline's MCP settings:

`json
{
"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"
}
}
}
}
`

$3

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

$3

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

$3

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

`text
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 |

$3

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

---

Development

$3

`bash
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
`

$3

After building, you can test CLI commands locally:

`bash
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
`

$3

Download and process the Jira Data Center OpenAPI specification:

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

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

$3

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

`bash
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 limits the maximum number of rows returned (1–100).
- --threshold 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 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:

`text
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

$3

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

$3

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

$3

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

$3

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:
`bash


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

$3

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

$3

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:
`bash
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:
`bash


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:
`json
{
"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:
`bash


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