@simplysf/simply-atlassian-mcp 0.5.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/docs/guides/mcp-server.md +402 -0
- package/oclif.manifest.json +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -14,7 +14,7 @@ Using it takes four steps: install the server, tell your MCP client how to launc
|
|
|
14
14
|
connection, then ask the agent for what you want in plain language. This README walks through
|
|
15
15
|
each, then covers letting the agent write, the full tool list, results and errors, and what to
|
|
16
16
|
check when something does not work. The same material, with the rest of the CLI's guides, is on
|
|
17
|
-
the [documentation site](https://simplysf.github.io/simply-atlassian/guides/mcp-server/).
|
|
17
|
+
the [documentation site](https://simplysf.github.io/simply-cli/atlassian/guides/mcp-server/).
|
|
18
18
|
|
|
19
19
|
## Install
|
|
20
20
|
|
|
@@ -45,7 +45,7 @@ forms.
|
|
|
45
45
|
## Connection settings
|
|
46
46
|
|
|
47
47
|
The server reads the same variables as the CLI, described in the
|
|
48
|
-
[Credentials](https://simplysf.github.io/simply-atlassian/guides/credentials/) guide:
|
|
48
|
+
[Credentials](https://simplysf.github.io/simply-cli/atlassian/guides/credentials/) guide:
|
|
49
49
|
|
|
50
50
|
```
|
|
51
51
|
JIRA_URL=https://your-site.atlassian.net
|
|
@@ -243,7 +243,7 @@ into:
|
|
|
243
243
|
|
|
244
244
|
Each tool's inputs are the matching command's arguments and flags in camel case, with arrays where
|
|
245
245
|
the CLI takes a repeatable or comma-separated flag; see the CLI's
|
|
246
|
-
[command reference](https://simplysf.github.io/simply-atlassian/reference/) for what each does.
|
|
246
|
+
[command reference](https://simplysf.github.io/simply-cli/atlassian/reference/) for what each does.
|
|
247
247
|
The first request above, for instance, becomes a call like:
|
|
248
248
|
|
|
249
249
|
```json
|
|
@@ -282,7 +282,7 @@ to also register the tools that create, update, transition, comment, link, and d
|
|
|
282
282
|
`ATLASSIAN_READ_ONLY` in the environment refuses every write, exactly as it does for the CLI.
|
|
283
283
|
|
|
284
284
|
That mirrors the two-credential-file arrangement in
|
|
285
|
-
[Write safety](https://simplysf.github.io/simply-atlassian/guides/write-safety/): give the agent's
|
|
285
|
+
[Write safety](https://simplysf.github.io/simply-cli/atlassian/guides/write-safety/): give the agent's
|
|
286
286
|
everyday server a read-scoped token, and configure a second server entry with `--allow-writes` and
|
|
287
287
|
a write-capable token that is enabled only when a person means to let the agent write. In a
|
|
288
288
|
`mcpServers` configuration the pair looks like this:
|
|
@@ -367,7 +367,7 @@ result whose text is a JSON object with a stable `code`:
|
|
|
367
367
|
|
|
368
368
|
The first three carry the same `name`, `message`, and `exitCode` the CLI writes to stderr,
|
|
369
369
|
scrubbed the same way, as described in
|
|
370
|
-
[Scripts and agents](https://simplysf.github.io/simply-atlassian/guides/scripting/). The agent
|
|
370
|
+
[Scripts and agents](https://simplysf.github.io/simply-cli/atlassian/guides/scripting/). The agent
|
|
371
371
|
sees these errors and can act on them, so a wrong key or a missing setting usually ends in the
|
|
372
372
|
agent telling you what went wrong rather than in silence.
|
|
373
373
|
|
|
@@ -0,0 +1,402 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: MCP server
|
|
3
|
+
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.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
`@simplysf/simply-atlassian-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io/)
|
|
7
|
+
server with one tool per CLI command. It calls the same library the CLI is built on, in-process,
|
|
8
|
+
so the agent gets the same credential handling, `dryRun` previews, read-only guard, and error
|
|
9
|
+
messages described elsewhere in these guides, and the same raw JSON the CLI prints with `--json`.
|
|
10
|
+
|
|
11
|
+
Using it takes four steps: install the server, tell your MCP client how to launch it, check the
|
|
12
|
+
connection, then ask the agent for what you want in plain language. This page walks through each,
|
|
13
|
+
then covers letting the agent write, the full tool list, results and errors, and what to check when
|
|
14
|
+
something does not work.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
The server needs Node.js 22 or later.
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
npm install -g @simplysf/simply-atlassian-mcp
|
|
22
|
+
simply-atlassian-mcp --help
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`--help` prints the options and every tool the server can register, so it doubles as a check that
|
|
26
|
+
the install worked. It prints to stderr, because stdout is reserved for the protocol stream.
|
|
27
|
+
|
|
28
|
+
You can skip the global install and have the client fetch the package on demand with
|
|
29
|
+
`npx -y @simplysf/simply-atlassian-mcp` as the command; the client configurations below show both
|
|
30
|
+
forms.
|
|
31
|
+
|
|
32
|
+
## Connection settings
|
|
33
|
+
|
|
34
|
+
The server reads the same variables as the CLI, described in [Credentials](/guides/credentials/):
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
JIRA_URL=https://your-site.atlassian.net
|
|
38
|
+
JIRA_USERNAME=you@example.com
|
|
39
|
+
JIRA_API_TOKEN=...
|
|
40
|
+
|
|
41
|
+
CONFLUENCE_URL=https://your-site.atlassian.net
|
|
42
|
+
CONFLUENCE_USERNAME=you@example.com
|
|
43
|
+
CONFLUENCE_API_TOKEN=...
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Put them in a `.env` file and pass it with `--env-file`, or set them in the `env` block of the
|
|
47
|
+
client's server entry. A variable already in the environment wins over the file, as it does for
|
|
48
|
+
the CLI. Settings are resolved when a tool is called rather than at startup, so a server given only
|
|
49
|
+
the `JIRA_*` variables still serves every Jira tool; only the Confluence tools report a missing
|
|
50
|
+
setting.
|
|
51
|
+
|
|
52
|
+
Use an absolute path for the env file. MCP clients launch the server from a working directory of
|
|
53
|
+
their own, so `~` and relative paths may not resolve. On Windows, write the path with forward
|
|
54
|
+
slashes or doubled backslashes inside JSON: `"C:/Users/me/atlassian.env"`.
|
|
55
|
+
|
|
56
|
+
## Configure a client
|
|
57
|
+
|
|
58
|
+
### Claude Desktop
|
|
59
|
+
|
|
60
|
+
Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Windows:
|
|
61
|
+
`%APPDATA%\Claude\`) and restart Claude Desktop:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"simply-atlassian": {
|
|
67
|
+
"command": "simply",
|
|
68
|
+
"args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The same entry with the settings inline and no global install:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"mcpServers": {
|
|
79
|
+
"simply-atlassian": {
|
|
80
|
+
"command": "npx",
|
|
81
|
+
"args": ["atlassian", "mcp"],
|
|
82
|
+
"env": {
|
|
83
|
+
"JIRA_URL": "https://your-site.atlassian.net",
|
|
84
|
+
"JIRA_USERNAME": "you@example.com",
|
|
85
|
+
"JIRA_API_TOKEN": "..."
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Claude Code
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
claude mcp add simply-atlassian -- simply-atlassian-mcp --env-file ~/atlassian.env
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Add `--scope project` to write the entry to a `.mcp.json` at the repository root instead, which
|
|
99
|
+
can be committed so a team shares the server definition. Keep tokens out of a committed file by
|
|
100
|
+
pointing at an env file each person holds locally. Inside a session, `/mcp` lists the configured
|
|
101
|
+
servers and whether each one connected.
|
|
102
|
+
|
|
103
|
+
### Cursor
|
|
104
|
+
|
|
105
|
+
Cursor reads `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project, with
|
|
106
|
+
the same `mcpServers` shape as Claude Desktop.
|
|
107
|
+
|
|
108
|
+
### Gemini CLI
|
|
109
|
+
|
|
110
|
+
Gemini CLI reads `~/.gemini/settings.json` for every project, or `.gemini/settings.json` inside a
|
|
111
|
+
project, with the same `mcpServers` shape as Claude Desktop:
|
|
112
|
+
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"mcpServers": {
|
|
116
|
+
"simply-atlassian": {
|
|
117
|
+
"command": "simply",
|
|
118
|
+
"args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`gemini mcp add` writes the same entry. `--scope user` puts it in the global file; the default
|
|
125
|
+
`project` scope writes `.gemini/settings.json`, and `-e` sets one variable on the entry:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
gemini mcp add --scope user \
|
|
129
|
+
-e JIRA_URL=https://your-site.atlassian.net \
|
|
130
|
+
-e JIRA_USERNAME=you@example.com \
|
|
131
|
+
-e JIRA_API_TOKEN=... \
|
|
132
|
+
simply-atlassian simply-atlassian-mcp
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Flags meant for the server itself, `--env-file` and `--allow-writes`, are easier to add by editing
|
|
136
|
+
`settings.json`, because `gemini mcp add` reads a leading-dash argument as one of its own options.
|
|
137
|
+
|
|
138
|
+
Values in `env` expand `$NAME` from the environment Gemini started in, which keeps the token out of
|
|
139
|
+
the settings file without an env file:
|
|
140
|
+
|
|
141
|
+
```json
|
|
142
|
+
{
|
|
143
|
+
"mcpServers": {
|
|
144
|
+
"simply-atlassian": {
|
|
145
|
+
"command": "npx",
|
|
146
|
+
"args": ["atlassian", "mcp"],
|
|
147
|
+
"env": {
|
|
148
|
+
"JIRA_URL": "https://your-site.atlassian.net",
|
|
149
|
+
"JIRA_USERNAME": "you@example.com",
|
|
150
|
+
"JIRA_API_TOKEN": "$JIRA_API_TOKEN"
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Two other fields on an entry matter here. `trust: true` bypasses the per-call confirmation for
|
|
158
|
+
every tool on that server, so leave it off on any entry started with `--allow-writes` and let a
|
|
159
|
+
person approve each write. `includeTools` and `excludeTools` narrow what the model is shown, which
|
|
160
|
+
is a second way to express the split in [Let the agent write](#let-the-agent-write): a write entry
|
|
161
|
+
can register the write tools while holding back the destructive ones.
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"mcpServers": {
|
|
166
|
+
"simply-atlassian-write": {
|
|
167
|
+
"command": "simply",
|
|
168
|
+
"args": ["atlassian", "mcp", "--allow-writes", "--env-file", "/home/me/atlassian-write.env"],
|
|
169
|
+
"excludeTools": ["jira_issue_delete", "jira_issue_comment_delete", "confluence_page_delete"],
|
|
170
|
+
"trust": false
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Inside a session, `/mcp` lists the configured servers, whether each connected, and the tools it
|
|
177
|
+
registered.
|
|
178
|
+
|
|
179
|
+
### Gemini Code Assist
|
|
180
|
+
|
|
181
|
+
Agent mode in the VS Code extension reads that same `~/.gemini/settings.json`, so an entry added
|
|
182
|
+
for Gemini CLI is already in place. In IntelliJ the file is `mcp.json` in the IDE's configuration
|
|
183
|
+
directory, holding the same `mcpServers` object.
|
|
184
|
+
|
|
185
|
+
### VS Code
|
|
186
|
+
|
|
187
|
+
VS Code reads `.vscode/mcp.json`, with a `servers` key and an explicit transport type:
|
|
188
|
+
|
|
189
|
+
```json
|
|
190
|
+
{
|
|
191
|
+
"servers": {
|
|
192
|
+
"simply-atlassian": {
|
|
193
|
+
"type": "stdio",
|
|
194
|
+
"command": "simply",
|
|
195
|
+
"args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Any other client
|
|
202
|
+
|
|
203
|
+
The server speaks MCP over stdio, so any client that can launch a local command works: give it the
|
|
204
|
+
command, its arguments, and optionally an environment, as above. It announces itself as
|
|
205
|
+
`simply-atlassian` with the package version during the handshake and supplies instructions that
|
|
206
|
+
summarise the tool conventions for the host's model.
|
|
207
|
+
|
|
208
|
+
## Check the connection
|
|
209
|
+
|
|
210
|
+
Ask the agent which Jira account it is connected as. It should call `jira_whoami`, whose
|
|
211
|
+
description tells the model to use it first for exactly this purpose, and report back the account
|
|
212
|
+
the credentials resolve to. If it does, the server is running and the credentials work; the
|
|
213
|
+
[troubleshooting](#troubleshooting) table covers the cases where it does not.
|
|
214
|
+
|
|
215
|
+
## Ask for what you want
|
|
216
|
+
|
|
217
|
+
You do not call tools yourself. Describe the outcome, and the agent chooses the tools and fills in
|
|
218
|
+
their inputs from the descriptions the server publishes. Some examples of what a request turns
|
|
219
|
+
into:
|
|
220
|
+
|
|
221
|
+
| You ask | The agent calls |
|
|
222
|
+
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
223
|
+
| "What's open in PROJ and assigned to me?" | `jira_issue_search` with `jql` such as `project = PROJ AND assignee = currentUser() AND statusCategory != Done` |
|
|
224
|
+
| "Summarise PROJ-42 and its comments." | `jira_issue_view`, then `jira_issue_comment_list` |
|
|
225
|
+
| "Who changed the priority on PROJ-42, and when?" | `jira_issue_history` with `field: "priority"` |
|
|
226
|
+
| "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` |
|
|
227
|
+
| "Find our release-notes pages in the DOCS space." | `confluence_page_search` with a CQL query |
|
|
228
|
+
| "Give me a link to PROJ-42." | `jira_open`, which returns the URL rather than launching a browser |
|
|
229
|
+
|
|
230
|
+
Each tool's inputs are the matching command's arguments and flags in camel case, with arrays where
|
|
231
|
+
the CLI takes a repeatable or comma-separated flag; see the [Command Reference](/reference/) for
|
|
232
|
+
what each does. The first request above, for instance, becomes a call like:
|
|
233
|
+
|
|
234
|
+
```json
|
|
235
|
+
{
|
|
236
|
+
"jql": "project = PROJ AND assignee = currentUser() AND statusCategory != Done",
|
|
237
|
+
"fields": ["summary", "status", "priority"],
|
|
238
|
+
"limit": 50
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
and returns the same envelope the CLI prints under `--json`:
|
|
243
|
+
|
|
244
|
+
```json
|
|
245
|
+
{ "issues": [...], "pages": 1, "complete": true }
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
A few things make the agent's job easier:
|
|
249
|
+
|
|
250
|
+
- **Name the fields you care about.** `fields` on the issue tools matters as much here as in the
|
|
251
|
+
CLI: raw issue payloads are large, and an agent pays for every token it reads. "Show me the
|
|
252
|
+
summary and status of..." lets it ask for only those.
|
|
253
|
+
- **Name boards and sprints; the agent resolves the numbers.** The sprint tools take numeric ids,
|
|
254
|
+
which the agent looks up with `jira_board_list` and `jira_sprint_list`.
|
|
255
|
+
- **Transitions go by name.** "Move it to Done" works; when unsure what the workflow allows, the
|
|
256
|
+
agent can call `jira_issue_transitions` first.
|
|
257
|
+
- **Mention people by name or email.** `mentions` resolves them to account ids; an ambiguous name
|
|
258
|
+
comes back as an error listing the candidates, so the agent can ask you which one.
|
|
259
|
+
- **Paste Confluence URLs.** Every page input accepts a page id or a page URL.
|
|
260
|
+
- **`open` tools return URLs.** A server cannot launch a browser, so `jira_open` and
|
|
261
|
+
`confluence_open` hand back the address for you to follow.
|
|
262
|
+
|
|
263
|
+
## Let the agent write
|
|
264
|
+
|
|
265
|
+
Started without options, the server registers only the read tools. Start it with `--allow-writes`
|
|
266
|
+
to also register the tools that create, update, transition, comment, link, and delete. Even then,
|
|
267
|
+
`ATLASSIAN_READ_ONLY` in the environment refuses every write, exactly as it does for the CLI.
|
|
268
|
+
|
|
269
|
+
That mirrors the two-credential-file arrangement in [Write safety](/guides/write-safety/): give the
|
|
270
|
+
agent's everyday server a read-scoped token, and configure a second server entry with
|
|
271
|
+
`--allow-writes` and a write-capable token that is enabled only when a person means to let the
|
|
272
|
+
agent write. In a `mcpServers` configuration the pair looks like this:
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
{
|
|
276
|
+
"mcpServers": {
|
|
277
|
+
"simply-atlassian": {
|
|
278
|
+
"command": "simply",
|
|
279
|
+
"args": ["atlassian", "mcp", "--env-file", "/home/me/atlassian.env"]
|
|
280
|
+
},
|
|
281
|
+
"simply-atlassian-write": {
|
|
282
|
+
"command": "simply",
|
|
283
|
+
"args": ["atlassian", "mcp", "--allow-writes", "--env-file", "/home/me/atlassian-write.env"]
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
A read-scoped token is still the only layer that binds; the server-side default just keeps write
|
|
290
|
+
tools out of the agent's normal loop entirely. Most clients also ask you to approve each tool call,
|
|
291
|
+
and the tools carry MCP annotations (`readOnlyHint`, `destructiveHint`) so a host can tell a read
|
|
292
|
+
from a delete when it asks.
|
|
293
|
+
|
|
294
|
+
With writes allowed:
|
|
295
|
+
|
|
296
|
+
- **Ask for a preview first.** Every write tool accepts `dryRun: true`, which returns the request
|
|
297
|
+
that would be sent without sending it. "Show me what you'd send to move PROJ-42 to Done with a
|
|
298
|
+
comment, then do it" produces a call like the one below, which you can check before the agent
|
|
299
|
+
repeats it without `dryRun`.
|
|
300
|
+
|
|
301
|
+
```json
|
|
302
|
+
{ "issue": "PROJ-42", "transition": "Done", "comment": "Verified in staging.", "dryRun": true }
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
- **Irreversible deletes need consent.** `jira_issue_delete` and `jira_issue_comment_delete`
|
|
306
|
+
require `confirm: true`, and so does `confluence_page_delete` with `purge: true`. A call without
|
|
307
|
+
it is answered with a `confirm-required` error before anything is looked up, and the message
|
|
308
|
+
names the input to add, so the agent will come back and ask you. Trashing a page needs no
|
|
309
|
+
`confirm`, because it is reversible.
|
|
310
|
+
- **Confluence bodies can be Markdown.** The page and comment tools take a body as `text` (plain
|
|
311
|
+
prose), raw storage-format `body`, or `markdown` (converted to storage format), and
|
|
312
|
+
`confluence_page_update` takes `append` to add to a page instead of replacing it. "Add a
|
|
313
|
+
Decisions section to this page with these three bullets" becomes `confluence_page_update` with
|
|
314
|
+
`markdown` and `append: true`.
|
|
315
|
+
|
|
316
|
+
## Tools
|
|
317
|
+
|
|
318
|
+
| Read tools | Write tools (`--allow-writes`) |
|
|
319
|
+
| ------------------------------ | ------------------------------------------------------- |
|
|
320
|
+
| `jira_whoami` | `jira_issue_create` |
|
|
321
|
+
| `jira_user_search` | `jira_issue_update` |
|
|
322
|
+
| `jira_user_view` | `jira_issue_transition` |
|
|
323
|
+
| `jira_open` | `jira_issue_delete` (needs `confirm`) |
|
|
324
|
+
| `jira_issue_search` | `jira_issue_comment_add` |
|
|
325
|
+
| `jira_issue_view` | `jira_issue_comment_edit` |
|
|
326
|
+
| `jira_issue_history` | `jira_issue_comment_delete` (needs `confirm`) |
|
|
327
|
+
| `jira_issue_transitions` | `jira_issue_link_create` |
|
|
328
|
+
| `jira_issue_comment_list` | `jira_issue_link_delete` |
|
|
329
|
+
| `jira_issue_link_list` | `jira_sprint_add` |
|
|
330
|
+
| `jira_issue_link_types` | `confluence_page_create` |
|
|
331
|
+
| `jira_board_list` | `confluence_page_update` |
|
|
332
|
+
| `jira_sprint_list` | `confluence_page_delete` (needs `confirm` with `purge`) |
|
|
333
|
+
| `jira_sprint_issues` | `confluence_page_comment_add` |
|
|
334
|
+
| `confluence_open` | |
|
|
335
|
+
| `confluence_page_get` | |
|
|
336
|
+
| `confluence_page_search` | |
|
|
337
|
+
| `confluence_page_children` | |
|
|
338
|
+
| `confluence_page_comment_list` | |
|
|
339
|
+
|
|
340
|
+
## Results and errors
|
|
341
|
+
|
|
342
|
+
A successful call returns what the CLI prints with `--json`, verbatim. A failure returns an error
|
|
343
|
+
result whose text is a JSON object with a stable `code`:
|
|
344
|
+
|
|
345
|
+
| `code` | Meaning |
|
|
346
|
+
| ------------------ | ------------------------------------------------------------------------------------ |
|
|
347
|
+
| `config` | Missing or contradictory settings, a refused write, bad input. |
|
|
348
|
+
| `auth` | The instance rejected the credentials; carries the HTTP `status`. |
|
|
349
|
+
| `error` | Any other failure, including an API error with its HTTP `status` and sanitised body. |
|
|
350
|
+
| `confirm-required` | A destructive tool was called without `confirm: true`. |
|
|
351
|
+
|
|
352
|
+
The first three map one-to-one onto the CLI's exit codes 2, 3, and 1, described in
|
|
353
|
+
[Scripts and agents](/guides/scripting/), and carry the same `name` and `message`, scrubbed of
|
|
354
|
+
credentials and control characters the same way. The agent sees these errors and can act on them,
|
|
355
|
+
so a wrong key or a missing setting usually ends in the agent telling you what went wrong rather
|
|
356
|
+
than in silence.
|
|
357
|
+
|
|
358
|
+
## Troubleshooting
|
|
359
|
+
|
|
360
|
+
Run `simply-atlassian-mcp --help` at a terminal first. If it prints the tool list, the package is
|
|
361
|
+
installed and working, and the problem is in how the client launches it or what it passes.
|
|
362
|
+
|
|
363
|
+
| Symptom | Cause and fix |
|
|
364
|
+
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
365
|
+
| 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. |
|
|
366
|
+
| 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. |
|
|
367
|
+
| 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. |
|
|
368
|
+
| 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. |
|
|
369
|
+
| `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. |
|
|
370
|
+
| `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. |
|
|
371
|
+
| 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). |
|
|
372
|
+
| 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. |
|
|
373
|
+
|
|
374
|
+
## Embed in your own process
|
|
375
|
+
|
|
376
|
+
The stdio binary is the usual way to run the server, but the package also exports what it is
|
|
377
|
+
built from, so a host process can serve the same tools over a transport of its choosing:
|
|
378
|
+
|
|
379
|
+
```js
|
|
380
|
+
import { createServer, startServer } from '@simplysf/simply-atlassian-mcp';
|
|
381
|
+
|
|
382
|
+
// Serve over stdio, exactly as the binary does.
|
|
383
|
+
await startServer({ allowWrites: false, envFile: '/home/me/atlassian.env' });
|
|
384
|
+
|
|
385
|
+
// Or build the server and attach a transport yourself.
|
|
386
|
+
const server = createServer({ allowWrites: true, env: process.env });
|
|
387
|
+
await server.connect(transport);
|
|
388
|
+
```
|
|
389
|
+
|
|
390
|
+
`createServer` returns the MCP SDK's `McpServer` with the tools registered and nothing connected.
|
|
391
|
+
`TOOLS` is the full catalogue, `selectTools(allowWrites)` is the subset a given configuration
|
|
392
|
+
registers, and `invokeTool` and `mapError` run one tool and map a failure onto the error object
|
|
393
|
+
above, for tests and hosts that need to drive the server without a transport.
|
|
394
|
+
|
|
395
|
+
## Options
|
|
396
|
+
|
|
397
|
+
```
|
|
398
|
+
simply-atlassian-mcp [--allow-writes] [--env-file <path>]
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
`--help` prints the options and the full tool list. Because stdout is the protocol stream, it
|
|
402
|
+
prints to stderr.
|
package/oclif.manifest.json
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@simplysf/simply-atlassian-mcp",
|
|
3
3
|
"description": "Model Context Protocol server exposing Jira and Confluence to AI agents, built on @simplysf/simply-atlassian-core",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.6.0",
|
|
5
5
|
"author": "@ClayChipps",
|
|
6
6
|
"homepage": "https://github.com/SimplySF/simply-atlassian",
|
|
7
7
|
"bugs": "https://github.com/SimplySF/simply-atlassian/issues",
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
"node": ">=22.0.0"
|
|
15
15
|
},
|
|
16
16
|
"files": [
|
|
17
|
+
"/docs",
|
|
17
18
|
"/lib",
|
|
18
19
|
"/oclif.manifest.json"
|
|
19
20
|
],
|
|
@@ -35,7 +36,7 @@
|
|
|
35
36
|
"dependencies": {
|
|
36
37
|
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
37
38
|
"@oclif/core": "^4.11.2",
|
|
38
|
-
"@simplysf/simply-atlassian-core": "^0.
|
|
39
|
+
"@simplysf/simply-atlassian-core": "^0.6.0",
|
|
39
40
|
"zod": "^4.5.4"
|
|
40
41
|
},
|
|
41
42
|
"devDependencies": {
|
|
@@ -183,5 +184,5 @@
|
|
|
183
184
|
}
|
|
184
185
|
}
|
|
185
186
|
},
|
|
186
|
-
"gitHead": "
|
|
187
|
+
"gitHead": "bde6b82c40ca4d9312eb8960cea1fdcd61931078"
|
|
187
188
|
}
|