{
  "markdown": "# Jira MCP Server\n\n[![npm version](https://badge.fury.io/js/raalarcon-jira-mcp-server.svg)](https://badge.fury.io/js/raalarcon-jira-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)\n[![CI/CD](https://github.com/raalarcon9705/jira-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/raalarcon9705/jira-mcp/actions/workflows/ci.yml)\n\nThe most complete **open source** [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **Jira & Atlassian**. Connect any MCP-compatible AI client to your Jira instance in seconds — manage issues, sprints, comments, transitions, users, and Confluence pages without leaving your AI assistant.\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"raalarcon-jira-mcp-server\"],\n      \"env\": {\n        \"JIRA_HOST\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n### Compatible AI Clients\n\n| Client | Supported |\n|--------|-----------|\n| [Claude Desktop](https://claude.ai/download) | ✅ |\n| [Claude Code](https://claude.ai/code) | ✅ |\n| [Cursor](https://cursor.sh) | ✅ |\n| [Windsurf](https://codeium.com/windsurf) | ✅ |\n| [Cline](https://github.com/cline/cline) | ✅ |\n| [Continue](https://continue.dev) | ✅ |\n| Any MCP-compatible client | ✅ |\n\n[![Open Source Love](https://badges.frapsoft.com/os/v1/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n[![Contributors](https://img.shields.io/github/contributors/raalarcon9705/jira-mcp.svg)](https://github.com/raalarcon9705/jira-mcp/graphs/contributors)\n[![Stars](https://img.shields.io/github/stars/raalarcon9705/jira-mcp.svg)](https://github.com/raalarcon9705/jira-mcp/stargazers)\n\n### Find This Server On\n\n- [MCP Market](https://mcpmarket.com/) — MCP server marketplace\n- [MCP Servers](https://mcpservers.org/) — Awesome MCP Servers directory\n- [Claude Marketplaces](https://claudemarketplaces.com) — Claude plugins & MCP directory\n- [npm](https://www.npmjs.com/package/raalarcon-jira-mcp-server) — `npx raalarcon-jira-mcp-server`\n\n## Features\n\n- ✅ **Project Management**: List projects and issue types\n- ✅ **Issue CRUD**: Create, read, update and delete issues\n- ✅ **Comments**: Create, read, update and delete comments with enhanced pagination\n- ✅ **Transitions**: Move issues between states\n- ✅ **Assignments**: Assign issues to users\n- ✅ **User Management**: Search and manage users\n- ✅ **Sprint Management**: Complete agile sprint lifecycle management\n- ✅ **Wiki Integration**: Access Confluence pages by URL identifier with HTML to text conversion\n- ✅ **Rich Text Support**: Markdown to ADF conversion for formatted descriptions and comments\n- ✅ **Validation**: Yup schema validation\n- ✅ **Authentication**: Full Jira Cloud support\n- ✅ **Optimized Responses**: Token-efficient field filtering\n- ✅ **Type Safety**: Full TypeScript support\n\n## Installation\n\n### Option 1: Using npx (Recommended)\n\nThe easiest way to use this MCP server is with `npx`:\n\n1. **Configure your MCP client** (e.g., Claude Desktop) with this configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"raalarcon-jira-mcp-server\"],\n      \"env\": {\n        \"JIRA_HOST\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n2. **Get your Jira API token** (see instructions below)\n\nThat's it! The server will be automatically downloaded and run when needed.\n\n### Option 2: Local Development\n\n1. **Clone the repository**:\n\n```bash\ngit clone https://github.com/raalarcon9705/jira-mcp.git\ncd jira-mcp\n```\n\n2. **Install dependencies**:\n\n```bash\nnpm install\n```\n\n3. **Build the project**:\n\n```bash\nnpm run build\n```\n\n4. **Configure your MCP client** with the full path to the built server:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"node\",\n      \"args\": [\"/full/path/to/jira-mcp/dist/index.js\"],\n      \"env\": {\n        \"JIRA_HOST\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n**Note**: Replace `/full/path/to/jira-mcp/` with the actual absolute path to your project directory.\n\n### Getting API Token\n\n1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click \"Create API token\"\n3. Give it a descriptive name\n4. Copy the generated token\n\n## Usage\n\n### Using with npx (Recommended)\n\nOnce configured in your MCP client, the server will automatically start when needed. No additional setup required!\n\n### Rich Text Support with Markdown\n\nThe server now supports **automatic Markdown to ADF conversion** for issue descriptions and comments. Simply use Markdown syntax and it will be automatically converted to Atlassian Document Format (ADF).\n\n#### Supported Markdown Elements\n\n- **Headers**: `# H1`, `## H2`, `### H3`\n- **Text formatting**: `**bold**`, `*italic*`\n- **Code**: `` `inline code` `` and `code blocks`\n- **Lists**: `- bullet lists` and `1. numbered lists`\n- **Links**: `[text](url)`\n- **Blockquotes**: `> quoted text`\n- **Checkboxes**: `- [x] completed task`\n\n#### Example Usage\n\n```javascript\n// Create issue with Markdown description\ncreate_issue({\n  projectKey: 'PROJ',\n  summary: 'Bug Report',\n  description: `# Bug Report\n\n## Description\nThis is a **critical** bug affecting the login system.\n\n## Steps to Reproduce\n1. Go to login page\n2. Enter invalid credentials\n3. Click login button\n\n## Code Example\n\\`\\`\\`javascript\nfunction login(username, password) {\n  return authenticate(username, password);\n}\n\\`\\`\\`\n\n> **Note**: This bug was reported by multiple users.`,\n});\n\n// Create comment with Markdown\ncreate_comment({\n  issueKey: 'PROJ-123',\n  body: `## Update\n\n**Status**: Fixed ✅\n\n- [x] Identified root cause\n- [x] Implemented fix\n- [x] Tested solution\n\nThe issue has been resolved.`,\n});\n```\n\n### Development\n\n```bash\nnpm run dev\n```\n\n### Production\n\n```bash\nnpm run build\nnpm start\n```\n\n### Testing with npx\n\nYou can also test the server directly with npx:\n\n```bash\n# Test the server\nnpx raalarcon-jira-mcp-server\n\n# Or use with MCP Inspector\nnpx @modelcontextprotocol/inspector\n# Then configure: command: \"npx\", args: [\"-y\", \"raalarcon-jira-mcp-server\"]\n```\n\n## Available Tools\n\n### Projects\n\n#### `get_projects`\n\nRetrieves all projects accessible to the authenticated user.\n\n**Parameters**:\n\n- `expand` (optional): Additional data to include\n- `recent` (optional): Number of recent projects (0-20)\n\n**Response**: Array of projects with essential fields:\n\n```json\n[\n  {\n    \"key\": \"PROJ\",\n    \"name\": \"Project Name\",\n    \"id\": \"10001\",\n    \"projectTypeKey\": \"software\"\n  }\n]\n```\n\n#### `get_issue_types`\n\nGets all available issue types for a specific project.\n\n**Parameters**:\n\n- `projectKey` (required): Project key\n\n**Response**: Array of issue types with essential fields:\n\n```json\n[\n  {\n    \"id\": \"10002\",\n    \"name\": \"Task\",\n    \"desc\": \"A small, independent piece of work\",\n    \"subtask\": false,\n    \"level\": 0\n  }\n]\n```\n\n### Issues\n\n#### `create_issue`\n\nCreates a new issue in Jira.\n\n**Parameters**:\n\n- `projectKey` (required): Project key\n- `summary` (required): Issue summary\n- `issueType` (required): Issue type (Bug, Story, Task, etc.)\n- `description` (optional): Issue description\n- `priority` (optional): Priority (Highest, High, Medium, Low, Lowest)\n- `assignee` (optional): Assignee account ID\n- `labels` (optional): Array of labels\n- `components` (optional): Array of components\n- `fixVersions` (optional): Array of fix versions\n- `customFields` (optional): Custom field values\n\n**Response**: `Issue PROJ-123 created successfully`\n\n#### `get_issue`\n\nGets details of a specific issue (custom fields removed for token efficiency).\n\n**Parameters**:\n\n- `issueKey` (required): Issue key (e.g., PROJ-123)\n- `expand` (optional): Additional information\n- `fields` (optional): Specific fields to return\n\n**Response**: Complete issue object with custom fields filtered out\n\n#### `update_issue`\n\nUpdates an existing issue.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key to update\n- `summary` (optional): New summary\n- `description` (optional): New description\n- `priority` (optional): New priority\n- `assignee` (optional): New assignee\n- `labels` (optional): New labels\n- `components` (optional): New components\n- `fixVersions` (optional): New fix versions\n- `customFields` (optional): Custom fields\n\n**Response**: `Issue PROJ-123 updated successfully`\n\n#### `delete_issue`\n\nDeletes an issue.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key to delete\n- `deleteSubtasks` (optional): Delete subtasks too (default: false)\n\n**Response**: `Issue PROJ-123 deleted successfully`\n\n### Comments\n\n#### `create_comment`\n\nAdds a comment to an issue.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `body` (required): Comment text (supports ADF format)\n- `visibility` (optional): Visibility settings\n\n**Response**: `Comment 12345 created successfully`\n\n#### `get_comments`\n\nGets all comments for an issue.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `startAt` (optional): Start index (default: 0)\n- `maxResults` (optional): Max comments (1-100, default: 50)\n\n**Response**: Optimized comment structure:\n\n```json\n{\n  \"total\": 5,\n  \"start\": 0,\n  \"max\": 50,\n  \"items\": [\n    {\n      \"id\": \"12345\",\n      \"author\": \"John Doe\",\n      \"authorId\": \"account-id\",\n      \"created\": \"2025-01-01T10:00:00.000Z\",\n      \"text\": \"Comment text content\"\n    }\n  ]\n}\n```\n\n#### `update_comment`\n\nUpdates an existing comment.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `commentId` (required): Comment ID\n- `body` (required): New comment text\n- `visibility` (optional): New visibility settings\n\n**Response**: `Comment 12345 updated successfully`\n\n#### `delete_comment`\n\nDeletes a comment.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `commentId` (required): Comment ID\n\n**Response**: `Comment 12345 deleted successfully`\n\n### Transitions\n\n#### `get_transitions`\n\nGets available transitions for an issue.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n\n**Response**: Array of transitions with essential fields:\n\n```json\n[\n  {\n    \"id\": \"21\",\n    \"name\": \"In Progress\",\n    \"desc\": \"The assignee is currently working on this activity\",\n    \"toName\": \"In Progress\",\n    \"toId\": \"3\",\n    \"available\": true,\n    \"category\": \"In Progress\"\n  }\n]\n```\n\n#### `transition_issue`\n\nMoves an issue to a different state.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `transitionId` (required): Transition ID\n- `comment` (optional): Comment to add during transition\n- `fields` (optional): Additional fields to update\n\n**Response**: `Issue PROJ-123 transitioned successfully`\n\n### Assignments\n\n#### `assign_issue`\n\nAssigns an issue to a user.\n\n**Parameters**:\n\n- `issueKey` (required): Issue key\n- `assignee` (required): User account ID\n\n**Response**: `Issue PROJ-123 assigned successfully`\n\n#### `get_users`\n\nSearches for users in Jira.\n\n**Parameters**:\n\n- `query` (optional): Search query by name or email\n- `projectKey` (optional): Filter by project access\n- `maxResults` (optional): Max users (1-100, default: 50)\n\n**Response**: Array of users with essential fields:\n\n```json\n[\n  {\n    \"id\": \"account-id\",\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\",\n    \"active\": true,\n    \"type\": \"atlassian\"\n  }\n]\n```\n\n#### `get_current_user`\n\nGets information about the current authenticated user.\n\n**Response**: Current user with essential fields:\n\n```json\n{\n  \"id\": \"account-id\",\n  \"name\": \"Current User\",\n  \"email\": \"user@example.com\",\n  \"active\": true,\n  \"timezone\": \"America/New_York\",\n  \"type\": \"atlassian\"\n}\n```\n\n### Sprint Management\n\n#### `get_agile_boards`\n\nGets all agile boards available in the Jira instance. Required to find board IDs for sprint operations.\n\n**Parameters**:\n\n- `projectKey` (optional): Filter boards by project\n- `boardType` (optional): Filter by type (scrum, kanban)\n\n**Response**: Array of boards with essential fields:\n\n```json\n[\n  {\n    \"id\": 191,\n    \"name\": \"DreamStar Board\",\n    \"type\": \"scrum\",\n    \"projectKey\": \"DRMSTR\",\n    \"projectName\": \"DreamStar\"\n  }\n]\n```\n\n#### `get_sprints`\n\nGets all sprints for a specific board. Returns sprint information including ID, name, state, and dates.\n\n**Parameters**:\n\n- `boardId` (required): The ID of the board to get sprints from\n- `state` (optional): Filter sprints by state (active, closed, future)\n\n**Response**: Array of sprints with essential fields:\n\n```json\n[\n  {\n    \"id\": 387,\n    \"name\": \"DRMSTR Sprint 1\",\n    \"state\": \"active\",\n    \"startDate\": \"2025-09-15T14:05:37.511Z\",\n    \"endDate\": \"2025-09-26T05:00:00.000Z\",\n    \"goal\": \"\"\n  }\n]\n```\n\n#### `create_sprint`\n\nCreates a new sprint. Sprint name and origin board ID are required. Start date, end date, and goal are optional.\n\n**Parameters**:\n\n- `name` (required): Name of the sprint to create\n- `originBoardId` (required): ID of the board where the sprint will be created\n- `startDate` (optional): Start date of the sprint (ISO 8601 format)\n- `endDate` (optional): End date of the sprint (ISO 8601 format)\n- `goal` (optional): Goal or objective of the sprint\n\n**Response**: Created sprint with essential fields:\n\n```json\n{\n  \"id\": 421,\n  \"name\": \"DRMSTR Sprint 3\",\n  \"state\": \"future\",\n  \"goal\": \"\"\n}\n```\n\n#### `update_sprint`\n\nUpdates sprint information (name, dates, goal, state). Only provided fields will be updated. For closed sprints, only name and goal can be updated.\n\n**Parameters**:\n\n- `sprintId` (required): ID of the sprint to update\n- `name` (optional): New name for the sprint\n- `startDate` (optional): New start date (ISO 8601 format)\n- `endDate` (optional): New end date (ISO 8601 format)\n- `goal` (optional): New goal or objective for the sprint\n- `state` (optional): New state (future, active, closed)\n\n**Response**: `Sprint 421 updated successfully`\n\n#### `close_sprint`\n\nCloses and completes a sprint. This action requires the sprint to be in the \"active\" state. Once closed, the sprint cannot be reopened.\n\n**Parameters**:\n\n- `sprintId` (required): ID of the sprint to close\n\n**Response**: `Sprint 421 closed successfully`\n\n#### `delete_sprint`\n\nDeletes a sprint. Once deleted, all open issues in the sprint will be moved to the backlog. This action is irreversible.\n\n**Parameters**:\n\n- `sprintId` (required): ID of the sprint to delete\n\n**Response**: `Sprint 421 deleted successfully. All open issues moved to backlog.`\n\n#### `move_issue_to_sprint`\n\nMoves an issue to a specific sprint. Returns a confirmation message. Issues can only be moved to open or active sprints.\n\n**Parameters**:\n\n- `issueKey` (required): Key of the issue to move (e.g., \"PROJ-123\")\n- `sprintId` (required): ID of the sprint to move the issue to\n\n**Response**: `Issue PROJ-123 moved to sprint 421 successfully`\n\n#### `get_sprint_issues`\n\nGets all issues for a given sprint. Returns a list of essential issue details (key, summary, status, assignee, priority).\n\n**Parameters**:\n\n- `sprintId` (required): ID of the sprint\n- `maxResults` (optional): Maximum number of issues to return (1-100, default: 50)\n\n**Response**: Array of issues with essential fields:\n\n```json\n[\n  {\n    \"key\": \"DRMSTR-1\",\n    \"summary\": \"Implement user authentication\",\n    \"status\": \"In Progress\",\n    \"assignee\": \"John Doe\",\n    \"priority\": \"High\"\n  }\n]\n```\n\n## Response Optimization\n\nThe server is optimized for token efficiency:\n\n- **Essential Fields Only**: Returns only necessary fields for each operation\n- **Custom Fields Filtered**: Automatically removes custom fields from issue responses\n- **Short Field Names**: Uses abbreviated field names (e.g., `desc` instead of `description`)\n- **Success Messages**: Clear, concise success confirmations\n- **Structured Data**: Consistent response formats across all tools\n\n## Error Handling\n\nThe server includes robust error handling with descriptive messages. Common errors include:\n\n- **Authentication**: Invalid or expired credentials\n- **Permissions**: Insufficient permissions for the operation\n- **Validation**: Invalid input data\n- **Resources**: Issues or projects not found\n- **API**: Rate limits or Jira server errors\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # Main MCP server\n├── jira-client.ts        # Jira API client\n├── schemas/\n│   └── index.ts          # Yup validation schemas\n└── tools/\n    ├── projects.ts       # Project tools\n    ├── issues.ts         # Issue tools\n    ├── comments.ts       # Comment tools\n    ├── transitions.ts    # Transition tools\n    ├── assignments.ts    # Assignment tools\n    └── sprints.ts        # Sprint management tools\n```\n\n### Adding New Features\n\n1. **Create validation schema** in `src/schemas/index.ts`\n2. **Implement method** in `src/jira-client.ts`\n3. **Create MCP tool** in appropriate file in `src/tools/`\n4. **Register tool** in `src/index.ts`\n\n### Testing\n\n#### Using MCP Inspector (Recommended)\n\n1. **Install MCP Inspector**:\n\n   ```bash\n   npm install -g @modelcontextprotocol/inspector\n   ```\n\n2. **Build the project**:\n\n   ```bash\n   npm run build\n   ```\n\n3. **Start MCP Inspector**:\n\n   ```bash\n   npx @modelcontextprotocol/inspector\n   ```\n\n4. **Configure your server** in the inspector interface:\n   - **Transport**: STDIO (default)\n   - **Command**: `node`\n   - **Args**: `build/index.js`\n   - **Environment**: Add your Jira credentials\n\n#### Alternative Testing Methods\n\n**CLI Mode** (for automation and scripting):\n\n```bash\n# List available tools\nnpx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list\n\n# Call a specific tool\nnpx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name get_projects\n```\n\n**Configuration File** (for complex setups):\n\n```json\n{\n  \"mcpServers\": {\n    \"jira-server\": {\n      \"command\": \"node\",\n      \"args\": [\"build/index.js\"],\n      \"env\": {\n        \"JIRA_HOST\": \"https://your-domain.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop**: Configure MCP servers directly in Claude Desktop for real-world testing\n\n#### Advanced Configuration\n\n**Environment Variables** (for advanced users):\n\n```bash\n# Jira configuration\nexport JIRA_HOST=\"https://your-domain.atlassian.net\"\nexport JIRA_EMAIL=\"your-email@example.com\"\nexport JIRA_API_TOKEN=\"your-api-token\"\n\n# Timeout settings\nexport MCP_SERVER_REQUEST_TIMEOUT=60000\nexport MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false\n\n# Proxy settings (if using MCP Proxy)\nexport MCP_PROXY_FULL_ADDRESS=http://localhost:5577\n\n# Auto-open browser\nexport MCP_AUTO_OPEN_ENABLED=true\n```\n\n**Query Parameters** (for direct testing):\n\n```\nhttp://localhost:6274/?transport=stdio&serverCommand=node&serverArgs=build/index.js\n```\n\n#### Manual Testing\n\n```bash\n# Build and run the server\nnpm run build\nnpm start\n```\n\n### Wiki\n\n#### `query_wiki`\n\nAccesses Confluence pages by URL identifier and returns formatted content.\n\n**Parameters**:\n\n- `query` (required): Page code to search for (like F4CjNw)\n\n**Response**: Markdown-formatted page content with metadata:\n\n```markdown\n# Page Title\n\n**ID:** 933462039\n**Space:** Orderbahn Team (OT)\n**URL:** /spaces/OT/pages/933462039/...\n**Author:** User Name\n**Last Modified:** 2025-09-26T16:35:30.695Z\n**Code:** F4CjNw\n\n## Content\n\n[Page content in plain text with preserved line breaks]\n\n## Page Hierarchy\n\n- Parent Page (page)\n  - Child Page (folder)\n    - Current Page (page)\n```\n\n**Features**:\n\n- Automatic redirect following for short URLs\n- HTML to plain text conversion preserving structure\n- Page hierarchy display\n- Comprehensive error handling\n\n## Contributing\n\nWe welcome contributions to the Jira MCP Server! Please follow these guidelines to ensure a smooth contribution process.\n\n### Getting Started\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally:\n   ```bash\n   git clone https://github.com/raalarcon9705/jira-mcp.git\n   cd jira-mcp\n   ```\n3. **Install dependencies**:\n   ```bash\n   npm install\n   ```\n4. **Create a new branch** for your feature:\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n\n### Development Workflow\n\n#### Setting Up Your Environment\n\n1. **Install MCP Inspector** (official testing tool):\n\n   ```bash\n   npm install -g @modelcontextprotocol/inspector\n   ```\n\n2. **Build the project**:\n\n   ```bash\n   npm run build\n   ```\n\n3. **Test with MCP Inspector**:\n   ```bash\n   npx @modelcontextprotocol/inspector\n   ```\n   Then configure your server:\n   - **Transport**: STDIO\n   - **Command**: `node`\n   - **Args**: `build/index.js`\n   - **Environment**: Add your Jira credentials\n\n#### Code Standards\n\n- **TypeScript**: All code must be written in TypeScript\n- **Type Safety**: Avoid `any` types, use proper Jira.js types\n- **Error Handling**: Include comprehensive error handling\n- **Validation**: Use Yup schemas for input validation\n- **Comments**: Add clear comments for complex logic\n- **Formatting**: Follow existing code style and formatting\n\n#### Adding New Features\n\n1. **Create validation schema** in `src/schemas/index.ts`:\n\n   ```typescript\n   export const yourFeatureSchema = yup.object({\n     // Define your schema\n   });\n   ```\n\n2. **Implement API method** in `src/jira-client.ts`:\n\n   ```typescript\n   async yourFeature(input: YourFeatureInput) {\n     try {\n       // Implementation\n     } catch (error) {\n       throw new Error(`Failed to your feature: ${error.message}`);\n     }\n   }\n   ```\n\n3. **Create MCP tool** in appropriate file in `src/tools/`:\n\n   ```typescript\n   {\n     name: 'your_tool',\n     description: 'Clear description of what the tool does',\n     inputSchema: {\n       // Define input schema\n     }\n   }\n   ```\n\n4. **Register tool** in `src/index.ts`:\n\n   ```typescript\n   // Add to appropriate handler\n   ```\n\n5. **Optimize response** for token efficiency:\n   - Return only essential fields\n   - Use short field names\n   - Filter out unnecessary data\n\n#### Testing Your Changes\n\n1. **Build the project**:\n\n   ```bash\n   npm run build\n   ```\n\n2. **Test with MCP Inspector**:\n\n   ```bash\n   npx @modelcontextprotocol/inspector\n   ```\n\n   - Configure server: STDIO, `node build/index.js`\n   - Test all affected tools\n   - Verify responses are optimized\n\n3. **Test with CLI mode** (for automation):\n\n   ```bash\n   # List tools\n   npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list\n\n   # Test specific tool\n   npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name get_projects\n   ```\n\n4. **Verify response optimization**:\n   - Check that only essential fields are returned\n   - Ensure field names are shortened\n   - Confirm custom fields are filtered out\n\n### Pull Request Process\n\n#### Before Submitting\n\n- [ ] **Code compiles** without TypeScript errors\n- [ ] **All tools work** as expected\n- [ ] **Response optimization** is implemented\n- [ ] **Error handling** is comprehensive\n- [ ] **Documentation** is updated if needed\n- [ ] **No personal data** is included in examples\n\n#### Creating a Pull Request\n\n1. **Commit your changes** with clear messages:\n\n   ```bash\n   git add .\n   git commit -m \"Add new feature: brief description\"\n   ```\n\n2. **Push to your fork**:\n\n   ```bash\n   git push origin feature/your-feature-name\n   ```\n\n3. **Open a Pull Request** on GitHub with:\n   - **Clear title** describing the change\n   - **Detailed description** of what was added/changed\n   - **Testing instructions** for reviewers\n   - **Screenshots** if UI changes are involved\n\n#### Pull Request Template\n\n```markdown\n## Description\n\nBrief description of the changes\n\n## Type of Change\n\n- [ ] Bug fix\n- [ ] New feature\n- [ ] Breaking change\n- [ ] Documentation update\n\n## Testing\n\n- [ ] All existing tests pass\n- [ ] New functionality tested\n- [ ] Response optimization verified\n\n## Checklist\n\n- [ ] Code follows project standards\n- [ ] Self-review completed\n- [ ] Documentation updated\n- [ ] No personal data included\n```\n\n### Code Review Process\n\n1. **Automated checks** will run on your PR\n2. **Maintainers will review** your code\n3. **Address feedback** promptly\n4. **Make requested changes** and update the PR\n5. **PR will be merged** once approved\n\n### Reporting Issues\n\nWhen reporting bugs or requesting features:\n\n1. **Check existing issues** first\n2. **Use the issue template** provided\n3. **Include reproduction steps** for bugs\n4. **Provide clear description** for feature requests\n5. **Include relevant logs** and error messages\n\n### Development Guidelines\n\n#### Response Optimization\n\n- **Essential fields only**: Return only necessary data\n- **Short field names**: Use abbreviated names (e.g., `desc` instead of `description`)\n- **Filter custom fields**: Remove `customfield_*` from issue responses\n- **Consistent format**: Maintain uniform response structure\n\n#### Error Handling\n\n- **Descriptive messages**: Include context in error messages\n- **Proper error types**: Use appropriate error types\n- **Logging**: Add console.error for debugging\n- **User-friendly**: Make errors understandable for end users\n\n#### Documentation\n\n- **Update README**: Add new tools to documentation\n- **Include examples**: Provide usage examples\n- **Response format**: Document response structure\n- **No personal data**: Use generic examples only\n\n### Community Guidelines\n\n- **Be respectful** and constructive in discussions\n- **Help others** learn and contribute\n- **Follow the code of conduct**\n- **Ask questions** if you need help\n\n### Getting Help\n\n- **GitHub Issues**: For bugs and feature requests\n- **Discussions**: For questions and general help\n- **Documentation**: Check existing docs first\n- **Code examples**: Look at existing implementations\n\nThank you for contributing to the Jira MCP Server! 🚀\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! This project is open source and we value all contributions.\n\n### Quick Start for Contributors\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork**:\n   ```bash\n   git clone https://github.com/your-username/jira-mcp.git\n   cd jira-mcp\n   ```\n3. **Install dependencies**:\n   ```bash\n   npm install\n   ```\n4. **Create a branch** for your feature:\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n5. **Make your changes** and test them\n6. **Submit a pull request**\n\n### Ways to Contribute\n\n- 🐛 **Report bugs** using our [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)\n- ✨ **Request features** using our [feature request template](.github/ISSUE_TEMPLATE/feature_request.md)\n- 💻 **Submit code** improvements and new features\n- 📚 **Improve documentation** and examples\n- 🧪 **Add tests** for better coverage\n- 🌍 **Translate** documentation to other languages\n\n### Development Guidelines\n\n- Follow our [Contributing Guide](CONTRIBUTING.md)\n- Read our [Code of Conduct](CODE_OF_CONDUCT.md)\n- Use TypeScript for all new code\n- Add tests for new functionality\n- Update documentation as needed\n\n### Getting Help\n\n- 💬 **Discussions**: Use GitHub Discussions for questions\n- 🐛 **Issues**: Use GitHub Issues for bugs and feature requests\n- 📖 **Documentation**: Check the README and CONTRIBUTING.md\n\n## Publishing to npm\n\nTo publish this MCP server to npm for distribution:\n\n1. **Login to npm**:\n\n   ```bash\n   npm login\n   ```\n\n2. **Run the publish script**:\n\n   ```bash\n   ./publish.sh\n   ```\n\n3. **Or publish manually**:\n   ```bash\n   npm run build\n   npm publish\n   ```\n\nThe package will be available as `raalarcon-jira-mcp-server` and users can install it with:\n\n```bash\nnpx raalarcon-jira-mcp-server\n```\n\n## License\n\nMIT\n\n## Support\n\nTo report bugs or request features, please open an issue in the repository.\n\n---\n\n**Note**: This MCP server is designed to work with Jira Cloud. For Jira Server/Data Center, additional modifications are required for authentication and some endpoints.\n",
  "bytes": 28366,
  "sha": "7be47317becbf941a6d78c944d5b2c5d309f4f987dff620a51b9deb1764ec480",
  "repo_slug": "raalarcon9705/jira-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_raalarcon9705_jira_mcp_1800ebd0/readme"
}