@de-otio/epimethian-mcp 3.0.1 → 4.0.1

package/README.md

@@ -2,7 +2,21 @@
 
 Confluence Cloud tools for AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/) (MCP). (not associated with or endorsed by Atlassian)
 
-> **Note:** For most Confluence use cases, the official [Atlassian Rovo MCP server](https://github.com/atlassian/mcp-server-atlassian) may be sufficient. Use Epimethian if you need draw.io diagram support, OS keychain credential storage, multi-tenant profile isolation, or attribution tracking on managed pages.
+## Why use this?
+
+The official [Atlassian MCP server](https://github.com/atlassian/atlassian-mcp-server) covers basic Confluence and Jira access. Epimethian targets gaps that matter for consultants, power users, and teams with strict security requirements:
+
+- **OS keychain credential storage** — API tokens are stored in macOS Keychain or Linux libsecret, never in plaintext config files. Setup uses masked input so tokens don't leak into terminal scrollback.
+- **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.
+
+If you don't need any of the above, the official Atlassian server is a fine choice.
+
+## How it works
+
+Epimethian runs as a local MCP server that your AI agent (Claude Code, Cursor, etc.) talks to over stdio. On startup it reads a profile name from the environment, pulls the matching credentials from your OS keychain, validates the connection against Confluence Cloud, and then exposes a set of tools the agent can call. All Confluence API calls go directly from your machine to Atlassian — there is no intermediate service.
 
 ## Quick Start
 
@@ -10,6 +24,8 @@ Tell your AI agent:
 
 > Install and configure the Epimethian MCP server. See https://github.com/de-otio/epimethian-mcp
 
+For a detailed agent-facing guide (installation, configuration, profile management, uninstallation), see [install-agent.md](install-agent.md) or run `epimethian-mcp agent-guide` after installation.
+
 Or install manually:
 
 ```bash
@@ -57,8 +73,11 @@ Manage profiles:
 epimethian-mcp profiles              # list all
 epimethian-mcp profiles --verbose    # show URLs and emails
 CONFLUENCE_PROFILE=jambit epimethian-mcp status   # test connection
+epimethian-mcp profiles --remove <name>           # delete profile and credentials
 ```
 
+The `--remove` command deletes the profile's keychain entry and registry record after interactive confirmation. For non-interactive environments (CI, agent shell sessions), pass `--force` to skip the prompt.
+
 ## Tools
 
 | Tool                 | Description                |

package/dist/cli/index.js

@@ -7403,6 +7403,29 @@ var init_status = __esm({
   }
 });
 
+// install-agent.md
+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., `jambit`, `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\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-jambit`) 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 (12)\n\n| Tool | Description |\n|------|-------------|\n| `create_page` | Create a new Confluence page |\n| `get_page` | Read a page by ID |\n| `get_page_by_title` | Look up a page by title in a space |\n| `update_page` | Update an existing page |\n| `delete_page` | Delete a page |\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';
+  }
+});
+
+// src/cli/agent-guide.ts
+var agent_guide_exports = {};
+__export(agent_guide_exports, {
+  runAgentGuide: () => runAgentGuide
+});
+function runAgentGuide() {
+  process.stdout.write(install_agent_default);
+}
+var init_agent_guide = __esm({
+  "src/cli/agent-guide.ts"() {
+    "use strict";
+    init_install_agent();
+  }
+});
+
 // node_modules/zod/v3/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -21780,15 +21803,29 @@ function sanitizeError(message) {
   safe = safe.replace(/Bearer [A-Za-z0-9._-]{20,}/g, "Bearer [REDACTED]");
   return safe;
 }
+var ConfluenceApiError = class extends Error {
+  status;
+  constructor(status, body) {
+    super(`Confluence API error (${status}): ${sanitizeError(body)}`);
+    this.name = "ConfluenceApiError";
+    this.status = status;
+  }
+};
+var ConfluenceConflictError = class extends Error {
+  constructor(pageId) {
+    super(
+      `Version conflict: page ${pageId} has been modified since you last read it. Call get_page to fetch the latest version, then retry your update with the new version number.`
+    );
+    this.name = "ConfluenceConflictError";
+  }
+};
 async function confluenceRequest(url, options = {}) {
   const cfg = await getConfig();
   const res = await fetch(url, { headers: cfg.jsonHeaders, ...options });
   if (!res.ok) {
     const body = await res.text();
-    console.error(`Confluence API error (${res.status}): ${body}`);
-    throw new Error(
-      `Confluence API error (${res.status}): ${sanitizeError(body)}`
-    );
+    console.error(`Confluence API error (${res.status}): ${sanitizeError(body)}`);
+    throw new ConfluenceApiError(res.status, body);
   }
   return res;
 }
@@ -21858,14 +21895,12 @@ async function createPage(spaceId, title, body, parentId) {
   return page;
 }
 async function updatePage(pageId, opts) {
-  const current = await getPage(pageId, true);
-  const newVersion = (current.version?.number ?? 0) + 1;
-  const newTitle = opts.title ?? current.title;
+  const newVersion = opts.version + 1;
   const versionMessage = opts.versionMessage ? `${opts.versionMessage} (via Epimethian)` : "Updated by Epimethian";
   const payload = {
     id: pageId,
     status: "current",
-    title: newTitle,
+    title: opts.title,
     version: { number: newVersion, message: versionMessage }
   };
   if (opts.body) {
@@ -21875,7 +21910,15 @@ async function updatePage(pageId, opts) {
       value: cleanBody + "\n" + buildAttributionFooter("updated")
     };
   }
-  const raw = await v2Put(`/pages/${pageId}`, payload);
+  let raw;
+  try {
+    raw = await v2Put(`/pages/${pageId}`, payload);
+  } catch (err) {
+    if (err instanceof ConfluenceApiError && err.status === 409) {
+      throw new ConfluenceConflictError(pageId);
+    }
+    throw err;
+  }
   const page = PageSchema.parse(raw);
   try {
     await addLabel(page.id, ATTRIBUTION_LABEL);
@@ -21947,10 +21990,8 @@ async function uploadAttachment(pageId, fileData, filename, comment) {
   });
   if (!res.ok) {
     const body = await res.text();
-    console.error(`Confluence API error (${res.status}): ${body}`);
-    throw new Error(
-      `Confluence API error (${res.status}): ${sanitizeError(body)}`
-    );
+    console.error(`Confluence API error (${res.status}): ${sanitizeError(body)}`);
+    throw new ConfluenceApiError(res.status, body);
   }
   const data = UploadResultSchema.parse(await res.json());
   const att = data.results[0];
@@ -21966,7 +22007,7 @@ function buildAttributionFooter(action) {
 }
 function stripAttributionFooter(body) {
   return body.replace(
-    /<!-- epimethian-attribution-start -->[\s\S]*?<!-- epimethian-attribution-end -->/g,
+    /<!--\s*epimethian-attribution-start\s*-->[\s\S]*?<!--\s*epimethian-attribution-end\s*-->/g,
     ""
   ).trimEnd();
 }
@@ -22070,20 +22111,22 @@ function registerTools(server, config2) {
   server.registerTool(
     "update_page",
     {
-      description: "Update an existing Confluence page. Auto-increments version number.",
+      description: "Update an existing Confluence page. You must provide the version number from your most recent get_page call. If the page was modified by someone else since then, this will return a conflict error \u2014 re-read the page and retry.",
       inputSchema: {
         page_id: external_exports.string().describe("The Confluence page ID"),
-        title: external_exports.string().optional().describe("New title (omit to keep current)"),
+        title: external_exports.string().describe("Page title (use the title from get_page if unchanged)"),
+        version: external_exports.number().int().positive().describe("The page version number from your most recent get_page call"),
         body: external_exports.string().optional().describe("New body content in plain text or storage format"),
         version_message: external_exports.string().optional().describe("Optional version comment")
       },
-      annotations: { destructiveHint: false, idempotentHint: true }
+      annotations: { destructiveHint: false, idempotentHint: false }
     },
-    async ({ page_id, title, body, version_message }) => {
+    async ({ page_id, title, version: version2, body, version_message }) => {
       try {
         const { page, newVersion } = await updatePage(page_id, {
           title,
           body,
+          version: version2,
           versionMessage: version_message
         });
         return toolResult(
@@ -22323,12 +22366,13 @@ function registerTools(server, config2) {
           `</ac:structured-macro>`
         ].join("\n");
         const current = await getPage(page_id, true);
-        const newVersion = (current.version?.number ?? 0) + 1;
         const existingBody = current.body?.storage?.value ?? current.body?.value ?? "";
         const newBody = append ? `${existingBody}
 ${macro}` : macro;
-        const { page } = await updatePage(page_id, {
+        const { page, newVersion } = await updatePage(page_id, {
+          title: current.title,
           body: newBody,
+          version: current.version?.number ?? 0,
           versionMessage: `Added diagram: ${filename}`
         });
         return toolResult(
@@ -22398,6 +22442,9 @@ async function run() {
   } else if (command === "status") {
     const { runStatus: runStatus2 } = await Promise.resolve().then(() => (init_status(), status_exports));
     await runStatus2();
+  } else if (command === "agent-guide") {
+    const { runAgentGuide: runAgentGuide2 } = await Promise.resolve().then(() => (init_agent_guide(), agent_guide_exports));
+    runAgentGuide2();
   } else {
     await main();
   }