@simplysf/simply-atlassian-mcp 0.4.2 → 0.6.0

package/README.md

@@ -14,17 +14,27 @@ Using it takes four steps: install the server, tell your MCP client how to launc
 connection, then ask the agent for what you want in plain language. This README walks through
 each, then covers letting the agent write, the full tool list, results and errors, and what to
 check when something does not work. The same material, with the rest of the CLI's guides, is on
-the [documentation site](https://simplysf.github.io/simply-atlassian/guides/mcp-server/).
+the [documentation site](https://simplysf.github.io/simply-cli/atlassian/guides/mcp-server/).
 
 ## Install
 
 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.
 
@@ -35,7 +45,7 @@ forms.
 ## Connection settings
 
 The server reads the same variables as the CLI, described in the
-[Credentials](https://simplysf.github.io/simply-atlassian/guides/credentials/) guide:
+[Credentials](https://simplysf.github.io/simply-cli/atlassian/guides/credentials/) guide:
 
 ```
 JIRA_URL=https://your-site.atlassian.net
@@ -233,7 +243,7 @@ into:
 
 Each tool's inputs are the matching command's arguments and flags in camel case, with arrays where
 the CLI takes a repeatable or comma-separated flag; see the CLI's
-[command reference](https://simplysf.github.io/simply-atlassian/reference/) for what each does.
+[command reference](https://simplysf.github.io/simply-cli/atlassian/reference/) for what each does.
 The first request above, for instance, becomes a call like:
 
 ```json
@@ -272,7 +282,7 @@ to also register the tools that create, update, transition, comment, link, and d
 `ATLASSIAN_READ_ONLY` in the environment refuses every write, exactly as it does for the CLI.
 
 That mirrors the two-credential-file arrangement in
-[Write safety](https://simplysf.github.io/simply-atlassian/guides/write-safety/): give the agent's
+[Write safety](https://simplysf.github.io/simply-cli/atlassian/guides/write-safety/): give the agent's
 everyday server a read-scoped token, and configure a second server entry with `--allow-writes` and
 a write-capable token that is enabled only when a person means to let the agent write. In a
 `mcpServers` configuration the pair looks like this:
@@ -357,7 +367,7 @@ result whose text is a JSON object with a stable `code`:
 
 The first three carry the same `name`, `message`, and `exitCode` the CLI writes to stderr,
 scrubbed the same way, as described in
-[Scripts and agents](https://simplysf.github.io/simply-atlassian/guides/scripting/). The agent
+[Scripts and agents](https://simplysf.github.io/simply-cli/atlassian/guides/scripting/). The agent
 sees these errors and can act on them, so a wrong key or a missing setting usually ends in the
 agent telling you what went wrong rather than in silence.
 

package/docs/guides/mcp-server.md

@@ -0,0 +1,402 @@
+---
+title: MCP server
+description: Give an AI agent in Claude Desktop, Claude Code, Cursor, Gemini CLI, or VS Code the same Jira and Confluence capabilities as the CLI, as Model Context Protocol tools, read-only by default.
+---
+
+`@simplysf/simply-atlassian-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io/)
+server with one tool per CLI command. It calls the same library the CLI is built on, in-process,
+so the agent gets the same credential handling, `dryRun` previews, read-only guard, and error
+messages described elsewhere in these guides, and the same raw JSON the CLI prints with `--json`.
+
+Using it takes four steps: install the server, tell your MCP client how to launch it, check the
+connection, then ask the agent for what you want in plain language. This page walks through each,
+then covers letting the agent write, the full tool list, results and errors, and what to check when
+something does not work.
+
+## Install
+
+The server needs Node.js 22 or later.
+
+```sh
+npm install -g @simplysf/simply-atlassian-mcp
+simply-atlassian-mcp --help
+```
+
+`--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.
+
+You can skip the global install and have the client fetch the package on demand with
+`npx -y @simplysf/simply-atlassian-mcp` as the command; the client configurations below show both
+forms.
+
+## Connection settings
+
+The server reads the same variables as the CLI, described in [Credentials](/guides/credentials/):
+
+```
+JIRA_URL=https://your-site.atlassian.net
+JIRA_USERNAME=you@example.com
+JIRA_API_TOKEN=...
+
+CONFLUENCE_URL=https://your-site.atlassian.net
+CONFLUENCE_USERNAME=you@example.com
+CONFLUENCE_API_TOKEN=...
+```
+
+Put them in a `.env` file and pass it with `--env-file`, or set them in the `env` block of the
+client's server entry. A variable already in the environment wins over the file, as it does for
+the CLI. Settings are resolved when a tool is called rather than at startup, so a server given only
+the `JIRA_*` variables still serves every Jira tool; only the Confluence tools report a missing
+setting.
+
+Use an absolute path for the env file. MCP clients launch the server from a working directory of
+their own, so `~` and relative paths may not resolve. On Windows, write the path with forward
+slashes or doubled backslashes inside JSON: `"C:/Users/me/atlassian.env"`.
+
+## Configure a client
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Windows:
+`%APPDATA%\Claude\`) and restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian": {
+      "command": "simply",
+      "args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
+    }
+  }
+}
+```
+
+The same entry with the settings inline and no global install:
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian": {
+      "command": "npx",
+      "args": ["atlassian", "mcp"],
+      "env": {
+        "JIRA_URL": "https://your-site.atlassian.net",
+        "JIRA_USERNAME": "you@example.com",
+        "JIRA_API_TOKEN": "..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```sh
+claude mcp add simply-atlassian -- simply-atlassian-mcp --env-file ~/atlassian.env
+```
+
+Add `--scope project` to write the entry to a `.mcp.json` at the repository root instead, which
+can be committed so a team shares the server definition. Keep tokens out of a committed file by
+pointing at an env file each person holds locally. Inside a session, `/mcp` lists the configured
+servers and whether each one connected.
+
+### Cursor
+
+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",
+      "args": ["atlassian", "mcp", "--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": ["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",
+      "args": ["atlassian", "mcp", "--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:
+
+```json
+{
+  "servers": {
+    "simply-atlassian": {
+      "type": "stdio",
+      "command": "simply",
+      "args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
+    }
+  }
+}
+```
+
+### Any other client
+
+The server speaks MCP over stdio, so any client that can launch a local command works: give it the
+command, its arguments, and optionally an environment, as above. It announces itself as
+`simply-atlassian` with the package version during the handshake and supplies instructions that
+summarise the tool conventions for the host's model.
+
+## Check the connection
+
+Ask the agent which Jira account it is connected as. It should call `jira_whoami`, whose
+description tells the model to use it first for exactly this purpose, and report back the account
+the credentials resolve to. If it does, the server is running and the credentials work; the
+[troubleshooting](#troubleshooting) table covers the cases where it does not.
+
+## Ask for what you want
+
+You do not call tools yourself. Describe the outcome, and the agent chooses the tools and fills in
+their inputs from the descriptions the server publishes. Some examples of what a request turns
+into:
+
+| You ask                                               | The agent calls                                                                                                 |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| "What's open in PROJ and assigned to me?"             | `jira_issue_search` with `jql` such as `project = PROJ AND assignee = currentUser() AND statusCategory != Done` |
+| "Summarise PROJ-42 and its comments."                 | `jira_issue_view`, then `jira_issue_comment_list`                                                               |
+| "Who changed the priority on PROJ-42, and when?"      | `jira_issue_history` with `field: "priority"`                                                                   |
+| "What's in the current sprint on the Platform board?" | `jira_board_list` to find the board id, `jira_sprint_list` for the active sprint, then `jira_sprint_issues`     |
+| "Find our release-notes pages in the DOCS space."     | `confluence_page_search` with a CQL query                                                                       |
+| "Give me a link to PROJ-42."                          | `jira_open`, which returns the URL rather than launching a browser                                              |
+
+Each tool's inputs are the matching command's arguments and flags in camel case, with arrays where
+the CLI takes a repeatable or comma-separated flag; see the [Command Reference](/reference/) for
+what each does. The first request above, for instance, becomes a call like:
+
+```json
+{
+  "jql": "project = PROJ AND assignee = currentUser() AND statusCategory != Done",
+  "fields": ["summary", "status", "priority"],
+  "limit": 50
+}
+```
+
+and returns the same envelope the CLI prints under `--json`:
+
+```json
+{ "issues": [...], "pages": 1, "complete": true }
+```
+
+A few things make the agent's job easier:
+
+- **Name the fields you care about.** `fields` on the issue tools matters as much here as in the
+  CLI: raw issue payloads are large, and an agent pays for every token it reads. "Show me the
+  summary and status of..." lets it ask for only those.
+- **Name boards and sprints; the agent resolves the numbers.** The sprint tools take numeric ids,
+  which the agent looks up with `jira_board_list` and `jira_sprint_list`.
+- **Transitions go by name.** "Move it to Done" works; when unsure what the workflow allows, the
+  agent can call `jira_issue_transitions` first.
+- **Mention people by name or email.** `mentions` resolves them to account ids; an ambiguous name
+  comes back as an error listing the candidates, so the agent can ask you which one.
+- **Paste Confluence URLs.** Every page input accepts a page id or a page URL.
+- **`open` tools return URLs.** A server cannot launch a browser, so `jira_open` and
+  `confluence_open` hand back the address for you to follow.
+
+## Let the agent write
+
+Started without options, the server registers only the read tools. Start it with `--allow-writes`
+to also register the tools that create, update, transition, comment, link, and delete. Even then,
+`ATLASSIAN_READ_ONLY` in the environment refuses every write, exactly as it does for the CLI.
+
+That mirrors the two-credential-file arrangement in [Write safety](/guides/write-safety/): give the
+agent's everyday server a read-scoped token, and configure a second server entry with
+`--allow-writes` and a write-capable token that is enabled only when a person means to let the
+agent write. In a `mcpServers` configuration the pair looks like this:
+
+```json
+{
+  "mcpServers": {
+    "simply-atlassian": {
+      "command": "simply",
+      "args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
+    },
+    "simply-atlassian-write": {
+      "command": "simply",
+      "args": ["atlassian", "mcp", "--allow-writes", "--env-file", "/home/me/atlassian-write.env"]
+    }
+  }
+}
+```
+
+A read-scoped token is still the only layer that binds; the server-side default just keeps write
+tools out of the agent's normal loop entirely. Most clients also ask you to approve each tool call,
+and the tools carry MCP annotations (`readOnlyHint`, `destructiveHint`) so a host can tell a read
+from a delete when it asks.
+
+With writes allowed:
+
+- **Ask for a preview first.** Every write tool accepts `dryRun: true`, which returns the request
+  that would be sent without sending it. "Show me what you'd send to move PROJ-42 to Done with a
+  comment, then do it" produces a call like the one below, which you can check before the agent
+  repeats it without `dryRun`.
+
+  ```json
+  { "issue": "PROJ-42", "transition": "Done", "comment": "Verified in staging.", "dryRun": true }
+  ```
+
+- **Irreversible deletes need consent.** `jira_issue_delete` and `jira_issue_comment_delete`
+  require `confirm: true`, and so does `confluence_page_delete` with `purge: true`. A call without
+  it is answered with a `confirm-required` error before anything is looked up, and the message
+  names the input to add, so the agent will come back and ask you. Trashing a page needs no
+  `confirm`, because it is reversible.
+- **Confluence bodies can be Markdown.** The page and comment tools take a body as `text` (plain
+  prose), raw storage-format `body`, or `markdown` (converted to storage format), and
+  `confluence_page_update` takes `append` to add to a page instead of replacing it. "Add a
+  Decisions section to this page with these three bullets" becomes `confluence_page_update` with
+  `markdown` and `append: true`.
+
+## Tools
+
+| Read tools                     | Write tools (`--allow-writes`)                          |
+| ------------------------------ | ------------------------------------------------------- |
+| `jira_whoami`                  | `jira_issue_create`                                     |
+| `jira_user_search`             | `jira_issue_update`                                     |
+| `jira_user_view`               | `jira_issue_transition`                                 |
+| `jira_open`                    | `jira_issue_delete` (needs `confirm`)                   |
+| `jira_issue_search`            | `jira_issue_comment_add`                                |
+| `jira_issue_view`              | `jira_issue_comment_edit`                               |
+| `jira_issue_history`           | `jira_issue_comment_delete` (needs `confirm`)           |
+| `jira_issue_transitions`       | `jira_issue_link_create`                                |
+| `jira_issue_comment_list`      | `jira_issue_link_delete`                                |
+| `jira_issue_link_list`         | `jira_sprint_add`                                       |
+| `jira_issue_link_types`        | `confluence_page_create`                                |
+| `jira_board_list`              | `confluence_page_update`                                |
+| `jira_sprint_list`             | `confluence_page_delete` (needs `confirm` with `purge`) |
+| `jira_sprint_issues`           | `confluence_page_comment_add`                           |
+| `confluence_open`              |                                                         |
+| `confluence_page_get`          |                                                         |
+| `confluence_page_search`       |                                                         |
+| `confluence_page_children`     |                                                         |
+| `confluence_page_comment_list` |                                                         |
+
+## Results and errors
+
+A successful call returns what the CLI prints with `--json`, verbatim. A failure returns an error
+result whose text is a JSON object with a stable `code`:
+
+| `code`             | Meaning                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| `config`           | Missing or contradictory settings, a refused write, bad input.                       |
+| `auth`             | The instance rejected the credentials; carries the HTTP `status`.                    |
+| `error`            | Any other failure, including an API error with its HTTP `status` and sanitised body. |
+| `confirm-required` | A destructive tool was called without `confirm: true`.                               |
+
+The first three map one-to-one onto the CLI's exit codes 2, 3, and 1, described in
+[Scripts and agents](/guides/scripting/), and carry the same `name` and `message`, scrubbed of
+credentials and control characters the same way. The agent sees these errors and can act on them,
+so a wrong key or a missing setting usually ends in the agent telling you what went wrong rather
+than in silence.
+
+## Troubleshooting
+
+Run `simply-atlassian-mcp --help` at a terminal first. If it prints the tool list, the package is
+installed and working, and the problem is in how the client launches it or what it passes.
+
+| Symptom                                                           | Cause and fix                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| The client reports the server failed to start                     | Desktop apps do not load your shell profile, so the command may not be on their `PATH`. Use the full path to the executable (it lives in the directory `npm prefix -g` reports, under `bin/` on macOS and Linux), or the `npx` form above. |
+| The client's log says `Env file ... not found.`                   | The only startup failure. The path is wrong or relative; make it absolute. The server exits with code 2.                                                                                                                                   |
+| Every tool returns `code: "config"` naming `JIRA_URL`             | The settings are not reaching the server: the env file is not being read, or the variables were set in a shell the client did not inherit. Pass `--env-file` or an `env` block explicitly.                                                 |
+| Confluence tools fail with `code: "config"` while Jira works      | Only the `JIRA_*` variables are set. Add the `CONFLUENCE_*` ones; each product's settings are resolved separately.                                                                                                                         |
+| `code: "auth"` with status `401`                                  | The instance rejected the credentials. Cloud needs `JIRA_USERNAME` plus `JIRA_API_TOKEN`; Server/Data Center needs `JIRA_PERSONAL_TOKEN` alone. Set one style, not both.                                                                   |
+| `code: "auth"` with status `403` on a write                       | The token is read-scoped, which is the intended outcome for the everyday server. Use the write-capable server entry for this change.                                                                                                       |
+| The agent says it has no tool to create, update, or delete        | The server was started without `--allow-writes`. That is the default; see [Let the agent write](#let-the-agent-write).                                                                                                                     |
+| A write returns `code: "config"` mentioning `ATLASSIAN_READ_ONLY` | The variable is set in the environment or the env file. Unset it, or point the write server at a credential file meant for writing.                                                                                                        |
+
+## Embed in your own process
+
+The stdio binary is the usual way to run the server, but the package also exports what it is
+built from, so a host process can serve the same tools over a transport of its choosing:
+
+```js
+import { createServer, startServer } from '@simplysf/simply-atlassian-mcp';
+
+// Serve over stdio, exactly as the binary does.
+await startServer({ allowWrites: false, envFile: '/home/me/atlassian.env' });
+
+// Or build the server and attach a transport yourself.
+const server = createServer({ allowWrites: true, env: process.env });
+await server.connect(transport);
+```
+
+`createServer` returns the MCP SDK's `McpServer` with the tools registered and nothing connected.
+`TOOLS` is the full catalogue, `selectTools(allowWrites)` is the subset a given configuration
+registers, and `invokeTool` and `mapError` run one tool and map a failure onto the error object
+above, for tests and hosts that need to drive the server without a transport.
+
+## Options
+
+```
+simply-atlassian-mcp [--allow-writes] [--env-file <path>]
+```
+
+`--help` prints the options and the full tool list. Because stdout is the protocol stream, it
+prints to stderr.

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.6.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.2",
+  "version": "0.6.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-atlassian",
   "bugs": "https://github.com/SimplySF/simply-atlassian/issues",
@@ -14,7 +14,9 @@
     "node": ">=22.0.0"
   },
   "files": [
-    "/lib"
+    "/docs",
+    "/lib",
+    "/oclif.manifest.json"
   ],
   "keywords": [
     "mcp",
@@ -33,11 +35,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@simplysf/simply-atlassian-core": "^0.5.0",
+    "@oclif/core": "^4.11.2",
+    "@simplysf/simply-atlassian-core": "^0.6.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 +54,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 +174,15 @@
       "service": true
     }
   },
-  "gitHead": "00dc34e673af42a05947595409e63cad9bd37d62"
+  "oclif": {
+    "bin": "simply",
+    "commands": "./lib/commands",
+    "topicSeparator": " ",
+    "topics": {
+      "atlassian": {
+        "description": "Work with Atlassian products."
+      }
+    }
+  },
+  "gitHead": "bde6b82c40ca4d9312eb8960cea1fdcd61931078"
 }