Jira Data Center MCP Server
by guercheLE
README.md
# Jira Data Center MCP Server
[](https://github.com/guercheLE/jira-dc-mcp/actions)
[](https://www.npmjs.com/package/jira-dc-mcp)
[](https://www.gnu.org/licenses/lgpl-3.0)
[](https://nodejs.org)
[](CONTRIBUTING.md)
**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.
---
<!-- TODO: Add screenshots once available
## Visual Overview
### Setup Wizard
*Interactive setup wizard completes configuration in under 5 minutes*
### Semantic Search in Action
*Natural language queries return ranked Jira operations with relevance scores*
### Claude Desktop Integration
*Claude Desktop using MCP tools to interact with Jira Data Center*
-->
---
## Table of Contents
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [Docker (Recommended)](#docker-recommended)
- [npm Install](#npm-install)
- [From Source](#from-source)
- [Usage](#usage)
- [MCP Tools](#mcp-tools)
- [Common Workflows](#common-workflows)
- [Installation](#installation)
- [Configuration](#configuration)
- [MCP Client Configuration](#mcp-client-configuration)
- [Project Structure](#project-structure)
- [Documentation](#documentation)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Contributors](#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:
```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](docs/docker.md) for advanced configuration.
### npm Install
**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](docs/troubleshooting.md#setup-wizard-errors) for common problems.
### From Source
**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.
### 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](#mcp-client-configuration) to connect Claude Desktop, Cline, or other clients
- **Explore MCP tools:** See [Usage Examples](#usage) below
- **Configure advanced features:** Check [Configuration Guide](#configuration)
---
---
## 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:**
```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 <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:**
```bash
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:**
```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 <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:**
```bash
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:**
```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:
### Quick Regeneration
```bash
# Complete database regeneration (recommended)
cd jira-dc-mcp
rm -f data/embeddings.db* && npm run build:all
```
### Step-by-Step Regeneration
```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
```
### 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
```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](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
```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 <operationId> [--json] [--verbose]
# Execute a Jira operation
jira-dc-mcp call <operationId> [--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`
---
### 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:**
```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" }
}
}
}
```
---
### 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](docs/cookbook.md) for 20+ practical examples and advanced patterns.**
---
## Installation
### Prerequisites
- **Node.js 22+** (LTS recommended) - [Download](https://nodejs.org)
- **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](#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
```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
```
### Config File Example
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](docs/internal/architecture/backend-architecture.md#configuration)
### 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](docs/api-version-detection.md) - Complete guide on API version detection
- [API Version FAQ](docs/api-version-faq.md) - 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)
```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"
}
}
}
}
```
### Cline (VS Code Extension)
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"
}
}
}
}
```
### 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](docs/troubleshooting.md)
---
## 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](docs/internal/architecture.md)** | System design, components, data flow |
| **[Authentication Guide](docs/authentication.md)** | OAuth 2.0, PAT, OAuth 1.0a setup and troubleshooting |
| **[API Version Detection](docs/api-version-detection.md)** | API version detection and configuration guide |
| **[API Version FAQ](docs/api-version-faq.md)** | Frequently asked questions about API versions |
| **[Cookbook](docs/cookbook.md)** | 20+ practical examples and code snippets |
| **[Docker Deployment](docs/docker.md)** | Container setup, environment variables, docker-compose |
| **[Troubleshooting Guide](docs/troubleshooting.md)** | Common issues and solutions |
| **[API Reference](docs/internal/architecture/api-specification.md)** | Complete MCP tools specification |
| **[Testing Strategy](docs/internal/architecture/testing-strategy.md)** | Unit, integration, E2E test patterns |
| **[Observability](docs/observability.md)** | Logging, monitoring, alerting setup |
### Getting Help
- **🐛 Bug Reports:** [Open an issue](https://github.com/guercheLE/jira-dc-mcp/issues/new?template=bug_report.md)
- **💡 Feature Requests:** [Request a feature](https://github.com/guercheLE/jira-dc-mcp/issues/new?template=feature_request.md)
- **❓ Questions:** [Discussions](https://github.com/guercheLE/jira-dc-mcp/discussions)
- **📧 Email:** Open a GitHub issue for fastest response
---
## Development
### Development Commands
```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
```
### CLI Commands (Post-Build)
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
```
### OpenAPI Spec Processing
Download and process the Jira Data Center OpenAPI specification:
```bash
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:
```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 <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:
```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](CONTRIBUTING.md) and please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
When opening an issue or pull request:
- Use the [issue templates](.github/ISSUE_TEMPLATE) for bugs, features, and questions
- Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) 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](docs/internal/architecture/coding-standards.md)
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
```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
```
### 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](docs/internal/architecture/coding-standards.md)
### 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:**
```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](tests/README.md)**
---
## License
**LGPL-3.0 License** - see [LICENSE](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](CONTRIBUTING.md) and follow our [Code of Conduct](CODE_OF_CONDUCT.md)
- See everyone who has contributed on the [GitHub contributors page](https://github.com/guercheLE/jira-dc-mcp/graphs/contributors)
---
## Acknowledgments
Built with excellent open-source tools:
- [@modelcontextprotocol/sdk](https://github.com/anthropics/mcp) - MCP implementation by Anthropic
- [sqlite-vec](https://github.com/asg017/sqlite-vec) - Vector search for SQLite
- [@xenova/transformers](https://github.com/xenova/transformers.js) - Local embeddings
- [Zod](https://github.com/colinhacks/zod) - TypeScript schema validation
- [pino](https://github.com/pinojs/pino) - High-performance JSON logger
- [Vitest](https://vitest.dev) - 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](docs/authentication.md) - Comprehensive security features and troubleshooting
- [Cookbook](docs/cookbook.md) - 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:
```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](docs/internal/architecture/backend-architecture.md#circuit-breaker-pattern).
## 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](docs/observability.md) - Complete logging, monitoring, and alerting setup
- [Cookbook](docs/cookbook.md) - Practical logging examples and troubleshooting