Claude Jira

Integración de Claude con Jira vía MCP server interno, diseñada para entornos corporativos con red privada (Jira Server/Data Center).

Arquitectura

[CLI (Typer)]     ──HTTP──►
                            [Service Layer (FastAPI)] → [Claude API — LiteLLM proxy]
[MCP Server SSE]  ──HTTP──►                           → [Jira REST API v2 — jira.zurich.com]

El MCP server y el service layer corren dentro de la red corporativa. Ningún dato sale hacia servicios cloud externos.

Setup

conda env create -f environment.yml
conda activate claude-mcp-jira
cp .env.example .env  # completar JIRA_PAT y MCP_API_KEY

Uso

# Levantar stack completo (service layer + MCP server)
docker compose up

# Desarrollo local (fuera de Docker)
bash scripts/dev.sh both       # service :18000 + MCP :18001
bash scripts/dev.sh service    # solo service layer
bash scripts/dev.sh stop       # detener todo
bash scripts/dev.sh restart    # reinicio limpio

# Tests
bash scripts/test-dev.sh       # service layer: 8 tests (CLI → FastAPI → Jira)
bash scripts/test-mcp.sh       # MCP server: 10 tests (SSE tools + auth + RBAC)
bash scripts/test-multi.sh     # multi-proyecto: 19 tests (ZNRX/AIPROJECTS/SAZ + auto-discovery)
bash scripts/test-actions.sh   # endpoints de acción: 24 tests (comments, assign, priority, labels, worklog, transition, clone, link, saz)
pytest tests/                  # unitarios: 52 tests (sanitizer, jql, auth, rbac)

# Comandos CLI
python cli/main.py create "bug login en producción prioridad alta"
python cli/main.py update ZNRX-123 "cambiar prioridad a alta"
python cli/main.py summarize ZNRX-123
python cli/main.py list-issues "mis tareas abiertas de esta semana"

Proyectos Jira configurados

Ver docs/jira-projects.md para metadata completa, restricciones de campos y configuración por proyecto.

Proyecto	JIRA_PROJECT_KEY	TICKET_LANG	Propósito
ZNRX	ZNRX	es	Gestión de requerimientos y desarrollo
AIPROJECTS	AIPROJECTS	en	IA y automatización de negocio
SAZ	SAZ	es	Solicitudes Release / DevOps
SCRX	SCRX	es	Desarrollo ágil Ecuador/LATAM

Certificados corporativos

certs/ contiene los certificados raíz Zurich. Ambos Dockerfiles los instalan automáticamente en /etc/ssl/certs/.

Archivo	Uso
zurichseguros-rootca-until-2031_03_20.crt	Servicios internos estándar (jira.zurich.com)
zurich-ssl-ca.pem	SSL inspection CA (ssldecrypt.latam.zurich.com) — requerido para api-zurich.data-fact.com
cacert-workflow-uat.pem	Endpoints UAT de workflow
localCA.crt	CA de desarrollo local

En .env, REQUESTS_CA_BUNDLE apunta al cert del endpoint que se va a llamar. Ver .env.example para detalles.

Estado de implementación

Fase	Estado	Descripción
1 — Prototipo CLI	✅ Completa	Comando create directo
2 — Service Layer	✅ Completa	FastAPI + sanitización + audit log + timeouts
3 — Comandos completos	✅ Completa	update, summarize, list + JQL controlado + rate limiter
4 — MCP Server	✅ Completa	SSE Docker + auth API key + RBAC + rate limit + output normalizado
4.1 — Ajustes e2e + TICKET_LANG	✅ Completa	Campos ZNRX, priority IDs, prompts ES, idioma configurable
4.2 — Deuda técnica	✅ Completa	JQL injection fix, audit MCP, rate limiter compartido, 52 unit tests
4.3 — Transiciones y Log Work	✅ Completa	POST /issues/{key}/transition + POST /issues/{key}/worklog
4.4 — Mejoras API	✅ Completa	comments, assign, priority, labels, clone
4.5 — Link dinámico	✅ Completa	POST /issues/{key}/link + GET /issue-link-types (cache TTL 1h)
5 — Soporte SAZ	✅ Completa	POST /issues/saz + MCP create_saz_request (lead); znrx_key opcional
7 — Multi-proyecto	✅ Completa	project opcional en create/search; SQLite + auto-discovery lazy; GET /projects
6 — Observabilidad	Futura	Prometheus + OpenTelemetry + caching — activar cuando el volumen lo justifique
8a — PAT dinámico	Futura	X-Jira-Token header opcional — cada usuario opera con su propia identidad Jira
8 — UI	Futura	Streamlit MVP → Next.js si hay adopción; login PAT → JWT → propaga como X-Jira-Token
9.1–9.4 — Git Intelligence	✅ Completa	Scanner, analyzer, mapper, POST /git/sync, repo registry SQLite, MCP sync_git_worklogs / register_git_repo
9.5 — Human-sensity worklogs	Futura	Señales contextuales + human-in-the-loop editable antes de registrar

Documentación

Documento	Descripción
docs/jira-projects.md	Proyectos Jira — restricciones, issuetypes, TICKET_LANG
docs/jira-fields.md	Campos requeridos y valores permitidos por proyecto
docs/jira-roles.md	Permisos efectivos del usuario en los 4 proyectos
docs/jira-link-types.md	Tipos de link — 29 tipos en jira.zurich.com; también disponible vía GET /issue-link-types
docs/jira-workflows.md	Statuses y transiciones por proyecto
arch/bd/README.md	Base de datos SQLite — tablas projects y git_repos, columnas, repos registrados
arch/	Arquitectura, plan de implementación, evaluaciones e informes técnicos
jira_mcp/README.md	Variables de entorno y configuración del MCP server