Atlassian AI Toolkit

SDK, CLI y servidor MCP con prioridad de IA para Atlassian Jira y Confluence

Un monorepo de Bun que contiene un SDK tipado, una CLI nativa para agentes y un servidor MCP para las API de Atlassian Cloud.

Paquetes

Related MCP server: MCP Atlassian

Instalar la CLI

Recomendado: Binario independiente

Sin Node.js, sin npm, sin conflictos de PATH. Un solo archivo compilado con Bun.

macOS y Linux:

curl -fsSL https://raw.githubusercontent.com/spenserhale/atlassian-ai-toolkit/main/scripts/install.sh | sh

El script detecta tu sistema operativo y arquitectura, descarga el binario correspondiente de la última versión, verifica su SHA256 y lo instala en $HOME/.local/bin/atlassian.

Fija una versión con ATLASSIAN_AI_TOOLKIT_VERSION=v0.1.0 o cambia el directorio de instalación con ATLASSIAN_AI_TOOLKIT_INSTALL=$HOME/bin.

Windows: descarga atlassian-windows-x64.exe desde la última versión y colócalo en tu PATH.

Binarios disponibles: atlassian-linux-{x64,arm64}, atlassian-darwin-{x64,arm64} y atlassian-windows-x64.exe.

Actualizar

Actualiza un binario instalado en su lugar desde la última versión de GitHub (verifica el SHA256 primero):

atlassian upgrade            # apply the latest release
atlassian upgrade --dry-run  # only show current vs latest

En Windows, cierra las instancias en ejecución antes de actualizar, o vuelve a descargar el exe desde la última versión.

Alias de shell

Para comandos más cortos, añade estos alias a tu perfil de shell (~/.zshrc o ~/.bashrc):

alias jira='atlassian jira'
alias conf='atlassian confluence'

Entonces jira get PROJ-123 ejecuta atlassian jira get PROJ-123, y conf get 123456 ejecuta atlassian confluence get 123456.

Configurar

Establece las credenciales de Atlassian Cloud en tu shell:

export ATLASSIAN_SITE_URL="https://your-site.atlassian.net"
export ATLASSIAN_EMAIL="you@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"

Crea un token de API con alcance en https://id.atlassian.com/manage-profile/security/api-tokens.

Adjuntos

Sube uno o más archivos a un issue de Jira. Repite --file para múltiples subidas; el nombre de archivo almacenado es el nombre base del archivo y el tipo MIME se infiere de su extensión.

# Attach a single file
atlassian jira attach PROJ-123 --file ./screenshot.png

# Attach several files and print the API response
atlassian jira attach PROJ-123 --file ./error.log --file ./har-capture.har --json

La herramienta MCP jira_add_attachment acepta los mismos paths, además de un array files para contenido que un agente genera en línea (filename, content, encoding: utf8 | base64).

Las páginas de Confluence aceptan un adjunto por llamada:

atlassian confluence attachment upload --page 123456 --file ./diagram.png

Los adjuntos deben estar habilitados en el sitio, y las subidas están sujetas al tamaño máximo de adjunto del sitio.

Acciones destructivas

Eliminaciones con vista previa por defecto. La eliminación real requiere --force y un valor --confirm que coincida con el recurso obtenido.

# Preview the permanent Jira delete
atlassian jira delete PROJ-123

# Permanently delete the Jira issue
atlassian jira delete PROJ-123 --force --confirm PROJ-123

# Preview moving a Confluence page to trash
atlassian confluence delete 123456

# Move a Confluence page to trash
atlassian confluence delete 123456 --force --confirm 123456

# Permanently purge an already-trashed Confluence page
atlassian confluence delete 123456 --purge --force --confirm 123456

Primeros pasos desde el código fuente

# Install dependencies
bun install

# Build all packages
bun run build

# Run the CLI
bun run dev:cli -- --help

# Run the MCP server (stdio mode for Claude Desktop)
bun run dev:mcp

El token debe tener el alcance mínimo de permisos de Jira y Confluence necesarios para el flujo de trabajo. Las implementaciones de referencia de terceros viven en refs/, que está intencionalmente en gitignore para que este repositorio nunca incluya ni ejecute código no revisado con credenciales locales.

Arquitectura

packages/sdk/     <-- Types, API client, business logic (foundation)
    ^       ^
    |       |
packages/cli/   packages/mcp/
    (Stricli)    (FastMCP)

Tanto la CLI como el servidor MCP son envoltorios delgados sobre el SDK. Si la API REST cambia, actualizas el SDK y ambos consumidores reciben la corrección automáticamente.

Desarrollo

# Run tests across all packages
bun test

# Build a specific package
cd packages/sdk && bun run build

Añadir una nueva operación de API

1. Añade tipos a packages/sdk/src/types.ts

2. Añade el método del cliente a packages/sdk/src/client.ts

3. Añade un comando de CLI en packages/cli/src/commands/

4. Añade una herramienta MCP en packages/mcp/src/tools/

Las operaciones destructivas deben tener una ruta de vista previa por defecto y requerir una bandera explícita --force en la CLI o force: true en las herramientas MCP.