# Jira Assets MCP Server

A minimal Model Context Protocol server that gives an AI client read **and write** access to Atlassian Jira Assets (formerly Insight), plus a review dashboard for bulk editing.

The official Atlassian MCP connector covers Jira issues and Confluence pages. It does not cover Assets. If your CMDB, license register, hardware inventory, or vendor catalogue lives in Assets, this closes the gap.

Companion article on MEDIUM: *Your CMDB Is Invisible to Your AI Assistant. Here Is How I Fixed That in One Evening.*  https://medium.com/@Road2DevNull/your-cmdb-is-invisible-to-your-ai-assistant-here-is-how-i-fixed-that-in-one-evening-5630ca6dbebc

---

## What you get

| File | Purpose |
|---|---|
| `assets_mcp_server.mjs` | The MCP server. Five tools, two dependencies. |
| `dashboard.html` | Self-contained review dashboard. Bulk edit, one-click push. |
| `store-credential.ps1` | One-time setup: stores the API token in Windows Credential Manager. |
| `read-credential.ps1` | Runtime helper: the server calls this to read the token back. |
| `claude_desktop_config.example.json` | Config template. No token in it, only a credential target name. |
| `package.json` | Dependency manifest. |

### Tools exposed

| Tool | Direction | Description |
|---|---|---|
| `get_assets` | read | Fetch all objects with flattened field values |
| `discover_schema` | read | List attribute names and numeric IDs. Run this first. |
| `update_auto_renewal` | write | Set the auto renewal flag on one object |
| `update_payment_method` | write | Set the payment method on one object |
| `apply_bulk_changes` | write | Apply changes to many objects in one call |

---

## Quick start

### 1. Install

```bash
git clone <this-repo>
cd assets-mcp
npm install
```

### 2. Find your workspace ID

The Assets API does **not** live on your Jira hostname. It sits behind a workspace-scoped gateway.

```bash
curl -u you@example.com:YOUR_API_TOKEN \
  https://your-site.atlassian.net/rest/servicedeskapi/assets/workspace
```

Copy the `workspaceId` UUID from the response.

### 3. Find your schema and object type IDs

Open the object type in the Assets UI and read them straight from the URL:

```
/jira/assets/object-schema/{schemaId}?typeId={objectTypeId}
```

### 4. Create an API token

Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens), create a token, and copy it immediately. It is shown once. Prefer a scoped token, restricted to the narrowest scopes the integration needs, over a classic full-account one.

### 5. Store the token in your OS credential store, not in a config file

Do this before touching any config file. On Windows:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File store-credential.ps1 -Target "AssetsMCP"
```

This prompts for the token with a masked input, so it is never typed as a command-line argument and never lands in shell history, and stores it via the native Windows `CredWrite` API, encrypted and tied to your Windows profile.

Verify it landed correctly before configuring the server:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File read-credential.ps1 -Target "AssetsMCP"
```

It should print the token back. If you're on macOS or Linux, swap this pair of scripts for your platform's equivalent (Keychain via the `security` CLI, or the Secret Service API via `secret-tool`); same pattern, different retrieval call.

### 6. Configure your MCP host

Copy `claude_desktop_config.example.json` into your host's config and fill in the values. Notice there is no token field to fill in, only email, workspace details, and the credential target name you used in step 5.

**Config file locations:**

| OS | Path |
|---|---|
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

Use forward slashes in the `args` path, even on Windows.

### 7. Restart your MCP host

Quit fully, including any system tray icon, then relaunch. The server is spawned on startup, reads the credential target from its environment, and pulls the token from the credential store at that point.

### 8. Discover your attribute IDs

Ask your client to run `discover_schema`. Output looks like:

```
    ID  NAME
  1001  Name
  1004  Status
  1009  Auto renewal
  1010  Payment method
```

Paste those IDs into the `ATTR` map at the top of `assets_mcp_server.mjs`. Copy the names **exactly**, casing included. They are case sensitive and frequently inconsistent.

### 9. Verify

Ask your client:

> Call get_assets and tell me how many objects came back, and how many unique keys are in the result.

If total and unique differ, pagination is duplicating records. See Pitfall 3 below.

### 10. Open the dashboard (optional)

Update the two tool name constants at the top of the `<script>` block in `dashboard.html`:

```javascript
const MCP_READ  = 'mcp__assets__get_assets';
const MCP_WRITE = 'mcp__assets__apply_bulk_changes';
```

The `assets` segment must match the server key you used in your host config.

---

## Known API pitfalls

These four cost me hours. They are documented here so they do not cost you the same.

### 1. Wrong base URL

Assets is not at `your-site.atlassian.net`. It is at:

```
https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1
```

The `workspaceId` is a UUID and is **not** your cloud ID.

### 2. AQL returns attribute IDs, not names

An AQL response gives you `objectTypeAttributeId` (a bare number). A single-object GET gives you `objectTypeAttribute.id` plus a name. Handle both shapes or half your reads silently return empty strings.

```javascript
const id = String(a.objectTypeAttributeId ?? a.objectTypeAttribute?.id ?? "");
```

### 3. `startAt` in the POST body is ignored

`POST /object/aql` honours `maxResults` in the body but **silently ignores `startAt`**. You get HTTP 200 and page one, forever.

```javascript
// Wrong
body: JSON.stringify({ qlQuery, maxResults, startAt })

// Right
const url = `${BASE_URL}/object/aql?startAt=${startAt}`;
```

Also: adding `includeAttributesDeep` to the body breaks pagination entirely, even with the query parameter fix. Do not use it.

Always include `ORDER BY` in your AQL so page boundaries stay stable across requests.

### 4. Attribute names are case sensitive

Real schemas are inconsistently cased. `Auto renewal` and `Payment method` both use a lowercase second word. Copy names from `discover_schema` output. Never type them from memory.

---

## Security

Read this before deploying.

| Property | Reality |
|---|---|
| Authentication | Basic Auth, personal API token |
| Token storage | OS credential store (Windows Credential Manager / DPAPI). No plaintext copy on disk. |
| Transport | stdio, local process, no listening port |
| Identity | Individual user, not a service account |
| Scope | Read and write on one Assets object type |
| Network exposure | None |
| Third parties | None. Atlassian only. |
| Audit trail | Native. All writes appear in Jira object history. |

### Why Basic Auth and not OAuth

The Assets workspace gateway rejects OAuth bearer tokens even when the token carries valid Assets scopes. Basic Auth with an API token is the only reliable path today. This is a real tradeoff, not a preference.

### Why the credential store, and not a config file

A plaintext secret in an application config file is one of the most common findings in any review of internal tooling, common enough to have its own classification, [CWE-798](https://cwe.mitre.org/data/definitions/798.html), Use of Hard-Coded Credentials. It is also cheap to avoid entirely. This server reads its token from the OS credential store at startup and never writes it to disk in plaintext, so a copied config file, a synced backup, or a support-ticket paste of the wrong file hands over nothing usable.

### What this does not solve, read this part too

The credential store protects data **at rest**. It does not change what happens if code is already running under your own logged-in session: an attacker with an active foothold can call the same `CredRead` API this server calls and get the plaintext back just as easily. The blast radius of an active compromise is unchanged; what shrinks is the blast radius of a passive one (theft of a file, an accidental copy, a backup sync).

Other limits worth knowing:

- It is still a **personal credential**, not a service account. Storage hardening doesn't answer who owns it after an offboarding, that still needs a rotation and revocation process.
- It is **platform-specific**. Windows Credential Manager has no meaning on macOS or Linux; porting means swapping the retrieval call for Keychain or Secret Service.
- It adds **one more moving part at startup**: a helper process that can fail (execution policy, a missing script, a locked profile).
- It is **not a substitute for an enterprise secrets manager**. No centralized rotation policy, no expiry enforcement, no access-controlled audit log of who read the secret and when. Good step up from a config file; not equivalent to Vault or a cloud KMS-backed secret if this ever needs to run for more than one person.

**Recommended mitigations on top of this, in order of impact:**

1. Rotate the token on a schedule; add it to your offboarding checklist
2. Prefer a scoped token over a classic full-account one, restricted to minimum viable permissions
3. Provision a dedicated account rather than a personal identity, once this scales beyond one user
4. If this needs to run on a shared or server host rather than a personal workstation, move to a proper secrets manager instead of an OS credential store

### What is genuinely better than the alternative

Every write goes through the Assets REST API, so every change lands in the object's native change history, attributed and timestamped. The CSV export and re-import workflow this replaces has no comparable audit trail.

---

## Adapting to a different object type

The server is not license specific. To point it at hardware, contracts, vendors, or anything else:

1. Change `ASSETS_OBJECT_TYPE_ID` in your config
2. Run `discover_schema` and replace the `ATTR` map
3. Rename the fields in `summariseObject()` to match your domain
4. Adjust `WRITABLE_ATTRS` and the write tool schemas for the fields you want editable

The pagination, auth, and attribute extraction logic is generic and needs no changes.

---

## Requirements

- Node.js 18 or later (native `fetch`)
- `@modelcontextprotocol/sdk`
- `zod`

---

## License

MIT. All identifiers in this repository are placeholders.