@de-otio/epimethian-mcp 5.2.0 → 5.3.0

package/README.md

@@ -14,7 +14,7 @@ The official [Atlassian MCP server](https://github.com/atlassian/atlassian-mcp-s
 - **Multi-tenant profile isolation** — Each Atlassian tenant gets its own named profile with fully separate credentials and keychain entries. No risk of cross-tenant writes when switching between clients.
 - **Tenant-aware write safety** — Write operations echo the target tenant so the AI agent (and you) always see where changes are going before they land.
 - **draw.io diagram support** — Create and embed draw.io diagrams directly in Confluence pages, something the official server doesn't expose.
-- **Attribution tracking** — Managed pages carry metadata so you can trace which AI-assisted edits touched which content.
+- **Attribution tracking** — Edited pages are labelled `epimethian-edited` for easy discovery. Confluence version messages include the MCP client name (e.g. "Updated by Claude Code (via Epimethian v5.2.0)") so you can trace which AI-assisted edits touched which content.
 
 If you don't need any of the above, the official Atlassian server is a fine choice.
 
@@ -113,7 +113,7 @@ Confluence pages are verbose — storage format HTML with macro markup can easil
 | `create_page`        | Create a new page          |
 | `get_page`           | Read a page by ID (`headings_only`, `section`, `max_length`, `format`) |
 | `get_page_by_title`  | Look up a page by title (same options as `get_page`) |
-| `update_page`        | Update an existing page (rejects markdown input) |
+| `update_page`        | Update an existing page    |
 | `update_page_section`| Update a single section by heading name |
 | `delete_page`        | Delete a page              |
 | `list_pages`         | List pages in a space      |

package/dist/cli/index.js

@@ -24073,14 +24073,14 @@ var require_turndown_cjs = __commonJS({
         } else if (node.nodeType === 1) {
           replacement = replacementForNode.call(self, node);
         }
-        return join4(output, replacement);
+        return join5(output, replacement);
       }, "");
     }
     function postProcess3(output) {
       var self = this;
       this.rules.forEach(function(rule) {
         if (typeof rule.append === "function") {
-          output = join4(output, rule.append(self.options));
+          output = join5(output, rule.append(self.options));
         }
       });
       return output.replace(/^[\t\r\n]+/, "").replace(/[\t\r\n\s]+$/, "");
@@ -24092,7 +24092,7 @@ var require_turndown_cjs = __commonJS({
       if (whitespace.leading || whitespace.trailing) content = content.trim();
       return whitespace.leading + rule.replacement(content, node, this.options) + whitespace.trailing;
     }
-    function join4(output, replacement) {
+    function join5(output, replacement) {
       var s1 = trimTrailingNewlines(output);
       var s2 = trimLeadingNewlines(replacement);
       var nls = Math.max(output.length - s1.length, replacement.length - s2.length);
@@ -34605,7 +34605,7 @@ var init_status = __esm({
 var install_agent_default;
 var init_install_agent = __esm({
   "install-agent.md"() {
-    install_agent_default = '# Epimethian MCP - Agent Installation Guide\n\n> This document is for AI agents installing and configuring the Epimethian MCP server on behalf of a user.\n\n## Verification\n\nThe official package is **`@de-otio/epimethian-mcp`** (scoped under `@de-otio`).\n\nDo NOT install unscoped alternatives like `epimethian-mcp` \u2014 these are unofficial and potentially unsafe.\n\n## Prerequisites\n\n- Node.js 18 or later\n- npm on PATH\n\n## Step 1: Install\n\n```bash\nnpm install -g @de-otio/epimethian-mcp\n```\n\nVerify the installation:\n\n```bash\nepimethian-mcp --version 2>/dev/null || which epimethian-mcp\n```\n\n## Step 2: Resolve the absolute path\n\nIDE-hosted agents may not resolve PATH correctly. Always use the absolute path in MCP configuration:\n\n```bash\nwhich epimethian-mcp\n```\n\nUse the output as the `command` value in the MCP config below.\n\n## Step 3: Collect configuration\n\nAsk the user for:\n1. **Profile name** \u2014 a short identifier for this Confluence instance (e.g., `globex`, `acme-corp`). Lowercase alphanumeric and hyphens only.\n2. **Confluence Cloud URL** \u2014 e.g., `https://yoursite.atlassian.net`\n3. **Email address** \u2014 the email associated with their Atlassian account\n\n## Step 4: Write MCP configuration\n\nAdd the server to `.mcp.json` (or the equivalent config file for the user\'s MCP client):\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path from Step 2>",\n      "env": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>"\n      }\n    }\n  }\n}\n```\n\n**IMPORTANT:** The only env var needed is `CONFLUENCE_PROFILE`. The URL, email, and API token are stored securely in the OS keychain \u2014 they should NOT appear in config files.\n\n## Step 5: Credential setup\n\nTell the user to run this command in their terminal:\n\n```\nepimethian-mcp setup --profile <profile name from Step 3>\n```\n\nThis interactive command will:\n1. Prompt for the Confluence URL, email, and API token (masked input)\n2. Test the connection\n3. Store all credentials securely in the OS keychain under the named profile\n\nThe API token is generated at: https://id.atlassian.com/manage-profile/security/api-tokens\n\n**Do NOT ask the user for the API token yourself.** The token must go directly from the user into the interactive setup command to avoid appearing in conversation logs.\n\n## Step 6: User must restart the MCP client\n\n**IMPORTANT:** The user must restart their MCP client (e.g., restart Claude Code, reload VS Code, restart Claude Desktop) for the new server configuration to take effect. The MCP client reads `.mcp.json` at startup and does not detect changes while running.\n\nTell the user:\n> Please restart your MCP client now to activate the Confluence tools.\n\n## Step 7: Validation\n\nAfter the user restarts, verify the server is working by listing available Confluence tools or running a simple operation like listing spaces.\n\n## Adding Additional Tenants\n\nTo add a second Confluence instance (e.g., for a different customer):\n\n1. Run `epimethian-mcp setup --profile <new-profile-name>` with the new credentials\n2. In the project that uses the new tenant, update `.mcp.json` to set `CONFLUENCE_PROFILE` to the new profile name\n3. Restart the MCP client\n\nEach VS Code window / Claude Code session uses the profile specified in its `.mcp.json`. Profiles are fully isolated \u2014 different OS keychain entries, different Confluence instances.\n\n## Managing Profiles\n\n- List all profiles: `epimethian-mcp profiles`\n- Show details: `epimethian-mcp profiles --verbose`\n- Check connection: `CONFLUENCE_PROFILE=<name> epimethian-mcp status`\n- Set read-only: `epimethian-mcp profiles --set-read-only <name>`\n- Set read-write: `epimethian-mcp profiles --set-read-write <name>`\n\n### Read-Only Mode\n\nNew profiles default to **read-only**. When read-only, all write tools are blocked and return an error. To enable writes for a profile:\n\n```bash\nepimethian-mcp profiles --set-read-write <name>\n```\n\nOr during setup: `epimethian-mcp setup --profile <name> --read-write`\n\n**Important:** Restart any running MCP servers after changing the read-only flag.\n\n### Removing a Profile\n\nTo delete a profile and its credentials, run:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\n**Agents must pass `--force`** because the command normally prompts for interactive confirmation (`Remove profile "<name>" and delete its credentials? [y/N]`), which will fail in non-TTY environments like agent shell sessions. The `--force` flag skips the confirmation prompt when stdin is not a TTY.\n\nThis command:\n1. Deletes the credential entry (URL, email, API token) from the OS keychain\n2. Removes the profile from the registry at `~/.config/epimethian-mcp/profiles.json`\n3. Writes an entry to the audit log at `~/.config/epimethian-mcp/audit.log`\n\nAfter removing a profile, also remove or update any `.mcp.json` files that reference it \u2014 otherwise the MCP server will fail to start with a missing-profile error.\n\n**Errors:**\n- If the profile name is invalid (not matching lowercase alphanumeric/hyphens, 1\u201363 chars), the command exits with code 1\n- If the profile does not exist in the keychain, the keychain deletion is silently skipped \u2014 the registry entry is still removed\n\n## Accessing This Guide Post-Install\n\nOnce installed, this guide is available locally via:\n\n```bash\nepimethian-mcp agent-guide\n```\n\nThis prints the full agent guide to stdout \u2014 no web fetch required.\n\n## Uninstallation\n\nWhen a user asks to uninstall Epimethian MCP, follow these steps:\n\n### Step 1: Check for existing profiles\n\n```bash\nepimethian-mcp profiles\n```\n\n### Step 2: Ask the user about credential cleanup\n\nIf profiles exist, ask the user:\n\n> You have Epimethian profiles configured: [list the profile names]. Would you like to delete all stored credentials before uninstalling? (This removes API tokens from your OS keychain.)\n\n### Step 3: Delete credentials (if the user agrees)\n\nFor each profile the user wants removed:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\nOr to remove all profiles:\n\n```bash\nfor name in $(epimethian-mcp profiles | grep \'^ \'); do epimethian-mcp profiles --remove "$name" --force; done\n```\n\n### Step 4: Remove MCP configuration\n\nDelete the `confluence` entry (or the tenant-specific entry like `confluence-globex`) from the project\'s `.mcp.json`.\n\n### Step 5: Uninstall the package\n\n```bash\nnpm uninstall -g @de-otio/epimethian-mcp\n```\n\n### Step 6: Restart the MCP client\n\nTell the user to restart their MCP client so it stops trying to launch the removed server.\n\n## CI/CD (No Keychain)\n\nFor environments where the OS keychain is unavailable (Docker, CI), set all three env vars directly:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path>",\n      "env": {\n        "CONFLUENCE_URL": "<url>",\n        "CONFLUENCE_EMAIL": "<email>",\n        "CONFLUENCE_API_TOKEN": "<token>"\n      }\n    }\n  }\n}\n```\n\n**Warning:** This exposes the API token in the process environment. Use profile-based auth whenever possible.\n\n## Troubleshooting\n\nIf **npm install fails**:\n- Verify Node.js 18+ is installed: `node --version`\n- Verify npm is on PATH: `npm --version`\n- If permission errors occur, the user may need to fix their npm prefix or use a Node version manager (nvm, fnm)\n\nIf **`epimethian-mcp setup` fails**:\n- "Connection failed": Verify the Confluence URL is correct and accessible\n- "Token is invalid or expired": The user needs to generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens\n- Keychain errors on Linux: The user may need to install `libsecret` / `gnome-keyring` (`apt install libsecret-tools` or equivalent)\n\nIf **the server doesn\'t appear after restart**:\n- Verify the `.mcp.json` path is correct for the user\'s MCP client\n- Verify the `command` value is an absolute path (run `which epimethian-mcp` to confirm)\n- Check that `.mcp.json` contains valid JSON (no trailing commas, correct quoting)\n\n## Available Tools (32)\n\n| Tool | Description |\n|------|-------------|\n| `create_page` | Create a new Confluence page |\n| `get_page` | Read a page by ID (use `headings_only` to preview structure first) |\n| `get_page_by_title` | Look up a page by title (use `headings_only` to preview structure first) |\n| `update_page` | Update an existing page |\n| `update_page_section` | Update a single section by heading name |\n| `prepend_to_page` | Insert content at the beginning of an existing page (additive, safe) |\n| `append_to_page` | Insert content at the end of an existing page (additive, safe) |\n| `delete_page` | Delete a page |\n| `revert_page` | Revert a page to a previous version |\n| `list_pages` | List pages in a space |\n| `get_page_children` | Get child pages of a page |\n| `search_pages` | Search pages using CQL (Confluence Query Language) |\n| `get_spaces` | List available Confluence spaces |\n| `add_attachment` | Upload a file attachment to a page |\n| `get_attachments` | List attachments on a page |\n| `add_drawio_diagram` | Add a draw.io diagram to a page |\n| `get_labels` | Get all labels on a Confluence page |\n| `add_label` | Add one or more labels to a Confluence page |\n| `remove_label` | Remove a label from a Confluence page |\n| `get_page_status` | Get the content status badge on a page |\n| `set_page_status` | Set the content status badge on a page |\n| `remove_page_status` | Remove the content status badge from a page |\n| `get_comments` | Get footer and/or inline comments on a page |\n| `create_comment` | Create a footer or inline comment on a page |\n| `resolve_comment` | Resolve or reopen an inline comment |\n| `delete_comment` | Permanently delete a comment |\n| `get_page_versions` | List version history for a page |\n| `get_page_version` | Get page content at a specific historical version |\n| `diff_page_versions` | Compare two versions of a page |\n| `lookup_user` | Search for Atlassian users by name or email to resolve accountId for inline mentions |\n| `resolve_page_link` | Resolve a page title + space key to a stable contentId and URL for page links |\n| `get_version` | Return the epimethian-mcp server version |\n';
+    install_agent_default = '# Epimethian MCP - Agent Installation Guide\n\n> This document is for AI agents installing and configuring the Epimethian MCP server on behalf of a user.\n\n## Verification\n\nThe official package is **`@de-otio/epimethian-mcp`** (scoped under `@de-otio`).\n\nDo NOT install unscoped alternatives like `epimethian-mcp` \u2014 these are unofficial and potentially unsafe.\n\n## Prerequisites\n\n- Node.js 18 or later\n- npm on PATH\n\n## Step 1: Install\n\n```bash\nnpm install -g @de-otio/epimethian-mcp\n```\n\nVerify the installation:\n\n```bash\nepimethian-mcp --version 2>/dev/null || which epimethian-mcp\n```\n\n## Step 2: Resolve the absolute path\n\nIDE-hosted agents may not resolve PATH correctly. Always use the absolute path in MCP configuration:\n\n```bash\nwhich epimethian-mcp\n```\n\nUse the output as the `command` value in the MCP config below.\n\n## Step 3: Collect configuration\n\nAsk the user for:\n1. **Profile name** \u2014 a short identifier for this Confluence instance (e.g., `globex`, `acme-corp`). Lowercase alphanumeric and hyphens only.\n2. **Confluence Cloud URL** \u2014 e.g., `https://yoursite.atlassian.net`\n3. **Email address** \u2014 the email associated with their Atlassian account\n\n## Step 4: Write MCP configuration\n\nAdd the server to `.mcp.json` (or the equivalent config file for the user\'s MCP client):\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path from Step 2>",\n      "env": {\n        "CONFLUENCE_PROFILE": "<profile name from Step 3>"\n      }\n    }\n  }\n}\n```\n\n**IMPORTANT:** The only env var needed is `CONFLUENCE_PROFILE`. The URL, email, and API token are stored securely in the OS keychain \u2014 they should NOT appear in config files.\n\n## Step 5: Credential setup\n\nTell the user to run this command in their terminal:\n\n```\nepimethian-mcp setup --profile <profile name from Step 3>\n```\n\nThis interactive command will:\n1. Prompt for the Confluence URL, email, and API token (masked input)\n2. Test the connection\n3. Store all credentials securely in the OS keychain under the named profile\n\nThe API token is generated at: https://id.atlassian.com/manage-profile/security/api-tokens\n\n**Do NOT ask the user for the API token yourself.** The token must go directly from the user into the interactive setup command to avoid appearing in conversation logs.\n\n## Step 6: User must restart the MCP client\n\n**IMPORTANT:** The user must restart their MCP client (e.g., restart Claude Code, reload VS Code, restart Claude Desktop) for the new server configuration to take effect. The MCP client reads `.mcp.json` at startup and does not detect changes while running.\n\nTell the user:\n> Please restart your MCP client now to activate the Confluence tools.\n\n## Step 7: Validation\n\nAfter the user restarts, verify the server is working by listing available Confluence tools or running a simple operation like listing spaces.\n\n## Adding Additional Tenants\n\nTo add a second Confluence instance (e.g., for a different customer):\n\n1. Run `epimethian-mcp setup --profile <new-profile-name>` with the new credentials\n2. In the project that uses the new tenant, update `.mcp.json` to set `CONFLUENCE_PROFILE` to the new profile name\n3. Restart the MCP client\n\nEach VS Code window / Claude Code session uses the profile specified in its `.mcp.json`. Profiles are fully isolated \u2014 different OS keychain entries, different Confluence instances.\n\n## Managing Profiles\n\n- List all profiles: `epimethian-mcp profiles`\n- Show details: `epimethian-mcp profiles --verbose`\n- Check connection: `CONFLUENCE_PROFILE=<name> epimethian-mcp status`\n- Set read-only: `epimethian-mcp profiles --set-read-only <name>`\n- Set read-write: `epimethian-mcp profiles --set-read-write <name>`\n\n### Read-Only Mode\n\nNew profiles default to **read-only**. When read-only, all write tools are blocked and return an error. To enable writes for a profile:\n\n```bash\nepimethian-mcp profiles --set-read-write <name>\n```\n\nOr during setup: `epimethian-mcp setup --profile <name> --read-write`\n\n**Important:** Restart any running MCP servers after changing the read-only flag.\n\n### Removing a Profile\n\nTo delete a profile and its credentials, run:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\n**Agents must pass `--force`** because the command normally prompts for interactive confirmation (`Remove profile "<name>" and delete its credentials? [y/N]`), which will fail in non-TTY environments like agent shell sessions. The `--force` flag skips the confirmation prompt when stdin is not a TTY.\n\nThis command:\n1. Deletes the credential entry (URL, email, API token) from the OS keychain\n2. Removes the profile from the registry at `~/.config/epimethian-mcp/profiles.json`\n3. Writes an entry to the audit log at `~/.config/epimethian-mcp/audit.log`\n\nAfter removing a profile, also remove or update any `.mcp.json` files that reference it \u2014 otherwise the MCP server will fail to start with a missing-profile error.\n\n**Errors:**\n- If the profile name is invalid (not matching lowercase alphanumeric/hyphens, 1\u201363 chars), the command exits with code 1\n- If the profile does not exist in the keychain, the keychain deletion is silently skipped \u2014 the registry entry is still removed\n\n## Accessing This Guide Post-Install\n\nOnce installed, this guide is available locally via:\n\n```bash\nepimethian-mcp agent-guide\n```\n\nThis prints the full agent guide to stdout \u2014 no web fetch required.\n\n## Uninstallation\n\nWhen a user asks to uninstall Epimethian MCP, follow these steps:\n\n### Step 1: Check for existing profiles\n\n```bash\nepimethian-mcp profiles\n```\n\n### Step 2: Ask the user about credential cleanup\n\nIf profiles exist, ask the user:\n\n> You have Epimethian profiles configured: [list the profile names]. Would you like to delete all stored credentials before uninstalling? (This removes API tokens from your OS keychain.)\n\n### Step 3: Delete credentials (if the user agrees)\n\nFor each profile the user wants removed:\n\n```bash\nepimethian-mcp profiles --remove <name> --force\n```\n\nOr to remove all profiles:\n\n```bash\nfor name in $(epimethian-mcp profiles | grep \'^ \'); do epimethian-mcp profiles --remove "$name" --force; done\n```\n\n### Step 4: Remove MCP configuration\n\nDelete the `confluence` entry (or the tenant-specific entry like `confluence-globex`) from the project\'s `.mcp.json`.\n\n### Step 5: Uninstall the package\n\n```bash\nnpm uninstall -g @de-otio/epimethian-mcp\n```\n\n### Step 6: Restart the MCP client\n\nTell the user to restart their MCP client so it stops trying to launch the removed server.\n\n## CI/CD (No Keychain)\n\nFor environments where the OS keychain is unavailable (Docker, CI), set all three env vars directly:\n\n```json\n{\n  "mcpServers": {\n    "confluence": {\n      "command": "<absolute path>",\n      "env": {\n        "CONFLUENCE_URL": "<url>",\n        "CONFLUENCE_EMAIL": "<email>",\n        "CONFLUENCE_API_TOKEN": "<token>"\n      }\n    }\n  }\n}\n```\n\n**Warning:** This exposes the API token in the process environment. Use profile-based auth whenever possible.\n\n## Troubleshooting\n\nIf **npm install fails**:\n- Verify Node.js 18+ is installed: `node --version`\n- Verify npm is on PATH: `npm --version`\n- If permission errors occur, the user may need to fix their npm prefix or use a Node version manager (nvm, fnm)\n\nIf **`epimethian-mcp setup` fails**:\n- "Connection failed": Verify the Confluence URL is correct and accessible\n- "Token is invalid or expired": The user needs to generate a new API token at https://id.atlassian.com/manage-profile/security/api-tokens\n- Keychain errors on Linux: The user may need to install `libsecret` / `gnome-keyring` (`apt install libsecret-tools` or equivalent)\n\nIf **the server doesn\'t appear after restart**:\n- Verify the `.mcp.json` path is correct for the user\'s MCP client\n- Verify the `command` value is an absolute path (run `which epimethian-mcp` to confirm)\n- Check that `.mcp.json` contains valid JSON (no trailing commas, correct quoting)\n\n## Available Tools (33)\n\n| Tool | Description |\n|------|-------------|\n| `create_page` | Create a new Confluence page |\n| `get_page` | Read a page by ID (use `headings_only` to preview structure first) |\n| `get_page_by_title` | Look up a page by title (use `headings_only` to preview structure first) |\n| `update_page` | Update an existing page |\n| `update_page_section` | Update a single section by heading name |\n| `prepend_to_page` | Insert content at the beginning of an existing page (additive, safe) |\n| `append_to_page` | Insert content at the end of an existing page (additive, safe) |\n| `delete_page` | Delete a page |\n| `revert_page` | Revert a page to a previous version |\n| `list_pages` | List pages in a space |\n| `get_page_children` | Get child pages of a page |\n| `search_pages` | Search pages using CQL (Confluence Query Language) |\n| `get_spaces` | List available Confluence spaces |\n| `add_attachment` | Upload a file attachment to a page |\n| `get_attachments` | List attachments on a page |\n| `add_drawio_diagram` | Add a draw.io diagram to a page |\n| `get_labels` | Get all labels on a Confluence page |\n| `add_label` | Add one or more labels to a Confluence page |\n| `remove_label` | Remove a label from a Confluence page |\n| `get_page_status` | Get the content status badge on a page |\n| `set_page_status` | Set the content status badge on a page |\n| `remove_page_status` | Remove the content status badge from a page |\n| `get_comments` | Get footer and/or inline comments on a page |\n| `create_comment` | Create a footer or inline comment on a page |\n| `resolve_comment` | Resolve or reopen an inline comment |\n| `delete_comment` | Permanently delete a comment |\n| `get_page_versions` | List version history for a page |\n| `get_page_version` | Get page content at a specific historical version |\n| `diff_page_versions` | Compare two versions of a page |\n| `lookup_user` | Search for Atlassian users by name or email to resolve accountId for inline mentions |\n| `resolve_page_link` | Resolve a page title + space key to a stable contentId and URL for page links |\n| `get_version` | Return the epimethian-mcp server version and report available updates |\n| `upgrade` | Upgrade epimethian-mcp to the latest available version (restart required after) |\n';
   }
 });
 
@@ -48840,9 +48840,9 @@ var StdioServerTransport = class {
 };
 
 // src/server/index.ts
-var import_promises2 = require("node:fs/promises");
-var import_node_os2 = require("node:os");
-var import_node_path3 = require("node:path");
+var import_promises3 = require("node:fs/promises");
+var import_node_os3 = require("node:os");
+var import_node_path4 = require("node:path");
 
 // src/server/confluence-client.ts
 var import_turndown = __toESM(require_turndown_cjs());
@@ -49324,7 +49324,7 @@ async function getPage(pageId, includeBody) {
 async function createPage(spaceId, title, body, parentId, clientLabel) {
   const cfg = await getConfig();
   const pageBody = stripAttributionFooter(toStorageFormat(body));
-  const epimethianTag = `Epimethian v${"5.2.0"}`;
+  const epimethianTag = `Epimethian v${"5.3.0"}`;
   const versionMsg = cfg.attribution && clientLabel ? `Created by ${clientLabel} (via ${epimethianTag})` : `Created by ${epimethianTag}`;
   const payload = {
     title,
@@ -49349,7 +49349,7 @@ async function createPage(spaceId, title, body, parentId, clientLabel) {
 async function updatePage(pageId, opts) {
   const cfg = await getConfig();
   const newVersion = opts.version + 1;
-  const epimethianTag = `Epimethian v${"5.2.0"}`;
+  const epimethianTag = `Epimethian v${"5.3.0"}`;
   const effectiveClient = cfg.attribution ? opts.clientLabel : void 0;
   let versionMessage;
   if (opts.versionMessage && effectiveClient)
@@ -56883,6 +56883,152 @@ function errorRecord(operation, pageId, err, extra) {
   };
 }
 
+// src/shared/update-check.ts
+var import_promises2 = require("node:fs/promises");
+var import_node_path3 = require("node:path");
+var import_node_os2 = require("node:os");
+var import_node_crypto2 = require("node:crypto");
+var import_node_child_process2 = require("node:child_process");
+var import_node_util = require("node:util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+var CONFIG_DIR2 = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".config", "epimethian-mcp");
+var UPDATE_CHECK_FILE = (0, import_node_path3.join)(CONFIG_DIR2, "update-check.json");
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@de-otio/epimethian-mcp/latest";
+var PACKAGE_NAME = "@de-otio/epimethian-mcp";
+function parseSemVer(version2) {
+  const match2 = version2.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!match2) return null;
+  return {
+    major: parseInt(match2[1], 10),
+    minor: parseInt(match2[2], 10),
+    patch: parseInt(match2[3], 10)
+  };
+}
+function classifyUpdate(current, latest) {
+  if (latest.major > current.major) return "major";
+  if (latest.major === current.major && latest.minor > current.minor)
+    return "minor";
+  if (latest.major === current.major && latest.minor === current.minor && latest.patch > current.patch)
+    return "patch";
+  return null;
+}
+async function readCheckState() {
+  try {
+    const raw = await (0, import_promises2.readFile)(UPDATE_CHECK_FILE, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && typeof parsed.lastCheck === "string") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function writeCheckState(state) {
+  await (0, import_promises2.mkdir)(CONFIG_DIR2, { recursive: true, mode: 448 });
+  const data = JSON.stringify(state, null, 2) + "\n";
+  const tmpFile = (0, import_node_path3.join)(
+    CONFIG_DIR2,
+    `.update-check.${(0, import_node_crypto2.randomBytes)(4).toString("hex")}.tmp`
+  );
+  await (0, import_promises2.writeFile)(tmpFile, data, { mode: 384 });
+  await (0, import_promises2.rename)(tmpFile, UPDATE_CHECK_FILE);
+}
+async function fetchLatestVersion() {
+  try {
+    const response = await fetch(NPM_REGISTRY_URL, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return typeof data.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  }
+}
+async function getPendingUpdate() {
+  const state = await readCheckState();
+  return state?.pendingUpdate ?? null;
+}
+async function clearPendingUpdate() {
+  const state = await readCheckState();
+  if (state) {
+    delete state.pendingUpdate;
+    await writeCheckState(state);
+  }
+}
+async function performUpgrade(version2) {
+  const { stdout: stdout3, stderr } = await execFileAsync(
+    "npm",
+    ["install", "-g", `${PACKAGE_NAME}@${version2}`],
+    { timeout: 12e4 }
+  );
+  return (stdout3 + stderr).trim();
+}
+async function checkForUpdates(currentVersion) {
+  if (process.env.EPIMETHIAN_NO_UPDATE_CHECK === "true") return null;
+  try {
+    const state = await readCheckState();
+    if (state?.lastCheck) {
+      const elapsed = Date.now() - new Date(state.lastCheck).getTime();
+      if (elapsed < ONE_DAY_MS) {
+        return state.pendingUpdate ?? null;
+      }
+    }
+    const latestStr = await fetchLatestVersion();
+    if (!latestStr) {
+      return state?.pendingUpdate ?? null;
+    }
+    const current = parseSemVer(currentVersion);
+    const latest = parseSemVer(latestStr);
+    if (!current || !latest) return null;
+    const type = classifyUpdate(current, latest);
+    const newState = {
+      lastCheck: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (!type) {
+      await writeCheckState(newState);
+      return null;
+    }
+    const info = {
+      current: currentVersion,
+      latest: latestStr,
+      type
+    };
+    if (type === "patch") {
+      try {
+        await performUpgrade(latestStr);
+        info.autoInstalled = true;
+        newState.pendingUpdate = info;
+        await writeCheckState(newState);
+        console.error(
+          `[epimethian-mcp] Bugfix v${latestStr} installed automatically. Restart the MCP server to apply.`
+        );
+      } catch (err) {
+        newState.pendingUpdate = info;
+        await writeCheckState(newState);
+        console.error(
+          `[epimethian-mcp] Auto-update to v${latestStr} failed: ${err instanceof Error ? err.message : err}`
+        );
+      }
+      return info;
+    }
+    newState.pendingUpdate = info;
+    await writeCheckState(newState);
+    console.error(
+      `[epimethian-mcp] ${type === "major" ? "Major" : "Minor"} update available: v${currentVersion} \u2192 v${latestStr}. Use the upgrade tool to install.`
+    );
+    return info;
+  } catch (err) {
+    console.error(
+      `[epimethian-mcp] Update check failed: ${err instanceof Error ? err.message : err}`
+    );
+    return null;
+  }
+}
+
 // src/server/index.ts
 function getClientLabel(server) {
   const client = server.server.getClientVersion();
@@ -56892,6 +57038,7 @@ function getClientLabel(server) {
 function escapeXml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
+var READ_ONLY_MARKDOWN_MARKER = "<!-- epimethian:read-only-markdown \u2014 do not pass this content to update_page -->";
 function formatMarkdownWithTokens(markdown, sidecar, header) {
   const tokenCount = Object.keys(sidecar).length;
   let body = markdown;
@@ -56904,13 +57051,19 @@ function formatMarkdownWithTokens(markdown, sidecar, header) {
       const name = m && m[2] ? ` ac:name="${m[2]}"` : "";
       return `- [[epi:${id}]]: <${tag}${name}>`;
     }).join("\n");
-    body = `<!-- ${tokenCount} Confluence macro${tokenCount === 1 ? "" : "s"} preserved as tokens; remove a token to delete that macro on the next update_page -->
+    body = `${READ_ONLY_MARKDOWN_MARKER}
+
+<!-- ${tokenCount} Confluence macro${tokenCount === 1 ? "" : "s"} preserved as tokens; remove a token to delete that macro on the next update_page -->
 
 ${markdown}
 
 ---
 Tokens:
 ${table2}`;
+  } else {
+    body = `${READ_ONLY_MARKDOWN_MARKER}
+
+${markdown}`;
   }
   return `${header}
 
@@ -56945,6 +57098,7 @@ var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
   "get_page_version",
   "diff_page_versions",
   "get_version",
+  "upgrade",
   "lookup_user",
   "resolve_page_link"
 ]);
@@ -57021,6 +57175,12 @@ function registerTools(server, config3) {
   );
   const pageIdSchema = external_exports.string().regex(/^\d+$/, "Page ID must be numeric");
   async function concatPageContent(page_id, version2, newContent, position, opts = {}) {
+    if (newContent.includes("epimethian:read-only-markdown")) {
+      throw new ConverterError(
+        "The content contains output produced by get_page with format: 'markdown', which is a read-only rendering not suitable for prepend/append operations. Compose new content from scratch instead.",
+        "READ_ONLY_MARKDOWN_ROUND_TRIP"
+      );
+    }
     const currentPage = await getPage(page_id, true);
     const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
     const isMarkdown = looksLikeMarkdown(newContent);
@@ -57076,6 +57236,12 @@ function registerTools(server, config3) {
       const blocked = writeGuard("create_page", config3);
       if (blocked) return blocked;
       try {
+        if (body.includes("epimethian:read-only-markdown")) {
+          throw new ConverterError(
+            "The body contains content produced by get_page with format: 'markdown', which is a read-only rendering not suitable for creating pages (tables, macros, and rich elements may be lost). Compose new markdown from scratch instead.",
+            "READ_ONLY_MARKDOWN_ROUND_TRIP"
+          );
+        }
         let finalBody = body;
         if (looksLikeMarkdown(body)) {
           const cfg = await getConfig();
@@ -57225,7 +57391,15 @@ ${truncated}`);
         const currentStorage = currentPage.body?.storage?.value ?? currentPage.body?.value ?? "";
         let finalStorage;
         let effectiveVersionMessage = version_message;
-        if (body && looksLikeMarkdown(body)) {
+        if (body && body.includes("epimethian:read-only-markdown")) {
+          throw new ConverterError(
+            "The body contains content produced by get_page with format: 'markdown', which is a read-only rendering not suitable for round-trip updates (tables, macros, and rich elements may be lost). To update this page, either: (1) read with format: 'storage' and edit the storage XML, (2) use update_page_section for targeted edits, or (3) compose new markdown from scratch (do not copy from format: 'markdown' output).",
+            "READ_ONLY_MARKDOWN_ROUND_TRIP"
+          );
+        }
+        if (body === void 0 || body === null) {
+          finalStorage = void 0;
+        } else if (looksLikeMarkdown(body)) {
           const plan = planUpdate({
             currentStorage,
             callerMarkdown: body,
@@ -57239,14 +57413,16 @@ ${truncated}`);
           finalStorage = plan.newStorage;
           effectiveVersionMessage = plan.versionMessage && version_message ? `${version_message}; ${plan.versionMessage}` : plan.versionMessage ?? version_message;
         } else {
-          finalStorage = body ?? "";
+          finalStorage = body;
+        }
+        if (finalStorage !== void 0) {
+          enforceContentSafetyGuards({
+            oldStorage: currentStorage,
+            newStorage: finalStorage,
+            confirmShrinkage: confirm_shrinkage,
+            confirmStructureLoss: confirm_structure_loss
+          });
         }
-        enforceContentSafetyGuards({
-          oldStorage: currentStorage,
-          newStorage: finalStorage,
-          confirmShrinkage: confirm_shrinkage,
-          confirmStructureLoss: confirm_structure_loss
-        });
         const { page, newVersion } = await updatePage(page_id, {
           title,
           body: finalStorage,
@@ -57262,11 +57438,12 @@ ${truncated}`);
           oldVersion: version2,
           newVersion,
           oldBodyLen: currentStorage.length,
-          newBodyLen: finalStorage.length,
+          newBodyLen: finalStorage?.length ?? currentStorage.length,
           replaceBody: replace_body || void 0
         });
+        const bodyReport = finalStorage !== void 0 ? `body: ${currentStorage.length}\u2192${finalStorage.length} chars` : `title only, body unchanged`;
         return toolResult(
-          `Updated: ${page.title} (ID: ${page.id}, version: ${newVersion}, body: ${currentStorage.length}\u2192${finalStorage.length} chars)` + echo
+          `Updated: ${page.title} (ID: ${page.id}, version: ${newVersion}, ${bodyReport})` + echo
         );
       } catch (err) {
         logMutation(errorRecord("update_page", page_id, err, {
@@ -57323,6 +57500,12 @@ ${truncated}`);
       const blocked = writeGuard("update_page_section", config3);
       if (blocked) return blocked;
       try {
+        if (body.includes("epimethian:read-only-markdown")) {
+          throw new ConverterError(
+            "The body contains content produced by get_page with format: 'markdown', which is a read-only rendering not suitable for section updates. Use format: 'storage' to read the section, then edit the storage XML.",
+            "READ_ONLY_MARKDOWN_ROUND_TRIP"
+          );
+        }
         const page = await getPage(page_id, true);
         const fullBody = page.body?.storage?.value ?? page.body?.value ?? "";
         const newFullBody = replaceSection(fullBody, section, body);
@@ -57659,8 +57842,8 @@ ${truncated}`);
       const blocked = writeGuard("add_attachment", config3);
       if (blocked) return blocked;
       try {
-        const resolved = await (0, import_promises2.realpath)((0, import_node_path3.resolve)(file_path));
-        const cwd = await (0, import_promises2.realpath)(process.cwd());
+        const resolved = await (0, import_promises3.realpath)((0, import_node_path4.resolve)(file_path));
+        const cwd = await (0, import_promises3.realpath)(process.cwd());
         if (!resolved.startsWith(cwd + "/") && resolved !== cwd) {
           return toolError(
             new Error(
@@ -57668,7 +57851,7 @@ ${truncated}`);
             )
           );
         }
-        const fileData = await (0, import_promises2.readFile)(resolved);
+        const fileData = await (0, import_promises3.readFile)(resolved);
         const name = filename ?? resolved.split("/").pop() ?? "attachment";
         const att = await uploadAttachment(page_id, fileData, name, comment2);
         return toolResult(
@@ -57708,14 +57891,14 @@ ${truncated}`);
       if (blocked) return blocked;
       try {
         const filename = diagram_name.endsWith(".drawio") ? diagram_name : `${diagram_name}.drawio`;
-        const tmpDir = await (0, import_promises2.mkdtemp)((0, import_node_path3.join)((0, import_node_os2.tmpdir)(), "drawio-"));
+        const tmpDir = await (0, import_promises3.mkdtemp)((0, import_node_path4.join)((0, import_node_os3.tmpdir)(), "drawio-"));
         try {
-          const tmpPath = (0, import_node_path3.join)(tmpDir, filename);
-          await (0, import_promises2.writeFile)(tmpPath, diagram_xml, "utf-8");
-          const fileData = await (0, import_promises2.readFile)(tmpPath);
+          const tmpPath = (0, import_node_path4.join)(tmpDir, filename);
+          await (0, import_promises3.writeFile)(tmpPath, diagram_xml, "utf-8");
+          const fileData = await (0, import_promises3.readFile)(tmpPath);
           await uploadAttachment(page_id, fileData, filename);
         } finally {
-          await (0, import_promises2.rm)(tmpDir, { recursive: true, force: true });
+          await (0, import_promises3.rm)(tmpDir, { recursive: true, force: true });
         }
         const macroId = crypto.randomUUID();
         const localId = crypto.randomUUID();
@@ -58350,27 +58533,75 @@ ${lines.join("\n")}${echo2}`
   server.registerTool(
     "get_version",
     {
-      description: "Return the epimethian-mcp server version.",
+      description: "Return the epimethian-mcp server version. Also reports available updates, if any.",
       inputSchema: {}
     },
-    async () => toolResult(`epimethian-mcp v${"5.2.0"}`)
+    async () => {
+      let text2 = `epimethian-mcp v${"5.3.0"}`;
+      try {
+        const pending = await getPendingUpdate();
+        if (pending) {
+          if (pending.autoInstalled) {
+            text2 += `
+
+Bugfix v${pending.latest} has been installed automatically. Restart the MCP server to apply.`;
+          } else {
+            text2 += `
+
+${pending.type === "major" ? "Major" : "Minor"} update available: v${pending.current} \u2192 v${pending.latest}. Call the upgrade tool to install.`;
+          }
+        }
+      } catch {
+      }
+      return toolResult(text2);
+    }
+  );
+  server.registerTool(
+    "upgrade",
+    {
+      description: "Upgrade epimethian-mcp to the latest available version. After a successful upgrade the user must restart the MCP server (reload the VS Code window or restart Claude).",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        const pending = await getPendingUpdate();
+        if (!pending) {
+          return toolResult(
+            `epimethian-mcp v${"5.3.0"} is already up to date.`
+          );
+        }
+        const output = await performUpgrade(pending.latest);
+        await clearPendingUpdate();
+        return toolResult(
+          `Upgraded epimethian-mcp from v${pending.current} to v${pending.latest}.
+
+\u26A0 Restart required: reload the VS Code window (or restart Claude) so the new version takes effect.
+
+` + output
+        );
+      } catch (err) {
+        return toolError(err);
+      }
+    }
   );
 }
 async function main() {
   const config3 = await getConfig();
   await validateStartup(config3);
   if (process.env.EPIMETHIAN_MUTATION_LOG === "true") {
-    const logDir = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".epimethian", "logs");
+    const logDir = (0, import_node_path4.join)((0, import_node_os3.homedir)(), ".epimethian", "logs");
     initMutationLog(logDir);
   }
   const serverName = config3.profile ? `confluence-${config3.profile}` : "confluence";
   const server = new McpServer({
     name: serverName,
-    version: "5.2.0"
+    version: "5.3.0"
   });
   registerTools(server, config3);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  checkForUpdates("5.3.0").catch(() => {
+  });
 }
 
 // src/cli/index.ts