a2atlassian

Agent: "What's the status of PROJ-42? Add a comment with the progress update."
  ↓
a2atlassian → get issue, add comment, transition to In Progress
  ↓
Agent: "Done — PROJ-42 updated and moved to In Progress."

¿Por qué a2atlassian?

Los servidores MCP de Atlassian existentes (Rovo, sooperset) requieren Docker, archivos .env y puentes mcp-remote. Vuelcan 72 herramientas en el contexto del agente y tienen peculiaridades conocidas que fallan silenciosamente. a2atlassian soluciona todo eso:

• Sin Docker — pip install a2atlassian y listo

• Conexiones preconfiguradas — define proyectos en .mcp.json con --register, el agente funciona inmediatamente

• Solo lectura por defecto — el acceso de escritura es opcional por conexión

• Alcance de conexión — --scope limita qué proyectos puede ver un agente

• Salida compacta — TSV para listas (30-60% menos tokens), JSON para entidades individuales

• Carga dinámica de herramientas — los clientes MCP que admiten herramientas diferidas (p. ej., Claude Code) cargan las herramientas bajo demanda, manteniendo el contexto ligero

• Enriquecimiento de errores — los nombres de campo incorrectos reciben sugerencias, los errores tipográficos en JQL reciben correcciones, las peculiaridades se corrigen automáticamente

• Los secretos permanecen en el entorno — ${ATLASSIAN_TOKEN} en las configuraciones, se expande solo en tiempo de ejecución

Inicio rápido

# Recommended — installs globally as a CLI tool
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

Como servidor MCP (recomendado)

Claude Code (con conexión preconfigurada):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \
  --register myproject https://mysite.atlassian.net user@company.com '${ATLASSIAN_TOKEN}'

Claude Code (mínimo — el agente llama a login bajo demanda):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / cualquier cliente MCP (.mcp.json):

{
  "mcpServers": {
    "a2atlassian": {
      "command": "uvx",
      "args": [
        "--from", "a2atlassian", "a2atlassian-mcp",
        "--register", "myproject", "https://mysite.atlassian.net",
        "user@company.com", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

Proyectos múltiples:

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "user@a.com", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "user@b.com", "${TOKEN_B}"
  ]
}

Conexiones con alcance (limita al agente a proyectos guardados específicos):

{
  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]
}

--register crea conexiones efímeras en memoria (duración del proceso, no se escriben archivos). --scope filtra qué conexiones guardadas son visibles. Ambos limitan el radio de acción.

Como CLI

# Save a connection (validates by calling /myself)
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN"

# Enable writes
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

# List / remove connections
a2atlassian connections
a2atlassian logout -p myproject

Herramientas MCP

Gestión de conexiones

Jira — Lectura

Jira — Escritura (requiere conexión de lectura y escritura)

Formatos de salida

Todas las herramientas aceptan un parámetro format:

Las respuestas de lista utilizan un formato compacto estilo TSV (fila de encabezado + valores separados por tabulaciones) inspirado en TOON. Este es el mismo enfoque que utiliza a2db: los nombres de las columnas aparecen una vez, luego solo los valores. Para un resultado de búsqueda de 50 incidencias, esto suele ahorrar un 40-60% de tokens en comparación con JSON.

Ejemplo de TSV (resultados de búsqueda):

# search (23 results, 50ms, truncated: False)
key	summary	assignee	status
PROJ-142	Fix auth timeout	Alice Smith	In Progress
PROJ-141	Add search filters	Bob Jones	To Do

Ejemplo de JSON (incidencia individual):

{
  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},
  "count": 1,
  "truncated": false,
  "time_ms": 85
}

Enriquecimiento de errores

Cuando algo falla, a2atlassian le dice al agente qué hacer:

Field 'asignee' does not exist
Did you mean: assignee?

Connection 'myproject' is read-only.
Run: a2atlassian login -p myproject --read-only false

Peculiaridades manejadas automáticamente:

• El responsable requiere un nombre para mostrar (no IDs de cuenta 712020:) — detectado automáticamente con una pista

• El campo principal debe ser una cadena simple — {"key": "PROJ-14"} normalizado a "PROJ-14" silenciosamente

• La conversión de tipo de incidencia no es compatible a través de la API — se proporcionan instrucciones claras de la interfaz de usuario de Jira

Seguridad

Solo lectura por defecto

Cada conexión comienza como solo lectura. Las herramientas de escritura verifican el indicador de conexión antes de ejecutarse:

Connection 'myproject' is read-only.
Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

El operador humano controla el acceso de escritura, no el agente.

Almacenamiento de credenciales

Las conexiones guardadas a través de login van a ~/.config/a2atlassian/connections/ como archivos TOML:

• Permisos de archivo: 0600 (solo lectura/escritura del propietario)

• Sintaxis ${ATLASSIAN_TOKEN} — las referencias a variables de entorno se almacenan literalmente, se expanden en tiempo de ejecución

• Sin secretos en la salida — list_connections muestra el nombre del proyecto, la URL y el modo — nunca los tokens

• Modo efímero — --register mantiene las credenciales solo en memoria, nunca se escriben en el disco

Alcance de conexión

Usa --scope para limitar a qué conexiones guardadas puede acceder una instancia específica de MCP:

# Project config — only myproject visible, even if other connections are saved
uvx --from a2atlassian a2atlassian-mcp --scope myproject

Las configuraciones de MCP a nivel de proyecto (.claude/mcp.json) anulan las configuraciones globales: cada repositorio ve solo sus propias conexiones.

Limitación de tasa

Reintento integrado con retroceso exponencial para los límites de tasa de Atlassian (429) y errores transitorios del servidor (500). Dos reintentos en intervalos de 1s y 3s antes de mostrar el error.

Comparativa

Hoja de ruta

Fase 1 (actual): Núcleo de Jira — obtener/buscar incidencias, comentarios (CRUD), transiciones. La ruta crítica secundaria.

Fase 2: Superficie completa de Jira — sprints, tableros, enlaces, proyectos, campos, registros de trabajo, archivos adjuntos, observadores.

Fase 3: Confluence — páginas, comentarios, archivos adjuntos, etiquetas, búsqueda.

Configuración por entorno

Local (macOS / Linux)

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email me@co.com --token "$TOKEN"

# Or add as MCP server (see Quick Start)

CI / Automatización

uv tool install a2atlassian

# Pre-configured — no login needed
uvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net ci-user@co.com "${CI_ATLASSIAN_TOKEN}"

Desarrollo

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

Licencia

Apache 2.0