@simplysf/simply-atlassian-mcp 0.4.0 → 0.4.1
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 +237 -25
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,25 +3,66 @@
|
|
|
3
3
|
[](https://npmjs.com/@simplysf/simply-atlassian-mcp) [](https://raw.githubusercontent.com/SimplySF/simply-atlassian/main/LICENSE.txt)
|
|
4
4
|
|
|
5
5
|
A [Model Context Protocol](https://modelcontextprotocol.io/) server that gives an AI agent in
|
|
6
|
-
Claude Desktop, Claude Code, Cursor, or any other MCP client the same Jira and Confluence
|
|
6
|
+
Claude Desktop, Claude Code, Cursor, VS Code, or any other MCP client the same Jira and Confluence
|
|
7
7
|
capabilities as the [`@simplysf/simply-atlassian`](../simply-atlassian) CLI: one tool per command,
|
|
8
8
|
calling the same [`@simplysf/simply-atlassian-core`](../simply-atlassian-core) library in-process.
|
|
9
9
|
The agent gets the CLI's credential handling, `dryRun` previews, read-only guard, credential
|
|
10
10
|
redaction, and error messages, and the same raw JSON the CLI prints with `--json`, without a
|
|
11
11
|
process per call.
|
|
12
12
|
|
|
13
|
+
Using it takes four steps: install the server, tell your MCP client how to launch it, check the
|
|
14
|
+
connection, then ask the agent for what you want in plain language. This README walks through
|
|
15
|
+
each, then covers letting the agent write, the full tool list, results and errors, and what to
|
|
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/).
|
|
18
|
+
|
|
13
19
|
## Install
|
|
14
20
|
|
|
21
|
+
The server needs Node.js 22 or later.
|
|
22
|
+
|
|
15
23
|
```bash
|
|
16
24
|
npm install -g @simplysf/simply-atlassian-mcp
|
|
25
|
+
simply-atlassian-mcp --help
|
|
17
26
|
```
|
|
18
27
|
|
|
19
|
-
|
|
28
|
+
`--help` prints the options and every tool the server can register, so it doubles as a check that
|
|
29
|
+
the install worked. It prints to stderr, because stdout is reserved for the protocol stream.
|
|
30
|
+
|
|
31
|
+
You can skip the global install and have the client fetch the package on demand with
|
|
32
|
+
`npx -y @simplysf/simply-atlassian-mcp` as the command; the client configurations below show both
|
|
33
|
+
forms.
|
|
34
|
+
|
|
35
|
+
## Connection settings
|
|
36
|
+
|
|
37
|
+
The server reads the same variables as the CLI, described in the
|
|
38
|
+
[Credentials](https://simplysf.github.io/simply-atlassian/guides/credentials/) guide:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
JIRA_URL=https://your-site.atlassian.net
|
|
42
|
+
JIRA_USERNAME=you@example.com
|
|
43
|
+
JIRA_API_TOKEN=...
|
|
44
|
+
|
|
45
|
+
CONFLUENCE_URL=https://your-site.atlassian.net
|
|
46
|
+
CONFLUENCE_USERNAME=you@example.com
|
|
47
|
+
CONFLUENCE_API_TOKEN=...
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Put them in a `.env` file and pass it with `--env-file`, or set them in the `env` block of the
|
|
51
|
+
client's server entry. A variable already in the environment wins over the file, as it does for
|
|
52
|
+
the CLI. Settings are resolved when a tool is called rather than at startup, so a server given only
|
|
53
|
+
the `JIRA_*` variables still serves every Jira tool; only the Confluence tools report a missing
|
|
54
|
+
setting.
|
|
55
|
+
|
|
56
|
+
Use an absolute path for the env file. MCP clients launch the server from a working directory of
|
|
57
|
+
their own, so `~` and relative paths may not resolve. On Windows, write the path with forward
|
|
58
|
+
slashes or doubled backslashes inside JSON: `"C:/Users/me/atlassian.env"`.
|
|
20
59
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
60
|
+
## Configure a client
|
|
61
|
+
|
|
62
|
+
### Claude Desktop
|
|
63
|
+
|
|
64
|
+
Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Windows:
|
|
65
|
+
`%APPDATA%\Claude\`) and restart Claude Desktop:
|
|
25
66
|
|
|
26
67
|
```json
|
|
27
68
|
{
|
|
@@ -34,13 +75,120 @@ guide — either as environment variables or as a file. For Claude Desktop, in
|
|
|
34
75
|
}
|
|
35
76
|
```
|
|
36
77
|
|
|
37
|
-
|
|
78
|
+
The same entry with the settings inline and no global install:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"simply-atlassian": {
|
|
84
|
+
"command": "npx",
|
|
85
|
+
"args": ["-y", "@simplysf/simply-atlassian-mcp"],
|
|
86
|
+
"env": {
|
|
87
|
+
"JIRA_URL": "https://your-site.atlassian.net",
|
|
88
|
+
"JIRA_USERNAME": "you@example.com",
|
|
89
|
+
"JIRA_API_TOKEN": "..."
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Claude Code
|
|
38
97
|
|
|
39
98
|
```sh
|
|
40
99
|
claude mcp add simply-atlassian -- simply-atlassian-mcp --env-file ~/atlassian.env
|
|
41
100
|
```
|
|
42
101
|
|
|
43
|
-
|
|
102
|
+
Add `--scope project` to write the entry to a `.mcp.json` at the repository root instead, which
|
|
103
|
+
can be committed so a team shares the server definition. Keep tokens out of a committed file by
|
|
104
|
+
pointing at an env file each person holds locally. Inside a session, `/mcp` lists the configured
|
|
105
|
+
servers and whether each one connected.
|
|
106
|
+
|
|
107
|
+
### Cursor
|
|
108
|
+
|
|
109
|
+
Cursor reads `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project, with
|
|
110
|
+
the same `mcpServers` shape as Claude Desktop.
|
|
111
|
+
|
|
112
|
+
### VS Code
|
|
113
|
+
|
|
114
|
+
VS Code reads `.vscode/mcp.json`, with a `servers` key and an explicit transport type:
|
|
115
|
+
|
|
116
|
+
```json
|
|
117
|
+
{
|
|
118
|
+
"servers": {
|
|
119
|
+
"simply-atlassian": {
|
|
120
|
+
"type": "stdio",
|
|
121
|
+
"command": "simply-atlassian-mcp",
|
|
122
|
+
"args": ["--env-file", "/home/me/atlassian.env"]
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Any other client
|
|
129
|
+
|
|
130
|
+
The server speaks MCP over stdio, so any client that can launch a local command works: give it the
|
|
131
|
+
command, its arguments, and optionally an environment, as above. It announces itself as
|
|
132
|
+
`simply-atlassian` with the package version during the handshake and supplies instructions that
|
|
133
|
+
summarise the tool conventions for the host's model.
|
|
134
|
+
|
|
135
|
+
## Check the connection
|
|
136
|
+
|
|
137
|
+
Ask the agent which Jira account it is connected as. It should call `jira_whoami`, whose
|
|
138
|
+
description tells the model to use it first for exactly this purpose, and report back the account
|
|
139
|
+
the credentials resolve to. If it does, the server is running and the credentials work; the
|
|
140
|
+
[troubleshooting](#troubleshooting) table covers the cases where it does not.
|
|
141
|
+
|
|
142
|
+
## Ask for what you want
|
|
143
|
+
|
|
144
|
+
You do not call tools yourself. Describe the outcome, and the agent chooses the tools and fills in
|
|
145
|
+
their inputs from the descriptions the server publishes. Some examples of what a request turns
|
|
146
|
+
into:
|
|
147
|
+
|
|
148
|
+
| You ask | The agent calls |
|
|
149
|
+
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
150
|
+
| "What's open in PROJ and assigned to me?" | `jira_issue_search` with `jql` such as `project = PROJ AND assignee = currentUser() AND statusCategory != Done` |
|
|
151
|
+
| "Summarise PROJ-42 and its comments." | `jira_issue_view`, then `jira_issue_comment_list` |
|
|
152
|
+
| "Who changed the priority on PROJ-42, and when?" | `jira_issue_history` with `field: "priority"` |
|
|
153
|
+
| "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` |
|
|
154
|
+
| "Find our release-notes pages in the DOCS space." | `confluence_page_search` with a CQL query |
|
|
155
|
+
| "Give me a link to PROJ-42." | `jira_open`, which returns the URL rather than launching a browser |
|
|
156
|
+
|
|
157
|
+
Each tool's inputs are the matching command's arguments and flags in camel case, with arrays where
|
|
158
|
+
the CLI takes a repeatable or comma-separated flag; see the CLI's
|
|
159
|
+
[command reference](https://simplysf.github.io/simply-atlassian/reference/) for what each does.
|
|
160
|
+
The first request above, for instance, becomes a call like:
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"jql": "project = PROJ AND assignee = currentUser() AND statusCategory != Done",
|
|
165
|
+
"fields": ["summary", "status", "priority"],
|
|
166
|
+
"limit": 50
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
and returns the same envelope the CLI prints under `--json`:
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
{ "issues": [...], "pages": 1, "complete": true }
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
A few things make the agent's job easier:
|
|
177
|
+
|
|
178
|
+
- **Name the fields you care about.** `fields` on the issue tools matters as much here as in the
|
|
179
|
+
CLI: raw issue payloads are large, and an agent pays for every token it reads. "Show me the
|
|
180
|
+
summary and status of..." lets it ask for only those.
|
|
181
|
+
- **Name boards and sprints; the agent resolves the numbers.** The sprint tools take numeric ids,
|
|
182
|
+
which the agent looks up with `jira_board_list` and `jira_sprint_list`.
|
|
183
|
+
- **Transitions go by name.** "Move it to Done" works; when unsure what the workflow allows, the
|
|
184
|
+
agent can call `jira_issue_transitions` first.
|
|
185
|
+
- **Mention people by name or email.** `mentions` resolves them to account ids; an ambiguous name
|
|
186
|
+
comes back as an error listing the candidates, so the agent can ask you which one.
|
|
187
|
+
- **Paste Confluence URLs.** Every page input accepts a page id or a page URL.
|
|
188
|
+
- **`open` tools return URLs.** A server cannot launch a browser, so `jira_open` and
|
|
189
|
+
`confluence_open` hand back the address for you to follow.
|
|
190
|
+
|
|
191
|
+
## Let the agent write
|
|
44
192
|
|
|
45
193
|
Started without options, the server registers only the read tools. Start it with `--allow-writes`
|
|
46
194
|
to also register the tools that create, update, transition, comment, link, and delete. Even then,
|
|
@@ -49,17 +197,50 @@ to also register the tools that create, update, transition, comment, link, and d
|
|
|
49
197
|
That mirrors the two-credential-file arrangement in
|
|
50
198
|
[Write safety](https://simplysf.github.io/simply-atlassian/guides/write-safety/): give the agent's
|
|
51
199
|
everyday server a read-scoped token, and configure a second server entry with `--allow-writes` and
|
|
52
|
-
a write-capable token only when a person means to let the agent write.
|
|
53
|
-
|
|
54
|
-
|
|
200
|
+
a write-capable token that is enabled only when a person means to let the agent write. In a
|
|
201
|
+
`mcpServers` configuration the pair looks like this:
|
|
202
|
+
|
|
203
|
+
```json
|
|
204
|
+
{
|
|
205
|
+
"mcpServers": {
|
|
206
|
+
"simply-atlassian": {
|
|
207
|
+
"command": "simply-atlassian-mcp",
|
|
208
|
+
"args": ["--env-file", "/home/me/atlassian.env"]
|
|
209
|
+
},
|
|
210
|
+
"simply-atlassian-write": {
|
|
211
|
+
"command": "simply-atlassian-mcp",
|
|
212
|
+
"args": ["--allow-writes", "--env-file", "/home/me/atlassian-write.env"]
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
A read-scoped token is still the only layer that binds; the server-side default just keeps write
|
|
219
|
+
tools out of the agent's normal loop entirely. Most clients also ask you to approve each tool call,
|
|
220
|
+
and the tools carry MCP annotations (`readOnlyHint`, `destructiveHint`) so a host can tell a read
|
|
221
|
+
from a delete when it asks.
|
|
55
222
|
|
|
56
223
|
With writes allowed:
|
|
57
224
|
|
|
58
|
-
-
|
|
59
|
-
sending it
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
225
|
+
- **Ask for a preview first.** Every write tool accepts `dryRun: true`, which returns the request
|
|
226
|
+
that would be sent without sending it. "Show me what you'd send to move PROJ-42 to Done with a
|
|
227
|
+
comment, then do it" produces a call like the one below, which you can check before the agent
|
|
228
|
+
repeats it without `dryRun`.
|
|
229
|
+
|
|
230
|
+
```json
|
|
231
|
+
{ "issue": "PROJ-42", "transition": "Done", "comment": "Verified in staging.", "dryRun": true }
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
- **Irreversible deletes need consent.** `jira_issue_delete` and `jira_issue_comment_delete`
|
|
235
|
+
require `confirm: true`, and so does `confluence_page_delete` with `purge: true`. A call without
|
|
236
|
+
it is answered with a `confirm-required` error before anything is looked up, and the message
|
|
237
|
+
names the input to add, so the agent will come back and ask you. Trashing a page needs no
|
|
238
|
+
`confirm`, because it is reversible.
|
|
239
|
+
- **Confluence bodies can be Markdown.** The page and comment tools take a body as `text` (plain
|
|
240
|
+
prose), raw storage-format `body`, or `markdown` (converted to storage format), and
|
|
241
|
+
`confluence_page_update` takes `append` to add to a page instead of replacing it. "Add a
|
|
242
|
+
Decisions section to this page with these three bullets" becomes `confluence_page_update` with
|
|
243
|
+
`markdown` and `append: true`.
|
|
63
244
|
|
|
64
245
|
## Tools
|
|
65
246
|
|
|
@@ -85,14 +266,6 @@ With writes allowed:
|
|
|
85
266
|
| `confluence_page_children` | |
|
|
86
267
|
| `confluence_page_comment_list` | |
|
|
87
268
|
|
|
88
|
-
Each tool's inputs are the command's arguments and flags in camel case; see the CLI's
|
|
89
|
-
[command reference](https://simplysf.github.io/simply-atlassian/reference/) for what each does.
|
|
90
|
-
`fields` on the issue tools matters as much here as in the CLI: raw issue payloads are large, and
|
|
91
|
-
an agent pays for every token it reads. The two `open` tools return the URL rather than launching
|
|
92
|
-
a browser. The Confluence write tools take a page or comment body as `text`, raw storage-format
|
|
93
|
-
`body`, or `markdown` (converted to storage format), and `confluence_page_update` takes `append`
|
|
94
|
-
to add to a page instead of replacing it.
|
|
95
|
-
|
|
96
269
|
## Results and errors
|
|
97
270
|
|
|
98
271
|
A successful call returns what the CLI prints with `--json`, verbatim. A failure returns an error
|
|
@@ -107,7 +280,46 @@ result whose text is a JSON object with a stable `code`:
|
|
|
107
280
|
|
|
108
281
|
The first three carry the same `name`, `message`, and `exitCode` the CLI writes to stderr,
|
|
109
282
|
scrubbed the same way, as described in
|
|
110
|
-
[Scripts and agents](https://simplysf.github.io/simply-atlassian/guides/scripting/).
|
|
283
|
+
[Scripts and agents](https://simplysf.github.io/simply-atlassian/guides/scripting/). The agent
|
|
284
|
+
sees these errors and can act on them, so a wrong key or a missing setting usually ends in the
|
|
285
|
+
agent telling you what went wrong rather than in silence.
|
|
286
|
+
|
|
287
|
+
## Troubleshooting
|
|
288
|
+
|
|
289
|
+
Run `simply-atlassian-mcp --help` at a terminal first. If it prints the tool list, the package is
|
|
290
|
+
installed and working, and the problem is in how the client launches it or what it passes.
|
|
291
|
+
|
|
292
|
+
| Symptom | Cause and fix |
|
|
293
|
+
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
294
|
+
| 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. |
|
|
295
|
+
| 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. |
|
|
296
|
+
| 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. |
|
|
297
|
+
| 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. |
|
|
298
|
+
| `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. |
|
|
299
|
+
| `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. |
|
|
300
|
+
| 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). |
|
|
301
|
+
| 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. |
|
|
302
|
+
|
|
303
|
+
## Embed in your own process
|
|
304
|
+
|
|
305
|
+
The stdio binary is the usual way to run the server, but the package also exports what it is
|
|
306
|
+
built from, so a host process can serve the same tools over a transport of its choosing:
|
|
307
|
+
|
|
308
|
+
```js
|
|
309
|
+
import { createServer, startServer } from '@simplysf/simply-atlassian-mcp';
|
|
310
|
+
|
|
311
|
+
// Serve over stdio, exactly as the binary does.
|
|
312
|
+
await startServer({ allowWrites: false, envFile: '/home/me/atlassian.env' });
|
|
313
|
+
|
|
314
|
+
// Or build the server and attach a transport yourself.
|
|
315
|
+
const server = createServer({ allowWrites: true, env: process.env });
|
|
316
|
+
await server.connect(transport);
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
`createServer` returns the MCP SDK's `McpServer` with the tools registered and nothing connected.
|
|
320
|
+
`TOOLS` is the full catalogue, `selectTools(allowWrites)` is the subset a given configuration
|
|
321
|
+
registers, and `invokeTool` and `mapError` run one tool and map a failure onto the error object
|
|
322
|
+
above, for tests and hosts that need to drive the server without a transport.
|
|
111
323
|
|
|
112
324
|
## Options
|
|
113
325
|
|
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.
|
|
4
|
+
"version": "0.4.1",
|
|
5
5
|
"author": "@ClayChipps",
|
|
6
6
|
"homepage": "https://github.com/SimplySF/simply-atlassian",
|
|
7
7
|
"bugs": "https://github.com/SimplySF/simply-atlassian/issues",
|
|
@@ -167,5 +167,5 @@
|
|
|
167
167
|
"service": true
|
|
168
168
|
}
|
|
169
169
|
},
|
|
170
|
-
"gitHead": "
|
|
170
|
+
"gitHead": "b0d86a9014b4e6483898577781f4090a20685b70"
|
|
171
171
|
}
|