@itzjoordi/jira-mcp 1.0.0

package/.env-example

@@ -0,0 +1,3 @@
+JIRA_BASE_URL=https://tu-org.atlassian.net
+JIRA_EMAIL=tu-email@empresa.com
+JIRA_API_TOKEN=TU_TOKEN_AQUI

package/.eslintrc.json

@@ -0,0 +1,17 @@
+{
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "extends": ["standard", "prettier"],
+  "rules": {
+    "no-unused-vars": [
+      "warn",
+      {
+        "argsIgnorePattern": "^_"
+      }
+    ],
+    "import/no-anonymous-default-export": "off",
+    "no-console": "off"
+  }
+}

package/.prettierignore

@@ -0,0 +1,3 @@
+node_modules/
+.vscode/
+.env

package/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

package/README.md

@@ -0,0 +1,78 @@
+# 🧩 MCP Jira Mercadona para VS Code + GitHub Copilot
+
+Este proyecto proporciona un **servidor MCP** que permite interactuar con **Jira Mercadona** directamente desde **VS Code** usando **GitHub Copilot Chat**.
+
+Incluye herramientas para:
+
+- Filtrar issues de forma natural: “mis tareas pendientes”, “backlog del proyecto”, “tareas en curso”, etc.
+- Mover tareas entre estados (workflow transition)
+
+## 🚀 Requisitos
+
+- Node.js 18+
+- VS Code 1.102+
+- Extensión GitHub Copilot Chat → <https://code.visualstudio.com/docs/copilot/overview>
+- API Token → <https://id.atlassian.com/manage-profile/security/api-tokens>
+
+## 📦 Instalación
+
+```bash
+git clone <URL-del-repo>
+cd jira-mcp-test
+npm install
+```
+
+## 🔑 Configuración
+
+```bash
+cp .env.example .env
+```
+
+Editar `.env`:
+
+```
+JIRA_BASE_URL=https://<tu-org>.atlassian.net
+JIRA_EMAIL=tu-email@empresa.com
+JIRA_API_TOKEN=<tu-api-token>
+```
+
+## 🧩 Activación MCP
+
+En VS Code:
+
+```
+Reiniciar completamente VS Code
+Command Palette > MCP: List Servers
+```
+
+Debe aparecer `jiraMcp`.
+
+## 💬 Uso (Copilot Chat)
+
+Ejemplos:
+
+```
+Devuelveme todas mis tareas asignadas en curso
+```
+
+```
+Dime el backlog del proyecto XXXX
+```
+
+```
+Cambia el estado de la tarea XXXX-#### a VALIDADA
+```
+
+## 👷 Estructura
+
+- server.mjs
+- jiraApi.mjs
+- jiraClient.mjs
+- .vscode/mcp.json
+- .env.example
+- package.json
+
+## 🧯 Problemas comunes
+
+- 401/403 → token incorrecto
+- MCP no aparece → reiniciar VS Code

package/eslint.config.js

@@ -0,0 +1,12 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import { defineConfig } from 'eslint/config';
+
+export default defineConfig([
+  {
+    files: ['**/*.{js,mjs,cjs}'],
+    plugins: { js },
+    extends: ['js/recommended'],
+    languageOptions: { globals: globals.browser },
+  },
+]);

package/jiraApi.mjs

@@ -0,0 +1,61 @@
+// jiraApi.mjs
+import { jiraRequest } from './jiraClient.mjs';
+
+/**
+ * Buscar issues usando JQL (API nueva /search/jql)
+ */
+export async function searchIssues(jql, maxResults = 20) {
+  const body = {
+    jql,
+    maxResults,
+    fields: ['summary', 'status', 'assignee', 'priority'],
+  };
+
+  const data = await jiraRequest('/rest/api/3/search/jql', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+
+  const issues = data.issues ?? [];
+
+  return issues.map((issue) => ({
+    key: issue.key,
+    summary: issue.fields.summary,
+    status: issue.fields.status.name,
+    assignee: issue.fields.assignee?.displayName ?? null,
+    priority: issue.fields.priority?.name ?? null,
+  }));
+}
+
+/**
+ * Obtener las transiciones posibles para un issue
+ */
+export async function getIssueTransitions(issueKey) {
+  const data = await jiraRequest(`/rest/api/3/issue/${issueKey}/transitions`, {
+    method: 'GET',
+  });
+
+  const transitions = data.transitions ?? [];
+
+  return transitions.map((t) => ({
+    id: t.id,
+    name: t.name,
+    toStatus: t.to.name,
+  }));
+}
+
+/**
+ * Ejecutar una transición (mover a otro estado/columna)
+ */
+export async function transitionIssue(issueKey, transitionId) {
+  const body = {
+    transition: { id: transitionId },
+  };
+
+  const jiraRequest = await jiraRequest(`/rest/api/3/issue/${issueKey}/transitions`, {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+
+  return { ok: true };
+}

package/jiraClient.mjs

@@ -0,0 +1,72 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import dotenv from 'dotenv';
+import { Buffer } from 'buffer';
+import process from 'process';
+
+let envLoaded = false;
+
+function loadGlobalEnvOnce() {
+  if (envLoaded) return;
+  envLoaded = true;
+  const home = os.homedir();
+  const candidates = [path.join(home, '.jira-mcp.env'), path.join(home, '.jira-mcp', '.env')];
+
+  for (const p of candidates) {
+    try {
+      if (fs.existsSync(p)) {
+        dotenv.config({ path: p });
+        break;
+      }
+    } catch {
+      // ignore
+    }
+  }
+}
+
+loadGlobalEnvOnce();
+
+// --- a partir de aquí, uso normal de env:
+const baseUrl = process.env.JIRA_BASE_URL;
+const email = process.env.JIRA_EMAIL;
+const apiToken = process.env.JIRA_API_TOKEN;
+
+if (!baseUrl || !email || !apiToken) {
+  throw new Error(
+    'Faltan credenciales de Jira. Crea un .env global en tu HOME:\n' +
+      '- macOS/Linux:  ~/.jira-mcp.env  (o  ~/.jira-mcp/.env)\n' +
+      '- Windows:      %USERPROFILE%\\.jira-mcp.env  (o  %USERPROFILE%\\.jira-mcp\\.env)\n\n' +
+      'Variables requeridas:\n' +
+      'JIRA_BASE_URL=https://<tu-org>.atlassian.net\n' +
+      'JIRA_EMAIL=tu-email@empresa.com\n' +
+      'JIRA_API_TOKEN=<tu-token>\n',
+  );
+}
+
+const authHeader = 'Basic ' + Buffer.from(`${email}:${apiToken}`).toString('base64');
+
+/**
+ * Llamada genérica a Jira con manejo de errores
+ */
+export async function jiraRequest(path, options = {}) {
+  const url = `${baseUrl}${path}`;
+
+  const response = await fetch(url, {
+    ...options,
+    headers: {
+      Authorization: authHeader,
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...(options.headers || {}),
+    },
+  });
+
+  const text = await response.text();
+
+  if (!response.ok) {
+    throw new Error(`Jira error ${response.status} ${response.statusText}: ${text.slice(0, 400)}`);
+  }
+
+  return text ? JSON.parse(text) : {};
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@itzjoordi/jira-mcp",
+  "version": "1.0.0",
+  "description": "Servidor MCP para Jira Mercadona usable desde Github Copilot Chat",
+  "type": "module",
+  "bin": {
+    "jira-mcp": "./server.mjs"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write ."
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "dotenv": "^17.2.3",
+    "zod": "^3.25.76"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "eslint": "^9.39.1",
+    "globals": "^16.5.0",
+    "prettier": "^3.6.2"
+  }
+}

package/server.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { searchIssues, getIssueTransitions, transitionIssue } from './jiraApi.mjs';
+
+// 1. Crear servidor MCP
+const server = new McpServer({
+  name: 'jira-mcp',
+  version: '0.1.0',
+});
+
+// 2. Tools
+// Tool: listar issues con filtros simples
+server.registerTool(
+  'jira_list_filtered',
+  {
+    title: 'Jira: listar issues con filtros simples',
+    description:
+      'Lista issues de Jira usando filtros de alto nivel (solo mías, en curso, backlog, etc.) y construye la JQL automáticamente.',
+    inputSchema: {
+      projectKey: z
+        .string()
+        .optional()
+        .describe("Clave de proyecto, p.ej. 'SIM1'. Si se omite, busca en todos."),
+      onlyAssignedToMe: z
+        .boolean()
+        .optional()
+        .describe('Si es true, solo issues asignadas al usuario actual.'),
+      excludeAssignedToMe: z
+        .boolean()
+        .optional()
+        .describe('Si es true, excluye las issues asignadas al usuario actual.'),
+      statusCategory: z
+        .enum(['To Do', 'In Progress', 'Done'])
+        .optional()
+        .describe('Filtrar por categoría de estado de Jira.'),
+      statusIn: z
+        .array(z.string())
+        .optional()
+        .describe('Lista de nombres de estado, p.ej. ["Por Hacer", "Validar"].'),
+      backlogOnly: z
+        .boolean()
+        .optional()
+        .describe('Si es true, devuelve issues de backlog (aprox: no Done, normalmente To Do).'),
+      maxResults: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .optional()
+        .describe('Máximo de issues a devolver (por defecto 20).'),
+    },
+  },
+  async ({
+    projectKey,
+    onlyAssignedToMe,
+    excludeAssignedToMe,
+    statusCategory,
+    statusIn,
+    backlogOnly,
+    maxResults,
+  }) => {
+    const clauses = [];
+
+    if (projectKey) {
+      clauses.push(`project = ${projectKey}`);
+    }
+
+    if (onlyAssignedToMe) {
+      clauses.push('assignee = currentUser()');
+    } else if (excludeAssignedToMe) {
+      clauses.push('assignee != currentUser()');
+    }
+
+    if (statusCategory) {
+      clauses.push(`statusCategory = "${statusCategory}"`);
+    }
+
+    if (statusIn && statusIn.length > 0) {
+      const quoted = statusIn.map((s) => `"${s}"`).join(', ');
+      clauses.push(`status in (${quoted})`);
+    }
+
+    if (backlogOnly) {
+      // Aproximación: backlog = no Done
+      clauses.push('statusCategory != "Done"');
+    }
+
+    let jql = clauses.join(' AND ');
+    const order = 'ORDER BY created DESC';
+
+    if (jql.trim().length === 0) {
+      jql = order;
+    } else {
+      jql = `${jql} ${order}`;
+    }
+
+    const issues = await searchIssues(jql, maxResults ?? 20);
+
+    const humanText =
+      issues.length === 0
+        ? `No se han encontrado issues para la JQL: ${jql}`
+        : `JQL usada: ${jql}\n\n` +
+          issues
+            .map(
+              (i) =>
+                `${i.key} | ${i.status} | ${i.summary}` + (i.assignee ? ` (${i.assignee})` : ''),
+            )
+            .join('\n');
+
+    return {
+      content: [
+        { type: 'text', text: humanText },
+        {
+          type: 'text',
+          text: '\n\n[JSON crudo para el modelo]\n' + JSON.stringify({ jql, issues }, null, 2),
+        },
+      ],
+      structuredContent: { jql, issues },
+    };
+  },
+);
+
+// Tool: obtener transiciones de un issue
+server.registerTool(
+  'jira_get_transitions',
+  {
+    title: 'Jira: obtener transiciones de un issue',
+    description:
+      'Devuelve las transiciones posibles (id, name, toStatus) para un issue de Jira concreto.',
+    inputSchema: {
+      issueKey: z.string().describe("Clave del issue, p.ej. 'SIM1-320'"),
+    },
+    // outputSchema opcional:
+    // outputSchema: z.array(
+    //   z.object({
+    //     id: z.string(),
+    //     name: z.string(),
+    //     toStatus: z.string(),
+    //   })
+    // ),
+  },
+  async ({ issueKey }) => {
+    const transitions = await getIssueTransitions(issueKey);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(transitions, null, 2),
+        },
+      ],
+      structuredContent: transitions,
+    };
+  },
+);
+
+// Tool: hacer transición de un issue
+server.registerTool(
+  'jira_transition_issue',
+  {
+    title: 'Jira: cambiar estado de un issue',
+    description: 'Ejecuta una transición de workflow en un issue de Jira usando su transitionId.',
+    inputSchema: {
+      issueKey: z.string().describe("Clave del issue, p.ej. 'SIM1-320'"),
+      transitionId: z.string().describe('ID de la transición (devuelta por jira_get_transitions)'),
+    },
+    // outputSchema opcional:
+    // outputSchema: z.object({ ok: z.boolean() }),
+  },
+  async ({ issueKey, transitionId }) => {
+    const result = await transitionIssue(issueKey, transitionId);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+      structuredContent: result,
+    };
+  },
+);
+
+// Tool: mover issue por nombre de transición
+server.registerTool(
+  'jira_move_issue_by_transition_name',
+  {
+    title: 'Jira: mover issue por nombre de transición',
+    description:
+      "Busca la transición por nombre (p.ej. 'Construir', 'Validar') y la ejecuta sobre el issue.",
+    inputSchema: {
+      issueKey: z.string().describe("Clave del issue, p.ej. 'SIM1-320'"),
+      transitionName: z.string().describe("Nombre exacto de la transición, p.ej. 'Construir'"),
+    },
+  },
+  async ({ issueKey, transitionName }) => {
+    const transitions = await getIssueTransitions(issueKey);
+    const match = transitions.find((t) => t.name.toLowerCase() === transitionName.toLowerCase());
+
+    if (!match) {
+      const available = transitions.map((t) => t.name).join(', ');
+      const msg =
+        `No se ha encontrado ninguna transición llamada "${transitionName}" ` +
+        `para el issue ${issueKey}. Transiciones disponibles: ${available}`;
+
+      return {
+        content: [{ type: 'text', text: msg }],
+        structuredContent: { ok: false, error: msg, transitions },
+      };
+    }
+
+    const result = await transitionIssue(issueKey, match.id);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Transición "${match.name}" aplicada a ${issueKey}. Nuevo estado: ${match.toStatus}`,
+        },
+        {
+          type: 'text',
+          text: '\n[Detalle JSON]\n' + JSON.stringify({ result, usedTransition: match }, null, 2),
+        },
+      ],
+      structuredContent: { ok: true, usedTransition: match },
+    };
+  },
+);
+
+// 3. Conectar por STDIO
+const transport = new StdioServerTransport();
+await server.connect(transport);