Servidor MCP de JIRA

Este es un servidor de Model Context Protocol (MCP) que proporciona herramientas para interactuar con JIRA. Permite obtener tickets de sprints activos y obtener información detallada de tickets a través de la interfaz MCP.

Características

El servidor proporciona las siguientes herramientas:

1. list-sprint-tickets: Obtiene todos los tickets del sprint activo para un proyecto dado

   • Parámetro requerido: projectKey (string)

2. get-ticket-details: Obtiene información detallada de un ticket específico

   • Parámetro requerido: issueKey (string)

3. add-comment: Añade un comentario a un ticket específico

   • Parámetro requerido: issueKey (string)

   • O bien comment (string) o filePath (string) — ver Editar contenido desde un archivo

   • Parámetro opcional: commentFormat — plain (predeterminado), wiki, markdown o adf

4. link-tickets: Enlaza dos tickets con una relación 'relates to'

   • Parámetro requerido: sourceIssueKey (string)

   • Parámetro requerido: targetIssueKey (string)

5. update-description: Actualiza la descripción de un ticket específico

   • Parámetro requerido: issueKey (string)

   • O bien description (string) o filePath (string) — ver Editar contenido desde un archivo

   • Parámetro opcional: descriptionFormat — plain (predeterminado), wiki, markdown o adf

6. list-child-issues: Obtiene todos los issues secundarios de un ticket padre

   • Parámetro requerido: parentKey (string)

7. create-sub-ticket: Crea un sub-ticket (issue secundario) para un ticket padre

   • Parámetro requerido: parentKey (string)

   • Parámetro requerido: summary (string)

   • Parámetro opcional: description (string) o filePath (string) — ver Editar contenido desde un archivo

   • Parámetro opcional: issueType (string) - El nombre del tipo de issue de sub-tarea (por ejemplo, 'Sub-task')

Related MCP server: mcp-jira

Instalación

1. Instala las dependencias:

   npm install

2. Compila el código TypeScript:

Este paso solo es necesario para Cline en Windows, que actualmente tiene un problema al ejecutar npx

npm run build

3. Configura los ajustes de MCP en el archivo de configuración de tu aplicación Claude (normalmente ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS o %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json en Windows):

Configuración para Claude:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuración para Cline:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Configuración

Necesitarás configurar las siguientes variables de entorno en tus ajustes de MCP:

1. JIRA_HOST: Tu URL de dominio de Atlassian (por ejemplo, https://your-company.atlassian.net)

2. JIRA_EMAIL: Tu correo electrónico de cuenta de JIRA

3. JIRA_API_TOKEN: Tu token de API de JIRA

   • Puedes generar un token de API desde tu Configuración de cuenta de Atlassian

Uso

Una vez configurado, puedes usar las herramientas a través de la interfaz MCP en Claude:

Listar tickets del sprint

Para obtener todos los tickets del sprint activo de un proyecto:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

Obtener detalles de un ticket

Para obtener información detallada de un ticket específico:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

Editar contenido desde un archivo

update-description, update-comment, add-comment, create-ticket y create-sub-ticket aceptan filePath en lugar de texto en línea. Esto está pensado para contenido largo: mantén la fuente en un archivo, edita ese archivo y vuelve a enviarlo; no es necesario volver a publicar todo el cuerpo a través de la llamada a la herramienta cada vez. En las dos herramientas de creación, la descripción sigue siendo opcional, por lo que omitir ambas sigue siendo válido.

El formato se deduce de la extensión, por lo que descriptionFormat / commentFormat se pueden omitir:

Pasar el formato explícitamente anula la extensión, que también es la forma de usar un archivo con cualquier otra extensión. Las rutas son absolutas o relativas al directorio de trabajo del servidor.

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

Un archivo vacío se rechaza en lugar de borrar la descripción o el comentario existentes, y pasar tanto el texto en línea como filePath es un error.

Modificar contenido existente

Para cambiar parte de una descripción o comentario que ya existe, expórtalo primero con export-content, edita el archivo y vuelve a subirlo; no es necesario reescribir todo:

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

La exportación informa si ese contenido es seguro para volver a subirlo como markdown. Jira almacena el contenido como ADF, y construcciones como paneles, menciones, píldoras de estado, medios, tablas, listas de tareas y expansiones no tienen equivalente en markdown; volver a subir markdown los eliminaría silenciosamente. Cuando hay alguno, la herramienta advierte y los lista; exporta con "format": "adf" en su lugar y modifica el JSON, que siempre se conserva exactamente (los archivos .json se reconocen como ADF al subirlos).

Omite filePath para obtener el contenido de vuelta en línea en lugar de escribir un archivo. Los IDs de comentarios se muestran mediante get-ticket-details.

Versiones de contenido (concurrencia optimista)

update-description y update-comment requieren expectedVersion siempre que el contenido que se reemplaza no esté vacío: la versión en la que se basó la edición. Si el contenido cambió en Jira desde entonces, la actualización se rechaza en lugar de descartar silenciosamente ese cambio: el mismo bloqueo que Confluence obtiene de sus números de versión de página.

Jira no tiene un número de versión propio, y la marca de tiempo updated de un issue no es un sustituto: se mueve con cualquier cambio en el issue, por lo que las transiciones, etiquetas y nuevos comentarios rechazarían parches de descripción que nunca entraron en conflicto. Por lo tanto, la versión es un hash del contenido en sí (v1-…), de modo que cambia exactamente cuando cambia lo que se está parcheando.

Las versiones provienen de export-content y de get-ticket-details, que informa Description version: y una version: para cada comentario, por lo que una pequeña edición en línea no necesita un viaje de ida y vuelta de exportación.

Escribir una descripción por primera vez no necesita versión. Omitir expectedVersion es en sí mismo la afirmación de que "aún no hay nada aquí", que el servidor comprueba: la escritura se realiza cuando la descripción sigue vacía, y se rechaza — nombrando la versión ahora en Jira — cuando alguien escribió una mientras tanto. Así que el bloqueo cubre también la primera escritura, sin que el llamador tenga que obtener la versión del contenido vacío.

Pasa "force": true para omitir la comprobación y sobrescribir sin importar.

Desarrollo

El servidor está escrito en TypeScript y utiliza:

• @modelcontextprotocol/sdk para la implementación del servidor MCP

• jira.js para la integración con la API de JIRA

Scripts recomendados:

• Compilar una vez: npm run build

• Compilar y observar: npm run build:watch

• Solo verificación de tipos: npm run typecheck

• Ejecución de desarrollo con observación: npm run start:dev

• Ejecutar servidor compilado: npm start

• Verificación de formato: npm run fmt:check

• Escritura de formato: npm run fmt

Flujo de trabajo típico:

1. Haz cambios en jira.ts

2. Ejecuta npm run start:dev durante el desarrollo, o npm run build y luego npm start para una ejecución compilada

3. Reinicia tu cliente MCP si es necesario para aplicar los cambios

Manejo de errores

El servidor incluye manejo de errores para:

• Credenciales de JIRA no válidas

• Sprints activos faltantes

• Claves de proyecto o de issue no válidas

• Errores de red

Los mensajes de error se devolverán en la respuesta de la herramienta.