Jira

Integre com a API REST do Jira para gerenciar projetos, acompanhar issues e realizar análises.

GitHub
8
Experimente este MCPPatrocinado

Documentação

Servidor MCP Jira

smithery badge

Um servidor abrangente do Model Context Protocol que fornece integração de nível empresarial com a API REST do Jira, permitindo que assistentes de IA executem tarefas avançadas de gerenciamento de projetos, análises e planejamento estratégico.

Observação: Este é um fork mantido de 1broseidon/mcp-jira-server. Somos gratos pelo trabalho original e continuamos a desenvolver e aprimorar este projeto de forma independente. Todo o crédito pela implementação inicial vai para os autores originais.

🚀 Visão Geral dos Recursos

Este servidor transforma a funcionalidade básica do Jira em uma plataforma completa de gerenciamento de projetos com concorrência e segurança de thread de nível empresarial:

🔒 Concorrência Empresarial e Segurança de Thread

  • Suporte Multi-Clientes com Segurança de Thread: Múltiplas sessões do Claude Code podem usar o mesmo servidor simultaneamente com segurança
  • Isolamento de Estado Baseado em Sessão: Cada conexão de cliente recebe seu próprio estado de sessão isolado
  • Cache de Configuração por Sessão: Evita condições de corrida e melhora o desempenho
  • Gerenciamento Automático de Sessão: Tempo limite de sessão de 30 minutos com limpeza graciosa
  • Arquitetura Pronta para Produção: Projetada para ambientes empresariais de alta concorrência

Gerenciamento Principal de Issues

  • Criar, atualizar, excluir e gerenciar issues do Jira
  • Consulta avançada de issues com suporte a JQL
  • Pontos de história e gerenciamento de sprints
  • Vinculação de épicos e gerenciamento de hierarquia
  • Tratamento de comentários e anexos
  • 🆕 Suporte a Controle de Tempo: Controle de tempo nativo com campos original_estimate e remaining_estimate
  • 🆕 Transições de Fluxo de Trabalho: Gerenciamento completo de fluxo de trabalho com ferramentas de transição
  • Suporte a múltiplas instâncias: Trabalhe com vários ambientes Jira Cloud em uma única sessão

🏗️ Estrutura e Organização de Projetos

  • Gerenciamento de Componentes: Organize o trabalho por áreas de recursos e equipes
  • Rastreamento de Versões/Releases: Gerencie marcos de release e progresso
  • Descoberta de Projetos: Pesquise e analise projetos em toda a sua instância do Jira
  • Análise de Configuração: Entenda a configuração do projeto e otimize fluxos de trabalho

📊 Análises Avançadas e Insights

  • Rastreamento de Progresso: Progresso de componentes e versões com indicadores visuais
  • Análise de Fluxo de Trabalho: Entenda transições de status e gargalos
  • Desempenho da Equipe: Distribuição de carga de trabalho e rastreamento de atividades dos responsáveis
  • Planejamento Estratégico: Roadmap de alto nível e gerenciamento de planos

🔍 Consultas Avançadas e Automação

  • Pesquisa JQL: Execute consultas complexas com análises abrangentes
  • Filtros Salvos: Crie consultas reutilizáveis com permissões de compartilhamento
  • Pesquisa Entre Projetos: Descubra e analise projetos em toda a organização
  • Operações em Lote: Gerencie com eficiência múltiplas issues e projetos

📋 Referência Completa de Ferramentas

Ferramentas de Gerenciamento de Issues

create_issue

Cria novas issues no Jira com suporte abrangente a campos

  • Parâmetros: summary, description, type, epic_link, priority, story_points, labels, sprint, projectKey
  • Recursos: Detecta automaticamente campos de pontos de história, suporta atribuição de sprint

list_issues

Lista issues do projeto com opções de filtragem e ordenação

  • Parâmetros: status, epic_key, sortField, sortOrder, projectKey
  • Recursos: Separadores visuais, exibição de informações de sprint, ordenação baseada em classificação

update_issue

Atualiza issues existentes com suporte completo a campos, incluindo controle de tempo

  • Parâmetros: issue_key, summary, description, status, assignee, epic_link, priority, story_points, labels, sprint, rank_after_issue, rank_before_issue, original_estimate, remaining_estimate, custom_fields, projectKey
  • Recursos: Classificação de issues, gerenciamento de sprint, vinculação de épicos, resolução inteligente de responsáveis, suporte a controle de tempo, tratamento dinâmico de campos de componentes

get_issue

Recupera informações detalhadas da issue

  • Parâmetros: issue_key
  • Recursos: Metadados completos da issue, comentários, relacionamentos

delete_issue

Remove issues dos projetos com segurança

  • Parâmetros: issue_key

add_comment

Adiciona comentários a issues existentes

  • Parâmetros: issue_key, comment

get_transitions 🆕 v1.1.0

Obtém transições de fluxo de trabalho disponíveis para uma issue

  • Parâmetros: issue_key, working_dir, instance (opcional)
  • Recursos: Lista transições disponíveis, campos obrigatórios e IDs de transição
  • Caso de Uso: Entenda as opções de fluxo de trabalho antes de realizar transições

transition_issue 🆕 v1.1.0

Executa transições de fluxo de trabalho em issues (por exemplo, mover para "Em Andamento", "Concluído")

  • Parâmetros: issue_key, transition_id OU transition_name, comment (opcional), resolution (opcional), fields (opcional), working_dir, instance (opcional)
  • Recursos: Transição por nome ou ID, definição automática de resolução, adição de comentários
  • Caso de Uso: Automatize mudanças de status e progressão no fluxo de trabalho

list_custom_fields 🆕 v1.1.0

Descubra campos personalizados disponíveis para configuração

  • Parâmetros: working_dir, instance (opcional), projectKey (opcional), showSystemFields (opcional)
  • Recursos: Descoberta de campos, exemplos de configuração, classificação de tipos
  • Caso de Uso: Integração de novos usuários, configuração de campos, exploração do sistema

⚙️ Gerenciamento de Configuração e Instâncias

list_instances

Lista instâncias do Jira disponíveis e suas configurações

  • Recursos: Descoberta de instâncias, mapeamentos de projetos, orientação de configuração, validação de configuração
  • Casos de Uso: Verificação de configuração multi-instância, solução de problemas, planejamento de configuração

🏗️ Ferramentas de Estrutura de Projetos

create_component

Cria componentes de projeto baseados em recursos

  • Parâmetros: name, description, leadAccountId, assigneeType
  • Recursos: Atribuição de líder, roteamento automático de issues

list_components

Lista todos os componentes do projeto com detalhes

  • Recursos: Categorização de componentes, informações do líder, estatísticas de uso

get_component_progress

Análises abrangentes de componentes e rastreamento de progresso

  • Recursos: Percentuais de progresso, detalhamentos de status, análise de atividade recente, distribuição de carga de trabalho

create_version

Cria versões de projeto para gerenciamento de releases

  • Parâmetros: name, description, startDate, releaseDate, released, archived
  • Recursos: Gerenciamento de cronograma de release, rastreamento de marcos

list_versions

Lista versões do projeto com categorização

  • Recursos: Separação ativa/released/arquivada, informações de cronograma, avisos de atraso

get_version_progress

Análise detalhada do progresso e cronograma da versão

  • Recursos: Rastreamento de conclusão, detalhamentos de issues, monitoramento de prazos, insights de cronograma

🔍 Ferramentas de Consulta Avançada

search_issues_jql

Execute consultas JQL avançadas com análises abrangentes

  • Parâmetros: jql, maxResults, startAt, fields, expand, validateQuery
  • Recursos: Validação de consulta, análises de resultados, paginação, otimização de desempenho

search_projects

Descubra e pesquise projetos em toda a organização

  • Parâmetros: query, typeKey, categoryId, status, maxResults, startAt, expand
  • Recursos: Descoberta entre projetos, análise de metadados, categorização

create_filter

Crie filtros salvos para rastreamento consistente

  • Parâmetros: name, jql, description, favourite, sharePermissions
  • Recursos: Gerenciamento de permissões, colaboração em equipe, reutilização de consultas

📊 Ferramentas de Análise de Projetos

get_project_details

Informações abrangentes do projeto e análise de estrutura

  • Parâmetros: projectKey, expand
  • Recursos: Metadados completos, resumos de componentes/versões, análise de permissões

get_project_statuses

Análise de configuração de fluxo de trabalho e status

  • Recursos: Categorização de status, insights de otimização de fluxo de trabalho, mapeamento de transições

get_issue_types

Descoberta de tipos de issue e análise de configuração

  • Recursos: Hierarquia de tipos, requisitos de campos, diretrizes de uso

detect_project_fields

🆕 Descoberta de Configuração de Campos - Essencial para integração de novos usuários

  • Parâmetros: working_dir, projectKey, instance (opcional)
  • Propósito: Detectar automaticamente IDs de campos personalizados necessários para a configuração do projeto
  • Saída: Trechos de configuração prontos para copiar para .jira-config.json
  • Detecta: IDs de campos de Pontos de História, Sprint e Link de Épico usando heurísticas inteligentes
  • Multi-Instância: Suporte completo para múltiplos ambientes Jira
  • Ciente de Sessão: Fornece orientação apenas no primeiro acesso ao projeto por sessão
  • Caso de Uso: Elimina a busca manual de IDs de campos na interface administrativa do Jira

🌉 Ferramentas de Integração Entre Servidores

jira_health_check

🆕 Monitoramento de Saúde do Servidor - Monitore o status do servidor Jira e a integração entre servidores

  • Propósito: Verificar saúde do servidor, tempo de atividade e conectividade entre servidores
  • Saída: Status de saúde abrangente, detalhes de configuração, operações suportadas
  • Entre Servidores: Mostra status de integração com servidores MCP do Confluence
  • Informações de Sessão: Contagem de sessões em tempo real e monitoramento de atividades

confluence_health_check

🆕 Verificação de Saúde Entre Servidores - Monitore a conectividade do servidor Confluence a partir do Jira

  • Propósito: Verificar o status da integração Jira-para-Confluence e suas capacidades
  • Saída: Status da conexão, verificação de endpoints, configuração de integração

🎯 Ferramentas de Planejamento Estratégico

list_plans

Gerenciamento de planos estratégicos (recurso Jira Premium)

  • Recursos: Rastreamento de roadmap de alto nível, análise de cronograma, métricas de equipe

Ferramentas de Gerenciamento de Sprints e Épicos

create_sprint

Cria novos sprints com metas e cronogramas

  • Parâmetros: name, goal, startDate, endDate, boardId, projectKey

update_sprint

Modifica detalhes e cronograma de sprints existentes

  • Parâmetros: sprintId, name, goal, startDate, endDate, state

get_sprint_details

Progresso abrangente de sprint e análises

  • Recursos: Rastreamento de issues, insights de velocidade, dados de burndown

move_issues_to_sprint

Atribuição em lote de sprints para issues

  • Parâmetros: sprintId, issueKeys

complete_sprint

Fecha sprints ativos e lida com o trabalho restante

  • Parâmetros: sprintId

create_epic

Cria novos épicos para organização de grandes recursos

  • Parâmetros: name, summary, description, priority, labels, projectKey

create_epic_with_issues

Cria um épico com issues vinculadas em uma única operação ⚡

  • Parâmetros: epic (name, summary, description, priority, labels), issues (matriz de dados de issues)
  • Recursos: Reduz chamadas de API, garante vinculação adequada, tratamento abrangente de erros
  • Benefícios: Operação atômica, valida todos os tipos de issues, resolução automática de responsáveis

update_epic_details

Atualiza propriedades e status do épico

  • Parâmetros: epicKey, name, summary, color, done

rank_epics e rank_issues

Gerencia a priorização de épicos e issues

  • Recursos: Classificação relativa, gerenciamento de prioridades

bulk_update_issues

Atualiza com eficiência múltiplas issues simultaneamente

  • Parâmetros: issueKeys, updates (status, assignee, labels, priority, sprint, storyPoints)
  • Recursos: Operações em lote, tratamento de erros por issue, resolução inteligente de responsáveis

Ferramentas de Board e Relatórios

list_boards

Lista boards Kanban e Scrum disponíveis

  • Recursos: Categorização de boards, associação a projetos

get_board_configuration

Analisa a configuração do board e a configuração de colunas

  • Recursos: Mapeamento de fluxo de trabalho, análise de colunas

get_sprint_report, get_velocity_chart_data, get_burndown_chart_data

Análises avançadas de sprint e desempenho da equipe

  • Recursos: Rastreamento de velocidade, análise de burndown, insights de desempenho

🛠️ Configuração e Instalação

Pré-requisitos

  1. Conta Jira: Com acesso à API e permissões apropriadas
  2. Token de API: Gerado em Configurações da Conta Atlassian
  3. Acesso ao Projeto: Permissões de leitura/escrita para os projetos de destino

Instalação

Instalando via npm

npm install -g jira-server

Após a instalação, o comando jira-server estará disponível globalmente.

Instalando via Smithery

Para instalar o Jira Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install jira-server --client claude

Instalação Manual

  1. Instale as dependências:
# Clone and install dependencies
npm install

# Build the server
npm run build

Configuração

1. Configuração Multi-Instância (Recomendado)

O Jira MCP Server suporta múltiplas instâncias do Jira em uma única sessão do Claude Desktop. Isso permite alternar facilmente entre diferentes ambientes do Jira Cloud com base nas chaves do projeto.

Crie o .jira-config.json no seu diretório de trabalho:

{
  "instances": {
    "primary": {
      "email": "your-email@company.com",
      "apiToken": "your-api-token-here",
      "domain": "your-domain",
      "projects": ["PROJ", "DEV", "OPS"]
    },
    "secondary": {
      "email": "your-email@otherdomain.com", 
      "apiToken": "your-other-api-token",
      "domain": "other-domain"
    }
  },
  "projects": {
    "PROJ": {
      "instance": "primary",
      "storyPointsField": "customfield_10016",
      "sprintField": "customfield_10020",
      "epicLinkField": "customfield_10014"
    },
    "DEV": {
      "instance": "primary",
      "storyPointsField": "customfield_10016"
    },
    "OTHER": {
      "instance": "secondary",
      "storyPointsField": "customfield_10020"
    }
  },
  "defaultInstance": "primary"
}

Lógica de Seleção de Instância

O servidor seleciona automaticamente a instância correta do Jira usando esta ordem de prioridade:

  1. Substituição Explícita: Parâmetro manual instance em chamadas de ferramentas
  2. Mapeamento de Projetos: Configuração direta de projeto para instância na seção projects
  3. Listas de Projetos da Instância: Projetos listados nos arrays projects da instância
  4. Instância Padrão: Recurso ao parâmetro defaultInstance
  5. Instância Única: Use a única instância disponível se apenas uma estiver configurada

2. Configuração Legada de Instância Única (Ainda Suportada)

Para configurações de instância única do Jira, use o formato simplificado:

{
  "projectKey": "YOUR_PROJECT_KEY",
  "storyPointsField": "customfield_XXXXX",  // Optional: auto-detected
  "sprintField": "customfield_YYYYY",       // Optional: auto-detected  
  "epicLinkField": "customfield_ZZZZZ"      // Optional: auto-detected
}

3. Configuração do Servidor MCP

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server",
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token", 
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": true
    }
  }
}

Para a Extensão VS Code Cline (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server", 
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": [
        "create_issue", "list_issues", "update_issue", "get_issue", "delete_issue", "add_comment",
        "list_instances", "create_component", "list_components", "get_component_progress",
        "create_version", "list_versions", "get_version_progress", 
        "search_issues_jql", "search_projects", "create_filter",
        "get_project_details", "get_project_statuses", "get_issue_types",
        "list_plans", "create_sprint", "update_sprint", "get_sprint_details",
        "create_epic", "update_epic_details", "bulk_update_issues"
      ]
    }
  }
}

Para OpenCode (opencode.json no projeto ou ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["node", "build/index.js"],
      "enabled": true,
      "environment": {
        "JIRA_CONFIG_PATH": "./config/.jira-config.json"
      }
    }
  }
}

JIRA_CONFIG_PATH pode ser absoluto, relativo ao arquivo de configuração, ou usar ~ para o diretório inicial. Se você registrar o servidor com um nome MCP diferente, defina JIRA_MCP_KEY para esse valor para que o carregador possa localizar o bloco correto.

4. Configuração de Integração Entre Servidores

Para integração entre servidores dos MCP servers do Jira e do Confluence, você precisará instalar e configurar o servidor complementar confluence-cloud-mcp junto com este servidor do Jira.

Adicione a configuração da API do Confluence ao seu .jira-config.json:

{
  "instances": {
    "primary": {
      "email": "your-email@company.com",
      "apiToken": "your-jira-api-token",
      "domain": "your-jira-domain",
      "projects": ["PROJ", "DEV"]
    }
  },
  "confluence": {
    "instances": {
      "primary": {
        "email": "your-email@company.com",
        "apiToken": "your-confluence-api-token",
        "domain": "your-confluence-domain"
      }
    },
    "defaultInstance": "primary"
  },
  "defaultInstance": "primary"
}

Isso permite ferramentas como jira_health_check, confluence_health_check e recursos de criação de documentos entre servidores.

Benefícios da Integração Entre Servidores:

  • Vinculação Bidirecional: Crie links inteligentes entre issues do Jira e páginas do Confluence
  • Documentação Automatizada: Gere páginas do Confluence diretamente de issues do Jira (épicos, funcionalidades, etc.)
  • Monitoramento de Saúde: Monitore ambos os servidores e seu status de integração
  • Fluxo de Trabalho Unificado: Alterne facilmente entre rastreamento de issues e documentação na mesma sessão de IA

Para instruções completas de configuração e recursos avançados entre servidores, consulte a documentação do confluence-cloud-mcp.

🎯 Exemplos de Uso

Gerenciamento Multi-Instância

Descoberta de Instância

// List all configured instances and project mappings
await list_instances({ working_dir: "/path/to/config" });

Seleção Automática de Instância

// Automatically uses correct instance based on project key
await create_issue({
  working_dir: "/path/to/config",
  projectKey: "HWY",  // Routes to Highway instance
  summary: "New feature request",
  description: "Implement user dashboard",
  type: "Task"
});

await create_issue({
  working_dir: "/path/to/config", 
  projectKey: "ONVX", // Routes to Onvex instance
  summary: "Security update",
  description: "Update authentication system",
  type: "Task"
});

Substituição Manual de Instância

// Explicitly specify instance for any tool call
await create_issue({
  working_dir: "/path/to/config",
  instance: "highway",  // Force use of Highway instance
  projectKey: "PROJ",
  summary: "Cross-instance task",
  type: "Task"
});

Fluxo de Trabalho de Planejamento de Projetos

// 1. Analyze project structure
await get_project_details({ projectKey: "PROJ" });

// 2. Create components for feature organization  
await create_component({
  name: "Authentication API",
  description: "User authentication and authorization features",
  leadAccountId: "user123"
});

// 3. Create release version
await create_version({
  name: "v2.0.0", 
  description: "Major feature release",
  releaseDate: "2024-06-30"
});

// 4. Search for related work
await search_issues_jql({
  jql: "project = PROJ AND component = 'Authentication API' AND fixVersion = 'v2.0.0'"
});

Rastreamento de Progresso e Análises

// Component progress analysis
await get_component_progress({ componentId: "10123" });

// Version release tracking  
await get_version_progress({ versionId: "10456" });

// Sprint performance metrics
await get_sprint_report({ boardId: 1, sprintId: 23 });

Consulta Avançada e Automação

// Create saved filter for team tracking
await create_filter({
  name: "Backend Team Sprint Work",
  jql: "assignee in (dev1, dev2, dev3) AND sprint in openSprints()",
  sharePermissions: [{ type: "project", projectId: "10000" }]
});

// Bulk update for sprint planning
await bulk_update_issues({
  issueKeys: ["PROJ-1", "PROJ-2", "PROJ-3"],
  updates: { sprint: "Sprint 5", storyPoints: 3 }
});

🆕 Gerenciamento de Tempo e Fluxo de Trabalho (v1.1.0)

Exemplos de Rastreamento de Tempo

// Set time estimates on issue creation
await create_issue({
  working_dir: "/path/to/config",
  projectKey: "PROJ",
  summary: "Implement user authentication",
  description: "Build OAuth2 integration",
  type: "Task",
  story_points: 5,
  original_estimate: "2w",  // 2 weeks
  // Time automatically displayed in get_issue
});

// Update time tracking on existing issues
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  original_estimate: "1w 2d",     // 1 week 2 days
  remaining_estimate: "3d 4h"     // 3 days 4 hours
});

// Use with component assignment
await update_issue({
  working_dir: "/path/to/config", 
  issue_key: "PROJ-124",
  custom_fields: {
    "Component": "Security"  // Automatically converts to [{name: "Security"}]
  },
  original_estimate: "5d"
});

Exemplos de Transição de Fluxo de Trabalho

// Discover available transitions for an issue
await get_transitions({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123"
});

// Transition issue to "In Progress" with comment
await transition_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  transition_name: "Start Progress",  // or transition_id: "21"
  comment: "Beginning work on this issue"
});

// Complete issue with resolution
await transition_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123", 
  transition_name: "Done",
  comment: "Implementation completed and tested",
  resolution: "Fixed"
});

// Workflow automation - bulk transition
const issueKeys = ["PROJ-101", "PROJ-102", "PROJ-103"];
for (const key of issueKeys) {
  await transition_issue({
    working_dir: "/path/to/config",
    issue_key: key,
    transition_name: "Ready for Review"
  });
}

Exemplos de Descoberta de Campos

// Discover all available fields for configuration
await list_custom_fields({
  working_dir: "/path/to/config",
  instance: "primary",
  projectKey: "PROJ",  // Optional: project-specific fields
  showSystemFields: false  // Show only custom fields
});

// Get ready-to-copy configuration snippets
// Output includes examples like:
// - Story Points: customfield_10036
// - Sprint: customfield_10020  
// - Components: Built-in system field

Épico com Issues - Criação em Massa ⚡

A nova ferramenta create_epic_with_issues permite criar um épico e várias issues vinculadas em uma única operação:

// Create epic with linked issues in one operation
await create_epic_with_issues({
  working_dir: "/path/to/config",
  projectKey: "PROJ",
  epic: {
    name: "User Authentication System",
    summary: "Complete user authentication and authorization",
    description: "Implement secure user authentication with OAuth2 and role-based access control",
    priority: "High",
    labels: ["security", "authentication"]
  },
  issues: [
    {
      summary: "Design OAuth2 integration",
      description: "Research and design OAuth2 flow for user authentication",
      type: "Task",
      story_points: 5,
      assignee: "john.doe@company.com",
      priority: "High"
    },
    {
      summary: "Implement user registration API",
      description: "Create REST API endpoints for user registration",
      type: "Story",
      story_points: 8,
      assignee: "Jane Smith",
      labels: ["api", "backend"]
    },
    {
      summary: "Build login form UI",
      description: "Create responsive login form with validation",
      type: "Task", 
      story_points: 3,
      assignee: "mike.wilson@company.com",
      priority: "Medium"
    }
  ]
});

Benefícios da Criação em Massa:

  • Menos Chamadas de API: Operação única em vez de várias chamadas separadas
  • Vinculação Automática: Todas as issues são automaticamente vinculadas ao épico
  • Operação Atômica: Ou todos os itens são criados com sucesso ou nenhum é
  • Validação Abrangente: Valida o épico e todas as issues antes da criação
  • Tratamento de Erros Aprimorado: Feedback detalhado sobre quaisquer falhas de validação
  • Resolução Inteligente de Responsáveis: Resolve automaticamente nomes/e-mails de usuários para IDs de conta

Exemplos de Gerenciamento de Responsáveis

O MCP Jira Server fornece resolução inteligente de responsáveis que aceita nomes de exibição, e-mails ou IDs de conta e os resolve automaticamente para a conta correta do Jira.

Atribuição de Issue Individual

// Assign by display name (most common)
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-123",
  assignee: "Esther Yang"  // Resolves to account ID automatically
});

// Assign by email address
await update_issue({
  working_dir: "/path/to/config", 
  issue_key: "PROJ-124",
  assignee: "esther.yang@company.com"
});

// Unassign issue
await update_issue({
  working_dir: "/path/to/config",
  issue_key: "PROJ-125", 
  assignee: "unassigned"  // or null, or empty string
});

Operações de Atribuição em Massa

// Assign multiple issues to one person
await bulk_update_issues({
  working_dir: "/path/to/config",
  issueKeys: ["PROJ-101", "PROJ-102", "PROJ-103"],
  updates: {
    assignee: "Rob Sherman",  // Intelligent name resolution
    sprint: "Sprint 10"
  }
});

// Unassign multiple issues
await bulk_update_issues({
  working_dir: "/path/to/config",
  issueKeys: ["PROJ-201", "PROJ-202"],
  updates: {
    assignee: "unassigned"
  }
});

Lógica de Resolução de Responsáveis

O sistema lida automaticamente com a resolução de usuários usando esta ordem de prioridade:

  1. Correspondência Exata de Nome de Exibição: "Esther Yang" → Correspondência exata nos usuários do Jira
  2. Correspondência de Endereço de E-mail: "esther.yang@company.com" → Correspondência por e-mail
  3. Correspondência Parcial de Nome: "Esther" → Correspondência parcial única encontrada
  4. Passagem de ID de Conta: Se já for um ID de conta, usa como está

Tratamento de Erros:

  • Nenhuma Correspondência Encontrada: Mensagem de erro clara com nomes semelhantes sugeridos
  • Múltiplas Correspondências: Lista todas as possibilidades e pede mais especificidade
  • Usuários Inválidos: Valida se o usuário existe e está ativo

Valores Especiais:

  • "unassigned", null ou "" → Desatribui a issue
  • IDs de conta que começam com padrões específicos são usados diretamente

🔧 Recursos Avançados

Detecção Inteligente de Campos

  • Detecta automaticamente campos personalizados (Story Points, Sprint, Epic Link)
  • Fornece orientação de configuração nos logs de depuração
  • Suporta substituição manual de ID de campo

Operações Entre Projetos

  • Pesquise e gerencie issues em vários projetos
  • Recursos de descoberta e análise de projetos
  • Relatórios e insights em toda a organização

Otimização de Desempenho

  • Operações em lote eficientes para atualizações em massa
  • Suporte a paginação para grandes conjuntos de dados
  • Validação de consultas e sugestões de otimização

Análises e Relatórios Ricos

  • Indicadores visuais de progresso e porcentagens
  • Análise de cronograma com rastreamento de prazos
  • Desempenho da equipe e distribuição de carga de trabalho
  • Análise de tendências históricas e insights

🐛 Solução de Problemas

Registro de Depuração

Monitore a atividade do servidor com logs detalhados:

# For Claude Desktop (macOS)
tail -f ~/Library/Logs/Claude/mcp-server-jira.log

# For development
npm run watch  # Auto-rebuild on changes

Problemas Comuns

Problemas de Detecção de Campos

  • Novos Usuários: Use a ferramenta detect_project_fields para descobrir automaticamente os IDs dos campos
  • Campos Ausentes: As ferramentas agora fornecem orientação automática no primeiro acesso ao projeto por sessão
  • Verifique os logs de depuração para mensagens "Found [Field] field"
  • Verifique os IDs de campos personalizados na administração do projeto
  • Garanta permissões de campo adequadas

Desempenho de Consultas

  • Use validateQuery: true para testes de JQL
  • Implemente paginação para grandes conjuntos de resultados
  • Monitore a complexidade das consultas nos logs de depuração

Problemas de Configuração

  • O servidor verifica vários locais de configuração em ordem:
    1. Parâmetro do diretório de trabalho (working_dir)
    2. Diretório de trabalho atual (process.cwd())
    3. Diretório de instalação do servidor
  • Verifique o formato e as permissões do .jira-config.json

Problemas de Configuração Multi-Instância

  • Instância Não Encontrada: Use list_instances para verificar nomes e configurações de instância
  • Instância Errada Selecionada: Verifique os mapeamentos de projeto na seção projects e os arrays projects da instância
  • Falhas de Autenticação: Verifique se cada instância tem e-mail, apiToken e domínio corretos
  • Conflitos de Chave de Projeto: Garanta que as chaves de projeto sejam únicas entre as instâncias ou mapeadas corretamente
  • Validação de Configuração: Use list_instances para verificação de configuração e orientação de solução de problemas

Limitação de Taxa da API

  • Implemente atrasos entre operações em massa
  • Use operações em lote quando disponíveis
  • Monitore os cabeçalhos de resposta da API para status de limite de taxa

Mensagens de Erro Aprimoradas 🎯

O servidor agora fornece mensagens de erro detalhadas e amigáveis com orientação específica para solução de problemas:

Erros de Validação de Campos

  • Problemas de Campo Detalhados: Explicações claras para cada problema de campo
  • Nomes Amigáveis: IDs de campos técnicos convertidos em nomes legíveis (por exemplo, customfield_10011 → Epic Name)
  • Orientação Específica de Campo: Conselhos direcionados para problemas comuns de campo

Solução de Problemas Contextual

  • Problemas de Permissão: Etapas específicas para resolver problemas de acesso
  • Problemas de Configuração: Orientação para configuração de campos e projetos
  • Falhas de Validação: Explicação clara do que deu errado e como corrigir

Exemplo de Erro Aprimorado

# Invalid Request: epic creation failed

The request contains invalid data or violates Jira field requirements.

## Field Issues
- **Epic Name:** Field 'customfield_10011' is not supported for issue type 'Epic' in this project
- **Priority:** Priority 'Critical' is not available. Available priorities: Highest, High, Medium, Low, Lowest

## Troubleshooting Steps
1. Epic Name field may not be available in this project
2. Try creating the epic without the Epic Name field  
3. Check available priorities for this project
4. Common values: Highest, High, Medium, Low, Lowest

Códigos de Erro e Resolução

Tipo de ErroCausas ComunsResolução
401 UnauthorizedToken de API ou e-mail inválidoVerifique as credenciais na configuração do MCP
403 ForbiddenPermissões de projeto insuficientesVerifique funções e permissões do projeto no Jira
404 Not FoundChave de projeto ou issue inválidaVerifique se o projeto/issue existe e está acessível
400 Bad RequestValores de campo ou transições inválidosAprimorado: Validação detalhada de campos com orientação específica

🚀 Desenvolvimento

Configuração de Desenvolvimento

# Install dependencies
npm install

# Development with auto-rebuild  
npm run watch

# Run tests
npm test

# Build for production
npm run build

Testes

O projeto inclui testes Jest abrangentes com suporte a ESM e TypeScript:

# Run all tests
npm test

# Run tests in watch mode during development
npm run test:watch

# Generate test coverage report
npm run test:coverage

Estrutura de Testes:

  • tests/unit/ - Testes unitários para módulos individuais (config, formatação, conversão ADF)
  • tests/integration/ - Testes de integração para funcionalidade do servidor
  • Usa Jest com ts-jest para suporte a ESM TypeScript
  • Os testes são executados automaticamente no pipeline de CI/CD

Recursos Principais:

  • Testes de módulos ESM com imports de extensão .js
  • Compilação TypeScript via ts-jest
  • Módulos VM experimentais do Node.js para compatibilidade ESM
  • Cobertura abrangente para utilitários e funcionalidade principal

Contribuindo

  1. Detecção de Campos: Adicione suporte a novos campos personalizados em src/config/config.ts
  2. Desenvolvimento de Ferramentas: Siga os padrões existentes em src/tools/
  3. Extensões de API: Estenda o cliente base em src/jira-client.ts
  4. Testes: Adicione testes abrangentes para novas funcionalidades

📈 Recursos Empresariais

Integração de Planejamento Estratégico

  • Vincula o trabalho tático a iniciativas estratégicas
  • Relatórios e insights em nível de portfólio
  • Rastreamento de dependências entre projetos

Análises Avançadas

  • Métricas personalizadas e rastreamento de KPIs
  • Benchmarking de desempenho da equipe
  • Previsão preditiva de entrega

Otimização de Fluxo de Trabalho

  • Identificação e resolução de gargalos
  • Recomendações de melhoria de processos
  • Descoberta de oportunidades de automação

Segurança e Conformidade

  • Trilha de auditoria e rastreamento de alterações
  • Análise e otimização de permissões
  • Governança de dados e relatórios de conformidade

Transforme sua experiência com o Jira de rastreamento básico de issues para uma plataforma abrangente de gerenciamento de projetos e planejamento estratégico.