mcp-multi-jira 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 iipanda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# mcp-multi-jira
+
+[![CI](https://github.com/iipanda/mcp-multi-jira/actions/workflows/ci.yml/badge.svg)](https://github.com/iipanda/mcp-multi-jira/actions/workflows/ci.yml)
+
+Multi-account Jira MCP server. Configure multiple Atlassian Jira accounts and route tool calls by account alias.
+
+## Project goals
+
+Most Jira MCP setups are single-account, which gets painful if you regularly switch between:
+
+- work + personal Jira
+- multiple clients/tenants
+- separate Jira sites with different permissions
+
+This project exists to provide a **single MCP server** that can hold **multiple Jira accounts** and route every tool call via an explicit `account` parameter (so your agent config stays stable while you tell it to use different accounts in prompts).
+
+This project has features like:
+
+- optional encrypted or OS keychain token storage
+- works with common MCP clients (Cursor, Claude Code, Codex CLI)
+- automatic installation of MCP configs for supported agents
+
+## Quick start
+
+First, set up your account(s):
+
+```bash
+npx -y mcp-multi-jira login Work
+npx -y mcp-multi-jira login Personal
+```
+
+Then, install the MCP in your favorite coding agent:
+
+```bash
+npx -y mcp-multi-jira install
+```
+
+That's it! Restart your coding agent / IDE to pick up the new MCP server.
+
+## CLI reference
+
+Log in an account:
+
+```bash
+mcp-multi-jira login WorkJira
+```
+
+List accounts:
+
+```bash
+mcp-multi-jira list
+```
+
+Start the server:
+(Note: server will be started automatically by the agents if you use the install command)
+
+```bash
+mcp-multi-jira serve
+```
+
+Install MCP configuration for supported agents:
+
+```bash
+mcp-multi-jira install
+```
+
+## Advanced usage
+
+### Change token storage
+
+By default, tokens are stored in a plaintext file. To use encryption or the OS keychain, set the default backend once with:
+
+```bash
+# Options: plain (default), encrypted, keychain
+mcp-multi-jira token-store encrypted
+```
+
+If you use encrypted storage, make sure your environment has the master password set, otherwise the MCP will fail to start:
+
+```bash
+export MCP_JIRA_TOKEN_PASSWORD="your-master-password"
+```
+
+Plaintext tokens are stored at `~/.mcp-jira/tokens.json` (do not use on shared machines).
+
+When switching token stores and accounts already exist, the CLI will prompt to migrate tokens to the new backend.
+
+### Override OAuth client
+
+```bash
+export MCP_JIRA_CLIENT_ID="your-client-id"
+export MCP_JIRA_CLIENT_SECRET="your-client-secret"
+```
+
+## Manual agent configuration
+
+You can auto-install agent configs:
+
+```bash
+mcp-multi-jira install
+```
+
+Below are manual snippets for advanced setups.
+
+### Cursor
+
+`~/.cursor/mcp.json` (or per-project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-jira": {
+      "command": "npx",
+      "args": ["-y", "mcp-multi-jira", "serve"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+`~/.claude/mcp_servers.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-jira": {
+      "command": "npx",
+      "args": ["-y", "mcp-multi-jira", "serve"]
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mcp_jira]
+command = "npx"
+args = ["-y", "mcp-multi-jira", "serve"]
+```

package/dist/agents/install.js

@@ -0,0 +1,279 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import toml from "@iarna/toml";
+import { checkbox, confirm, password } from "@inquirer/prompts";
+import { backupFile } from "../utils/fs.js";
+import { info, warn } from "../utils/log.js";
+const MCP_SERVER_NAME = "mcp-jira";
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object";
+}
+function ensureRecord(value) {
+    return isRecord(value) ? value : {};
+}
+function getOrCreateRecord(container, key) {
+    const current = container[key];
+    if (isRecord(current)) {
+        return current;
+    }
+    const next = {};
+    container[key] = next;
+    return next;
+}
+function createMcpServerEntry(env) {
+    return {
+        command: "npx",
+        args: ["-y", "mcp-multi-jira", "serve"],
+        ...(Object.keys(env).length > 0 ? { env } : {}),
+    };
+}
+function resolveEnvDefaults() {
+    return {
+        clientId: process.env.MCP_JIRA_CLIENT_ID || process.env.ATLASSIAN_CLIENT_ID || "",
+        clientSecret: process.env.MCP_JIRA_CLIENT_SECRET ||
+            process.env.ATLASSIAN_CLIENT_SECRET ||
+            "",
+        tokenPassword: process.env.MCP_JIRA_TOKEN_PASSWORD || "",
+        tokenStore: process.env.MCP_JIRA_TOKEN_STORE || "",
+    };
+}
+function normalizeTokenStore(value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = value.toLowerCase();
+    if (normalized === "encrypted" ||
+        normalized === "plain" ||
+        normalized === "keychain") {
+        return normalized;
+    }
+    return null;
+}
+async function promptEnv(tokenStore) {
+    const defaults = resolveEnvDefaults();
+    if (tokenStore !== "encrypted") {
+        return { tokenPassword: "" };
+    }
+    if (defaults.tokenPassword) {
+        return { tokenPassword: defaults.tokenPassword };
+    }
+    const tokenPassword = await password({
+        message: "Master token password for encrypted storage (leave blank to skip):",
+    });
+    return { tokenPassword };
+}
+function buildEnv(envInput) {
+    const env = {};
+    if (envInput.clientId) {
+        env.MCP_JIRA_CLIENT_ID = envInput.clientId;
+    }
+    if (envInput.clientSecret) {
+        env.MCP_JIRA_CLIENT_SECRET = envInput.clientSecret;
+    }
+    if (envInput.tokenPassword) {
+        env.MCP_JIRA_TOKEN_PASSWORD = envInput.tokenPassword;
+    }
+    if (envInput.tokenStore) {
+        env.MCP_JIRA_TOKEN_STORE = String(envInput.tokenStore);
+    }
+    if (envInput.tokenStore === "keychain") {
+        env.MCP_JIRA_USE_KEYCHAIN = "true";
+    }
+    return env;
+}
+function isJiraEntry(name, entry) {
+    const lowered = name.toLowerCase();
+    if (lowered.includes("jira") || lowered.includes("atlassian")) {
+        return true;
+    }
+    const serialized = JSON.stringify(entry ?? "").toLowerCase();
+    return (serialized.includes("mcp.atlassian.com") ||
+        serialized.includes("mcp-atlassian") ||
+        serialized.includes("jira_url"));
+}
+async function removeJiraEntries(entries, message, configPath) {
+    const jiraKeys = Object.keys(entries).filter((key) => isJiraEntry(key, entries[key]));
+    if (jiraKeys.length === 0) {
+        return true;
+    }
+    const remove = await confirm({
+        message: `${message} (${jiraKeys.join(", ")}). Remove them?`,
+        default: false,
+    });
+    if (!remove) {
+        warn(`Skipping config update for ${configPath}.`);
+        return false;
+    }
+    await backupFile(configPath);
+    for (const key of jiraKeys) {
+        delete entries[key];
+    }
+    return true;
+}
+async function readJsonConfig(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return { config: ensureRecord(JSON.parse(raw)), exists: true };
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { config: {}, exists: false };
+        }
+        throw err;
+    }
+}
+async function loadClaudeConfig() {
+    const home = os.homedir();
+    const mcpServersPath = path.join(home, ".claude", "mcp_servers.json");
+    const globalConfigPath = path.join(home, ".claude.json");
+    const mcpFile = await readJsonConfig(mcpServersPath);
+    if (mcpFile.exists) {
+        return { config: mcpFile.config, targetPath: mcpServersPath, mode: "mcp" };
+    }
+    const globalFile = await readJsonConfig(globalConfigPath);
+    return {
+        config: globalFile.config,
+        targetPath: globalConfigPath,
+        mode: "project",
+    };
+}
+async function updateCursorConfig(configPath, env) {
+    let config = { mcpServers: {} };
+    let exists = false;
+    try {
+        const raw = await fs.readFile(configPath, "utf8");
+        config = ensureRecord(JSON.parse(raw));
+        exists = true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    const mcpServers = getOrCreateRecord(config, "mcpServers");
+    if (exists) {
+        const shouldContinue = await removeJiraEntries(mcpServers, `Cursor config ${configPath} contains Jira MCP entries`, configPath);
+        if (!shouldContinue) {
+            return;
+        }
+    }
+    mcpServers[MCP_SERVER_NAME] = createMcpServerEntry(env);
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
+    info(`Updated Cursor MCP config: ${configPath}`);
+}
+async function updateCodexConfig(configPath, env) {
+    let config = {};
+    let exists = false;
+    try {
+        const raw = await fs.readFile(configPath, "utf8");
+        config = ensureRecord(toml.parse(raw));
+        exists = true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    const servers = getOrCreateRecord(config, "mcp_servers");
+    if (exists) {
+        const shouldContinue = await removeJiraEntries(servers, "Codex config has Jira MCP entries", configPath);
+        if (!shouldContinue) {
+            return;
+        }
+    }
+    servers[MCP_SERVER_NAME.replace(/-/g, "_")] = createMcpServerEntry(env);
+    config.mcp_servers = servers;
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, toml.stringify(config), "utf8");
+    info(`Updated Codex MCP config: ${configPath}`);
+}
+async function updateClaudeMcpServers(config, targetPath, env) {
+    const mcpServers = getOrCreateRecord(config, "mcpServers");
+    const shouldContinue = await removeJiraEntries(mcpServers, "Claude MCP config has Jira entries", targetPath);
+    if (!shouldContinue) {
+        return false;
+    }
+    mcpServers[MCP_SERVER_NAME] = createMcpServerEntry(env);
+    return true;
+}
+async function updateClaudeProjectConfig(config, targetPath, env) {
+    const projectPath = process.cwd();
+    const projects = getOrCreateRecord(config, "projects");
+    const project = getOrCreateRecord(projects, projectPath);
+    const mcpServers = getOrCreateRecord(project, "mcpServers");
+    const shouldContinue = await removeJiraEntries(mcpServers, `Claude config for ${projectPath} has Jira entries`, targetPath);
+    if (!shouldContinue) {
+        return false;
+    }
+    mcpServers[MCP_SERVER_NAME] = createMcpServerEntry(env);
+    return true;
+}
+async function updateClaudeConfig(env) {
+    const { config, targetPath, mode } = await loadClaudeConfig();
+    const updated = mode === "mcp"
+        ? await updateClaudeMcpServers(config, targetPath, env)
+        : await updateClaudeProjectConfig(config, targetPath, env);
+    if (!updated) {
+        return;
+    }
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, JSON.stringify(config, null, 2), "utf8");
+    info(`Updated Claude MCP config: ${targetPath}`);
+}
+export async function runInstaller(options) {
+    const targets = (await checkbox({
+        message: "Select which agents to configure:",
+        choices: [
+            { name: "Cursor", value: "cursor" },
+            { name: "OpenAI Codex CLI", value: "codex" },
+            { name: "Claude Code CLI", value: "claude" },
+        ],
+        required: true,
+    }));
+    const defaults = resolveEnvDefaults();
+    const envStore = normalizeTokenStore(options?.tokenStore) ??
+        normalizeTokenStore(process.env.MCP_JIRA_TOKEN_STORE) ??
+        (process.env.MCP_JIRA_USE_KEYCHAIN ? "keychain" : null) ??
+        normalizeTokenStore(defaults.tokenStore) ??
+        "plain";
+    const envInput = await promptEnv(envStore);
+    const env = buildEnv({
+        ...envInput,
+        tokenStore: envStore,
+        clientId: defaults.clientId,
+        clientSecret: defaults.clientSecret,
+    });
+    for (const target of targets) {
+        if (target === "cursor") {
+            const home = os.homedir();
+            const globalPath = path.join(home, ".cursor", "mcp.json");
+            const localPath = path.join(process.cwd(), ".cursor", "mcp.json");
+            await updateCursorConfig(globalPath, env);
+            try {
+                await fs.access(localPath);
+                const updateLocal = await confirm({
+                    message: `Also update local Cursor config at ${localPath}?`,
+                    default: false,
+                });
+                if (updateLocal) {
+                    await updateCursorConfig(localPath, env);
+                }
+            }
+            catch {
+                // ignore missing local config
+            }
+            continue;
+        }
+        if (target === "codex") {
+            const configPath = path.join(os.homedir(), ".codex", "config.toml");
+            await updateCodexConfig(configPath, env);
+            continue;
+        }
+        if (target === "claude") {
+            await updateClaudeConfig(env);
+        }
+    }
+    info("Installation complete. Restart each agent to load the new MCP configuration.");
+}