@simplysf/simply-atlassian-mcp 0.4.1 → 0.5.0

package/README.md

@@ -3,8 +3,8 @@
 [![NPM](https://img.shields.io/npm/v/@simplysf/simply-atlassian-mcp?label=@simplysf/simply-atlassian-mcp)](https://npmjs.com/@simplysf/simply-atlassian-mcp) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://raw.githubusercontent.com/SimplySF/simply-atlassian/main/LICENSE.txt)
 
 A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives an AI agent in
-Claude Desktop, Claude Code, Cursor, VS Code, or any other MCP client the same Jira and Confluence
-capabilities as the [`@simplysf/simply-atlassian`](../simply-atlassian) CLI: one tool per command,
+Claude Desktop, Claude Code, Cursor, Gemini, VS Code, or any other MCP client the same Jira and
+Confluence capabilities as the [`@simplysf/simply-atlassian`](../simply-atlassian) CLI: one tool per command,
 calling the same [`@simplysf/simply-atlassian-core`](../simply-atlassian-core) library in-process.
 The agent gets the CLI's credential handling, `dryRun` previews, read-only guard, credential
 redaction, and error messages, and the same raw JSON the CLI prints with `--json`, without a
@@ -21,10 +21,20 @@ the [documentation site](https://simplysf.github.io/simply-atlassian/guides/mcp-
 The server needs Node.js 22 or later.
 
 ```bash
-npm install -g @simplysf/simply-atlassian-mcp
-simply-atlassian-mcp --help
+npm install -g @simplysf/simply-cli
+simply atlassian mcp --list
 ```
 
+`--list` prints every tool this server would register, then exits. Run without it and the server
+waits on stdin for a client, which at a terminal looks like a hang.
+
+The plugin installs itself the first time you run the command, so `@simplysf/simply-cli` is the
+only thing to install.
+
+**The standalone binary still works.** `npm install -g @simplysf/simply-atlassian-mcp` and
+`simply-atlassian-mcp` are unchanged, and an existing client configuration pointing at them keeps
+running.
+
 `--help` prints the options and every tool the server can register, so it doubles as a check that
 the install worked. It prints to stderr, because stdout is reserved for the protocol stream.
 
@@ -109,6 +119,83 @@ servers and whether each one connected.
 Cursor reads `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project, with
 the same `mcpServers` shape as Claude Desktop.
 
+### Gemini CLI
+
+Gemini CLI reads `~/.gemini/settings.json` for every project, or `.gemini/settings.json` inside a
+project, with the same `mcpServers` shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian": {
+      "command": "simply-atlassian-mcp",
+      "args": ["--env-file", "/home/me/atlassian.env"]
+    }
+  }
+}
+```
+
+`gemini mcp add` writes the same entry. `--scope user` puts it in the global file; the default
+`project` scope writes `.gemini/settings.json`, and `-e` sets one variable on the entry:
+
+```sh
+gemini mcp add --scope user \
+  -e JIRA_URL=https://your-site.atlassian.net \
+  -e JIRA_USERNAME=you@example.com \
+  -e JIRA_API_TOKEN=... \
+  simply-atlassian simply-atlassian-mcp
+```
+
+Flags meant for the server itself, `--env-file` and `--allow-writes`, are easier to add by editing
+`settings.json`, because `gemini mcp add` reads a leading-dash argument as one of its own options.
+
+Values in `env` expand `$NAME` from the environment Gemini started in, which keeps the token out of
+the settings file without an env file:
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian": {
+      "command": "npx",
+      "args": ["-y", "@simplysf/simply-atlassian-mcp"],
+      "env": {
+        "JIRA_URL": "https://your-site.atlassian.net",
+        "JIRA_USERNAME": "you@example.com",
+        "JIRA_API_TOKEN": "$JIRA_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Two other fields on an entry matter here. `trust: true` bypasses the per-call confirmation for
+every tool on that server, so leave it off on any entry started with `--allow-writes` and let a
+person approve each write. `includeTools` and `excludeTools` narrow what the model is shown, which
+is a second way to express the split in [Let the agent write](#let-the-agent-write): a write entry
+can register the write tools while holding back the destructive ones.
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian-write": {
+      "command": "simply-atlassian-mcp",
+      "args": ["--allow-writes", "--env-file", "/home/me/atlassian-write.env"],
+      "excludeTools": ["jira_issue_delete", "jira_issue_comment_delete", "confluence_page_delete"],
+      "trust": false
+    }
+  }
+}
+```
+
+Inside a session, `/mcp` lists the configured servers, whether each connected, and the tools it
+registered.
+
+### Gemini Code Assist
+
+Agent mode in the VS Code extension reads that same `~/.gemini/settings.json`, so an entry added
+for Gemini CLI is already in place. In IntelliJ the file is `mcp.json` in the IDE's configuration
+directory, holding the same `mcpServers` object.
+
 ### VS Code
 
 VS Code reads `.vscode/mcp.json`, with a `servers` key and an explicit transport type:

package/lib/commands/atlassian/mcp.d.ts

@@ -0,0 +1,28 @@
+import { Command } from '@oclif/core';
+/**
+ * Serves this package's MCP tools over stdio, as a command of the `simply` CLI.
+ *
+ * The same server the `simply-atlassian-mcp` binary runs — that binary still exists and still works.
+ * This exists so an MCP client can be pointed at `simply` with no separate global install: the
+ * plugin is fetched on first use like any other.
+ *
+ * **Extends `Command` directly, not `AtlassianCommand`.** That is deliberate and load-bearing. stdout
+ * is the protocol channel here, and the shared base class enables oclif's `--json` flag, which
+ * makes oclif print this command's return value to stdout when it is passed. One stray object on
+ * that stream corrupts the session, and the client's error would say nothing about why.
+ */
+export default class AtlassianMcp extends Command {
+    static enableJsonFlag: boolean;
+    static readonly summary = "Serve the Atlassian MCP tools over stdio.";
+    static readonly description: string;
+    static readonly examples: {
+        description: string;
+        command: string;
+    }[];
+    static readonly flags: {
+        'allow-writes': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'env-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        list: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/lib/commands/atlassian/mcp.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Command, Flags } from '@oclif/core';
+import { selectTools, startServer } from '../../index.js';
+/**
+ * Serves this package's MCP tools over stdio, as a command of the `simply` CLI.
+ *
+ * The same server the `simply-atlassian-mcp` binary runs — that binary still exists and still works.
+ * This exists so an MCP client can be pointed at `simply` with no separate global install: the
+ * plugin is fetched on first use like any other.
+ *
+ * **Extends `Command` directly, not `AtlassianCommand`.** That is deliberate and load-bearing. stdout
+ * is the protocol channel here, and the shared base class enables oclif's `--json` flag, which
+ * makes oclif print this command's return value to stdout when it is passed. One stray object on
+ * that stream corrupts the session, and the client's error would say nothing about why.
+ */
+export default class AtlassianMcp extends Command {
+    // Explicitly off, restating the class comment as code so a later refactor onto a base class
+    // that enables it fails loudly here rather than silently corrupting a protocol stream.
+    static enableJsonFlag = false;
+    static summary = 'Serve the Atlassian MCP tools over stdio.';
+    static description = 'Runs a Model Context Protocol server exposing Jira and Confluence as tools, for Claude Desktop, Claude ' +
+        'Code, Cursor, Gemini CLI, VS Code, or any other MCP client. It speaks the protocol on stdout, ' +
+        'so it is meant to be launched by a client rather than run by hand — at a terminal it will ' +
+        'simply appear to hang, waiting for a client that is not there.\n\n' +
+        'Point a client at it with "command": "simply", "args": ["atlassian", "mcp"]. The plugin installs ' +
+        'itself on first use, so nothing needs installing beyond the simply CLI.\n\n' +
+        'Only read tools are registered unless --allow-writes is passed, and ATLASSIAN_READ_ONLY still ' +
+        'refuses every write even then.';
+    static examples = [
+        {
+            description: 'Register only the read tools, taking settings from the environment',
+            command: '<%= config.bin %> <%= command.id %>',
+        },
+        {
+            description: 'Allow writes, with settings from a file',
+            command: '<%= config.bin %> <%= command.id %> --allow-writes --env-file ~/atlassian.env',
+        },
+        {
+            description: 'List the tools this server would register, without starting it',
+            command: '<%= config.bin %> <%= command.id %> --list',
+        },
+    ];
+    static flags = {
+        'allow-writes': Flags.boolean({
+            summary: 'Also register the tools that change data.',
+            description: 'Off by default, so a server launched without thinking about it can only read. ' +
+                'ATLASSIAN_READ_ONLY in the environment still refuses every write even when this is on.',
+            default: false,
+        }),
+        'env-file': Flags.string({
+            char: 'e',
+            summary: 'Path to a .env file holding connection settings.',
+            description: 'Use an absolute path. MCP clients launch a server from a working directory of their own, ' +
+                'so ~ and relative paths may not resolve.',
+        }),
+        list: Flags.boolean({
+            summary: 'Print the tools that would be registered, then exit without serving.',
+            description: 'Printed to stderr, because stdout belongs to the protocol.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AtlassianMcp);
+        if (flags.list) {
+            // stderr, like every other diagnostic here: a client that inspects stdout must only ever
+            // find protocol traffic on it.
+            const tools = selectTools(flags['allow-writes']);
+            process.stderr.write([
+                `${tools.length} tool(s) would be registered${flags['allow-writes'] ? ' (writes allowed)' : ' (read-only)'}:`,
+                ...tools.map((tool) => `  ${tool.name.padEnd(28)} ${tool.title}`),
+                '',
+            ].join('\n'));
+            return;
+        }
+        // Resolves once the transport is connected; the process then stays alive until the client
+        // closes the stream, which is why this command never returns in normal use.
+        await startServer({ allowWrites: flags['allow-writes'], envFile: flags['env-file'] });
+    }
+}
+//# sourceMappingURL=mcp.js.map

package/lib/commands/atlassian/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../src/commands/atlassian/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,YAAa,SAAQ,OAAO;IAC/C,4FAA4F;IAC5F,uFAAuF;IAChF,MAAM,CAAU,cAAc,GAAG,KAAK,CAAC;IAEvC,MAAM,CAAmB,OAAO,GAAG,2CAA2C,CAAC;IAC/E,MAAM,CAAmB,WAAW,GACzC,yGAAyG;QACzG,gGAAgG;QAChG,4FAA4F;QAC5F,oEAAoE;QACpE,mGAAmG;QACnG,6EAA6E;QAC7E,gGAAgG;QAChG,gCAAgC,CAAC;IAE5B,MAAM,CAAmB,QAAQ,GAAG;QACzC;YACE,WAAW,EAAE,oEAAoE;YACjF,OAAO,EAAE,qCAAqC;SAC/C;QACD;YACE,WAAW,EAAE,yCAAyC;YACtD,OAAO,EAAE,+EAA+E;SACzF;QACD;YACE,WAAW,EAAE,gEAAgE;YAC7E,OAAO,EAAE,4CAA4C;SACtD;KACF,CAAC;IAEK,MAAM,CAAmB,KAAK,GAAG;QACtC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC;YAC5B,OAAO,EAAE,2CAA2C;YACpD,WAAW,EACT,gFAAgF;gBAChF,wFAAwF;YAC1F,OAAO,EAAE,KAAK;SACf,CAAC;QACF,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;YACvB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,kDAAkD;YAC3D,WAAW,EACT,2FAA2F;gBAC3F,0CAA0C;SAC7C,CAAC;QACF,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC;YAClB,OAAO,EAAE,sEAAsE;YAC/E,WAAW,EAAE,4DAA4D;YACzE,OAAO,EAAE,KAAK;SACf,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAEjD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,yFAAyF;YACzF,+BAA+B;YAC/B,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;YACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;gBACE,GAAG,KAAK,CAAC,MAAM,+BAA+B,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,cAAc,GAAG;gBAC7G,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACjE,EAAE;aACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;YACF,OAAO;QACT,CAAC;QAED,0FAA0F;QAC1F,4EAA4E;QAC5E,MAAM,WAAW,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,cAAc,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC"}

package/oclif.manifest.json

@@ -0,0 +1,65 @@
+{
+  "commands": {
+    "atlassian:mcp": {
+      "aliases": [],
+      "args": {},
+      "description": "Runs a Model Context Protocol server exposing Jira and Confluence as tools, for Claude Desktop, Claude Code, Cursor, Gemini CLI, VS Code, or any other MCP client. It speaks the protocol on stdout, so it is meant to be launched by a client rather than run by hand — at a terminal it will simply appear to hang, waiting for a client that is not there.\n\nPoint a client at it with \"command\": \"simply\", \"args\": [\"atlassian\", \"mcp\"]. The plugin installs itself on first use, so nothing needs installing beyond the simply CLI.\n\nOnly read tools are registered unless --allow-writes is passed, and ATLASSIAN_READ_ONLY still refuses every write even then.",
+      "examples": [
+        {
+          "description": "Register only the read tools, taking settings from the environment",
+          "command": "<%= config.bin %> <%= command.id %>"
+        },
+        {
+          "description": "Allow writes, with settings from a file",
+          "command": "<%= config.bin %> <%= command.id %> --allow-writes --env-file ~/atlassian.env"
+        },
+        {
+          "description": "List the tools this server would register, without starting it",
+          "command": "<%= config.bin %> <%= command.id %> --list"
+        }
+      ],
+      "flags": {
+        "allow-writes": {
+          "description": "Off by default, so a server launched without thinking about it can only read. ATLASSIAN_READ_ONLY in the environment still refuses every write even when this is on.",
+          "name": "allow-writes",
+          "summary": "Also register the tools that change data.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "env-file": {
+          "char": "e",
+          "description": "Use an absolute path. MCP clients launch a server from a working directory of their own, so ~ and relative paths may not resolve.",
+          "name": "env-file",
+          "summary": "Path to a .env file holding connection settings.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "list": {
+          "description": "Printed to stderr, because stdout belongs to the protocol.",
+          "name": "list",
+          "summary": "Print the tools that would be registered, then exit without serving.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "atlassian:mcp",
+      "pluginAlias": "@simplysf/simply-atlassian-mcp",
+      "pluginName": "@simplysf/simply-atlassian-mcp",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Serve the Atlassian MCP tools over stdio.",
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "atlassian",
+        "mcp.js"
+      ]
+    }
+  },
+  "version": "0.5.0"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-atlassian-mcp",
   "description": "Model Context Protocol server exposing Jira and Confluence to AI agents, built on @simplysf/simply-atlassian-core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-atlassian",
   "bugs": "https://github.com/SimplySF/simply-atlassian/issues",
@@ -14,7 +14,8 @@
     "node": ">=22.0.0"
   },
   "files": [
-    "/lib"
+    "/lib",
+    "/oclif.manifest.json"
   ],
   "keywords": [
     "mcp",
@@ -33,11 +34,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "@oclif/core": "^4.11.2",
     "@simplysf/simply-atlassian-core": "^0.5.0",
     "zod": "^4.5.4"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",
+    "oclif": "^4.23.0",
+    "shx": "^0.4.0",
     "vitest": "^4.1.10"
   },
   "publishConfig": {
@@ -49,6 +53,8 @@
     "fix-license": "eslint src test --fix --rule \"header/header: [2]\"",
     "format": "wireit",
     "lint": "wireit",
+    "postpack": "shx rm -f oclif.manifest.json",
+    "prepack": "pnpm run compile && oclif manifest",
     "test": "wireit",
     "test:coverage": "wireit",
     "test:only": "wireit",
@@ -167,5 +173,15 @@
       "service": true
     }
   },
-  "gitHead": "b0d86a9014b4e6483898577781f4090a20685b70"
+  "oclif": {
+    "bin": "simply",
+    "commands": "./lib/commands",
+    "topicSeparator": " ",
+    "topics": {
+      "atlassian": {
+        "description": "Work with Atlassian products."
+      }
+    }
+  },
+  "gitHead": "5dae9b6f994f73ca5b6ba14644d80f34fa520cbe"
 }