mcp-jira-stdio 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 graslt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,364 @@
+# MCP Jira Server
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Model Context Protocol (MCP) server for Jira API integration. Enables reading, writing, and managing Jira issues and projects directly from your MCP client (e.g., Claude Desktop).
+
+## 🚀 Quick Start
+
+### 1. Prerequisites
+
+- Node.js v18 or higher
+- Jira instance (Cloud or Server)
+- Jira API token
+
+### 2. Installation
+
+```bash
+# Install from npm
+npm install -g mcp-jira-stdio
+
+# Or install locally in your project
+npm install mcp-jira-stdio
+```
+
+#### Development Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/freema/mcp-jira-stdio.git
+cd mcp-jira-stdio
+
+# Install dependencies
+npm install
+# or using Task runner
+task install
+
+# Build the project
+npm run build
+# or
+task build
+```
+
+### 3. Jira API Setup
+
+1. Go to your Jira instance settings
+2. Create an API token:
+   - **Jira Cloud**: Go to Account Settings → Security → Create and manage API tokens
+   - **Jira Server**: Use your username and password (or create an application password)
+3. Note your Jira base URL (e.g., `https://yourcompany.atlassian.net`)
+
+### 4. Configuration
+
+Create a `.env` file from the provided example:
+
+```bash
+# Copy the example environment file
+cp .env.example .env
+
+# Edit .env with your actual Jira credentials
+# Or use Task runner:
+task env
+```
+
+Example `.env` contents:
+
+```env
+JIRA_BASE_URL=https://your-instance.atlassian.net
+JIRA_EMAIL=your-email@example.com
+JIRA_API_TOKEN=your-api-token
+```
+
+**Note:** Generate your API token at [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+
+### 5. Test Connection
+
+```bash
+# Test Jira connection
+task jira:test
+
+# List visible projects
+task jira:projects
+```
+
+### 6. Configure MCP Client
+
+Add to your Claude Desktop config:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "mcp-jira-stdio",
+      "env": {
+        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+#### Alternative: Using npx
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["mcp-jira-stdio"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-instance.atlassian.net",
+        "JIRA_EMAIL": "your-email@example.com",
+        "JIRA_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after adding the configuration.
+
+## 📦 Available Tools
+
+### Projects
+
+- `jira_get_visible_projects`: Retrieves all projects visible to the user.
+- `jira_get_project_info`: Retrieves detailed information about a project (components, versions, roles, insights).
+
+### Issues
+
+- `jira_get_issue`: Retrieve issue details by key (supports optional fields/expand).
+- `jira_search_issues`: Search for Jira issues using JQL with pagination and fields.
+- `jira_create_issue`: Create a new issue in a project (type, priority, assignee, labels, components).
+- `jira_update_issue`: Update an existing issue (summary, description, priority, assignee, labels, components).
+- `jira_create_subtask`: Create a subtask under a parent issue (auto-detects subtask type).
+
+### Comments
+
+- `jira_add_comment`: Add a comment to an issue (optional visibility by group/role).
+
+### Metadata & Users
+
+- `jira_get_issue_types`: List issue types (optionally per project).
+- `jira_get_users`: Search for users (by query, username, or accountId).
+- `jira_get_priorities`: List available priorities.
+- `jira_get_statuses`: List available statuses (global or project-specific).
+
+### My Work
+
+- `jira_get_my_issues`: Retrieve issues assigned to the current user (sorted by updated).
+
+## 🛠️ Development
+
+### Development Commands
+
+```bash
+# Development mode with hot reload
+npm run dev
+task dev
+
+# Build for production
+npm run build
+task build
+
+# Type checking
+npm run typecheck
+task typecheck
+
+# Linting
+npm run lint
+task lint
+
+# Format code
+npm run format
+task fmt
+
+# Run all checks
+npm run check
+task check
+```
+
+### MCP Inspector
+
+Debug your MCP server using the inspector:
+
+```bash
+# Run inspector (production build)
+npm run inspector
+task inspector
+
+# Run inspector (development mode)
+npm run inspector:dev
+task inspector:dev
+```
+
+### Testing
+
+```bash
+# Run tests
+npm test
+task test
+
+# Run tests with coverage
+npm run test:coverage
+task test:coverage
+
+# Watch mode
+npm run test:watch
+task test:watch
+```
+
+## 🚢 Publishing to npm
+
+Steps to publish a new version to npm:
+
+- Prerequisites: npm account with 2FA enabled (recommended) and access to the `mcp-jira-stdio` package name.
+- Bump version: `npm version patch` (or `minor`/`major`). This updates `package.json` and creates a git tag.
+- Verify locally:
+  - `npm run check` (typecheck, lint, format:check)
+  - `npm run test:run`
+  - `npm run build`
+- Inspect the tarball content: `npm pack` (should include `dist/`, `README.md`, `LICENSE`, `scripts/`).
+- Publish:
+  - Manual: `npm publish --access public`
+  - Or via GitHub Release: create a GitHub Release; the workflow at `.github/workflows/publish.yml` will build and publish to npm using `NPM_TOKEN` secret.
+
+CI Workflows:
+
+- CI checks on PRs/commits: `.github/workflows/ci.yml` runs typecheck, lint, format:check, tests, and build.
+- Publish on release: `.github/workflows/publish.yml` publishes to npm when a GitHub Release is published.
+
+Setup secrets for publish workflow:
+
+- In GitHub repo settings → Secrets and variables → Actions, add `NPM_TOKEN` (npm access token with publish rights).
+
+## 📋 Project Structure
+
+```
+src/
+├── index.ts              # Entry point & MCP server setup
+├── config/
+│   └── constants.ts      # API configuration & constants
+├── tools/
+│   ├── index.ts          # Tool exports
+│   └── get-visible-projects.ts  # Get visible projects tool
+├── types/
+│   ├── common.ts         # Common types & interfaces
+│   ├── jira.ts           # Jira API types
+│   └── tools.ts          # Tool input/output schemas
+└── utils/
+    ├── jira-auth.ts      # Jira authentication & client
+    ├── validators.ts     # Input validation with Zod
+    ├── formatters.ts     # Response formatting
+    ├── error-handler.ts  # Error handling
+    └── api-helpers.ts    # Jira API helpers
+```
+
+## 🔧 Tool Usage Examples
+
+### Get Visible Projects
+
+```javascript
+// List all projects
+jira_get_visible_projects({});
+
+// List projects with additional details
+jira_get_visible_projects({
+  expand: ['description', 'lead', 'issueTypes'],
+});
+
+// List recent projects only
+jira_get_visible_projects({
+  recent: 10,
+});
+```
+
+## ❗ Troubleshooting
+
+### Common Issues
+
+**"Authentication failed"**
+
+- Verify your API token is correct
+- Check that your email matches your Jira account
+- Ensure your Jira base URL is correct (no trailing slash)
+
+**"Connection failed"**
+
+- Verify your Jira instance is accessible
+- Check network connectivity
+- Ensure Jira REST API is enabled
+
+**"Permission denied"**
+
+- Verify your account has the necessary permissions
+- Check project permissions in Jira
+- Ensure you're using the correct Jira instance
+
+**MCP Connection Issues**
+
+- Ensure you're using the built version (`dist/index.js`)
+- Check that Node.js path is correct in Claude Desktop config
+- Look for errors in Claude Desktop logs
+- Use `task inspector` to debug
+
+### Debug Commands
+
+```bash
+# Test Jira connection
+task jira:test
+
+# List projects (test API connectivity)
+task jira:projects
+
+# Run MCP inspector for debugging
+task inspector:dev
+
+# Check all configuration
+task check
+```
+
+## 🔍 Environment Variables
+
+| Variable         | Required | Description       | Example                         |
+| ---------------- | -------- | ----------------- | ------------------------------- |
+| `JIRA_BASE_URL`  | Yes      | Jira instance URL | `https://company.atlassian.net` |
+| `JIRA_EMAIL`     | Yes      | Your Jira email   | `user@example.com`              |
+| `JIRA_API_TOKEN` | Yes      | Jira API token    | `ATxxx...`                      |
+| `NODE_ENV`       | No       | Environment mode  | `development` or `production`   |
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests and linting (`task check`)
+4. Commit your changes (`git commit -m 'Add some amazing feature'`)
+5. Push to the branch (`git push origin feature/amazing-feature`)
+6. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+### MCP Config Setup
+
+Configure Claude Desktop to use this MCP server interactively:
+
+```bash
+npm run setup:mcp
+```
+
+The script will:
+
+- Build the project if needed and detect your Node path
+- Prompt for `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
+- Save a `jira` entry into your Claude Desktop config or print the JSON
+- Optionally generate a local `.env` for development

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }