@de-otio/epimethian-mcp 4.1.2 → 4.2.0

package/README.md

@@ -74,31 +74,68 @@ Each project's `.mcp.json` specifies which profile to use. Profiles are fully is
 Manage profiles:
 
 ```bash
-epimethian-mcp profiles              # list all
-epimethian-mcp profiles --verbose    # show URLs and emails
+epimethian-mcp profiles              # list all (shows read-only status)
+epimethian-mcp profiles --verbose    # show URLs, emails, and read-only status
 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.
 
+### Per-Profile Read-Only Mode
+
+Protect client tenants from accidental writes:
+
+```bash
+epimethian-mcp profiles --set-read-only acme-corp
+epimethian-mcp profiles --set-read-write jambit
+```
+
+New profiles default to **read-only**. The `setup` command prompts "Enable writes for this profile? [y/N]" or accepts `--read-write` for non-interactive use.
+
+When a profile is read-only, all write tools (`create_page`, `update_page`, `update_page_section`, `delete_page`, `add_attachment`, `add_drawio_diagram`, `add_label`, `remove_label`, `create_comment`, `resolve_comment`, `delete_comment`, `set_page_status`, `remove_page_status`) return an error with a remediation command. Read tools work normally. The read-only flag is resolved at server startup — restart running servers after changing it.
+
+## Token Efficiency
+
+Confluence pages are verbose — storage format HTML with macro markup can easily reach 50,000+ tokens. Epimethian reduces token usage through several strategies, all lossless with respect to Confluence data:
+
+- **Drill-down pattern** — Use `headings_only` to get a page outline (~500 tokens), then `section` to read just the part you need in storage format. No need to fetch the full page body.
+- **Section-level editing** — `update_page_section` replaces content under a single heading. The rest of the page is never touched, eliminating the need to send the full body on updates.
+- **Page cache** — An in-memory, version-keyed cache eliminates redundant API calls during iterative editing. After updating a page, subsequent reads serve from cache (~90% fewer tokens on repeated reads).
+- **Search excerpts** — Search results include content previews so the agent can triage results without calling `get_page` on each one.
+- **Markdown view** — `format: "markdown"` returns a compact read-only rendering where macros become `[macro: name]` placeholders. The server rejects any attempt to write markdown back — storage format is the only accepted write format.
+- **Truncation** — `max_length` cuts the body at an element boundary with a `[truncated at N of M characters]` marker.
+
 ## Tools
 
 | Tool                 | Description                |
 | -------------------- | -------------------------- |
 | `create_page`        | Create a new page          |
-| `get_page`           | Read a page by ID (supports `headings_only` outline) |
-| `get_page_by_title`  | Look up a page by title (supports `headings_only` outline) |
-| `update_page`        | Update an existing 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_section`| Update a single section by heading name |
 | `delete_page`        | Delete a page              |
 | `list_pages`         | List pages in a space      |
 | `get_page_children`  | Get child pages            |
-| `search_pages`       | Search via CQL             |
+| `search_pages`       | Search via CQL (includes content excerpts) |
 | `get_spaces`         | List available spaces      |
 | `add_attachment`     | Upload a file attachment   |
 | `get_attachments`    | List attachments on a page |
 | `add_drawio_diagram` | Add a draw.io diagram      |
+| `get_labels`         | Get all labels on a page   |
+| `add_label`          | Add one or more labels to a page |
+| `remove_label`       | Remove a label from a page |
+| `get_comments`       | Read page comments (footer and inline) |
+| `create_comment`     | Add a comment to a page    |
+| `resolve_comment`    | Resolve or reopen an inline comment |
+| `delete_comment`     | Delete a comment           |
+| `get_page_status`    | Get the content status badge on a page |
+| `set_page_status`    | Set the content status badge on a page |
+| `remove_page_status` | Remove the content status badge from a page |
+| `get_page_versions`  | List version history for a page |
+| `get_page_version`   | Get page content at a specific historical version |
+| `diff_page_versions` | Compare two versions of a page |
 
 ## Credential Security