layoutbridge-light 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,326 @@
-# Temporary Holding Version
+# LayoutBridge Light for Adobe InDesign®
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Deutsche Fassung: [README.de.md](README.de.md)
+
+**LayoutBridge Light for Adobe InDesign®** – MCP server for book typesetting
+in Adobe® InDesign® (npm package `layoutbridge-light`) by MCP Interfaces. It
+provides the tools a book needs, for any MCP-capable AI: documents and
+pages, master pages and sections, layout grid, text frames and autoflow of
+whole manuscripts, text, paragraph and character styles with drop caps,
+images and anchored objects, table of contents and index, typography
+checks, print-on-demand checks and book covers, preflight and export (PDF,
+page images and e-books as EPUB, with a check of the EPUB).
+
+LayoutBridge Light is the book edition of LayoutBridge for Adobe InDesign®:
+same server, 77 of its tools. Not included are tables, layers, groups and
+object styles, shapes, lines and effects, page reordering, packaging and the
+tools for taking over third-party documents. It needs its own licence key; a key for
+LayoutBridge for Adobe InDesign® does not work here, and vice versa.
+
+Product page: https://mcp-interfaces.com/layoutbridge-light/ (German:
+https://mcp-schnittstellen.de/layoutbridge-light/).
+Step-by-step installation guide:
+https://mcp-interfaces.com/layoutbridge-light/installation.html (German:
+https://mcp-schnittstellen.de/layoutbridge-light/installation.html).
+
+Adobe and InDesign are either registered trademarks or trademarks of Adobe in
+the United States and/or other countries.
+
+## Requirements
+
+- Adobe® InDesign®, installed and running – Mac or Windows (Windows 10/11
+  x64; tested with InDesign® 21.5.1.73 on Windows 11)
+- Windows: Windows PowerShell 5.1 (`powershell.exe`, included in Windows)
+- Your licence key from the purchase receipt e-mail – one key per
+  workstation
+- A network connection for the licence check on the first call
+- **Node.js version 20 or newer – only for the npm package** (entry in the
+  configuration file, `--setup`, `--deactivate`) **and for other MCP
+  clients.** With the installation package (`.mcpb`) no separate Node.js
+  installation is needed – Claude Desktop comes with Node.js (switch “Use
+  built-in Node.js for MCP” under “Advanced settings”, on by default).
+
+## Installation in Claude Desktop
+
+There are two ways. Way A is the shorter one; Way B is the same entry that
+other MCP clients receive. The installation guide linked above shows every
+step with Mac and Windows details.
+
+**Way A – installation package (bundle file `.mcpb`)**
+
+1. Download the file `layoutbridge-light-<version>.mcpb` from the product
+   page.
+2. In Claude Desktop, open Settings › Desktop app › Extensions and drag the
+   file into that window – it says “Drag .MCPB or .DXT files here to
+   install”. On Mac you can open the file by double-clicking it instead. On
+   Windows, double-clicking does not open Claude Desktop – Windows asks
+   which app to use; drag the file into the window, or choose “Advanced
+   settings” › “Install extension” and select the file. Confirm the
+   installation dialog with “Install”.
+3. Enter your licence key in the field “Licence key” and click “Save”. The
+   key is stored by Claude Desktop on your computer.
+4. **Switch the extension on.** After installation, “LayoutBridge for
+   Adobe InDesign®” is listed under Settings › Extensions as “Disabled”.
+   Switch it to enabled – otherwise no tools appear.
+
+**Way B – npm package (Node.js version 20 or newer)**
+
+Setup command – run in Terminal (Mac) or PowerShell (Windows):
+
+```
+npx layoutbridge-light --setup
+```
+
+The command adds the server to the Claude Desktop configuration file and
+stores the licence key in the default location (see “Licence key”). It
+only runs when you call it. Before every change it shows the full path of
+the file and the new entry verbatim and asks for confirmation (`y` for
+yes, `n` for no). Before writing it creates a backup
+`claude_desktop_config.json.bak-YYYY-MM-DD_HHMM` in the same folder; only
+the entry `layoutbridge-light` under `mcpServers` is changed, all other
+entries stay unchanged. If the file is not valid JSON, it stops and names
+line and column. The licence key is asked for without being shown and is
+written only to `license.key`. No administrator rights, no network
+connection. On Windows it uses the configuration folder of the Claude
+Desktop package (see “By hand”) if there is one, otherwise
+`%APPDATA%\Claude`, and says which one it chose; if it finds several
+Claude Desktop packages and cannot tell which one is in use, it stops
+without changing anything.
+
+- `--dry-run` shows the same and writes nothing.
+- `--license-key-file <path>` reads the key from a file instead of asking
+  for it.
+
+**By hand:** open the configuration file of Claude Desktop in a text
+editor. On Windows, the simplest way is Settings › Desktop app › Developer ›
+“Edit Config”: it opens the folder Claude Desktop actually reads. For the
+usual installation as an app package this is
+`%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json`
+(`<id>` is a combination of letters and digits); only an installation
+without a package uses `%APPDATA%\Claude\claude_desktop_config.json`. On
+the Mac the file is `~/Library/Application Support/Claude/claude_desktop_config.json`
+(“Edit Config” works there as well). If the file is empty or does not exist
+yet, its complete content is this:
+
+```json
+{
+  "mcpServers": {
+    "layoutbridge-light": {
+      "command": "npx",
+      "args": ["-y", "layoutbridge-light"]
+    }
+  }
+}
+```
+
+If the file already lists other servers under `"mcpServers"`, insert only
+the block `"layoutbridge-light": { … }` there – with a comma between the
+entries – and leave everything else unchanged. Then store the licence key
+(see “Licence key”). On the first start, `npx` downloads the package
+`layoutbridge-light` from the npm registry; after that it starts from the
+local cache.
+
+**Then:** quit Claude Desktop completely – on Mac with ⌘ + Q, on Windows
+via “Quit” in the application menu; closing the window is not enough –
+and start it again. Start Adobe® InDesign® and ask in Claude Desktop:
+“Which InDesign® version is running?” Claude calls the tool
+`get_app_version` and reports the version. The tools appear under the
+extension name “LayoutBridge Light for Adobe InDesign®” on Way A, and with the
+prefix `layoutbridge-light:` on Way B.
+
+## Other MCP clients
+
+Other MCP clients (Claude Code, Cursor, GitHub Copilot and others) register
+the same server according to their own documentation. The command is
+always
+
+```
+npx -y layoutbridge-light
+```
+
+and requires Node.js version 20 or newer. The licence key is found in the
+same places as described under “Licence key”.
+
+## Licence key
+
+The key is in the purchase receipt e-mail and is valid for exactly one
+workstation; several workstations need several keys.
+
+**Where LayoutBridge looks for the key, in this order:**
+
+1. the environment variable `LAYOUTBRIDGE_LIGHT_LICENSE_KEY` – the
+   installation package sets it from the field “Licence key”; on Way B it
+   can go into the server entry as `"env": { "LAYOUTBRIDGE_LIGHT_LICENSE_KEY":
+   "YOUR-LICENCE-KEY" }`,
+2. the file named in the environment variable `LAYOUTBRIDGE_LIGHT_LICENSE_FILE`,
+3. the file `license.key` at the default location – the key only, no other
+   text:
+   - Mac: `~/Library/Application Support/layoutbridge-light/license.key`
+   - Windows: `%USERPROFILE%\.layoutbridge-light\license.key`
+
+Create the folder `layoutbridge-light` or `.layoutbridge-light` if it does not
+exist. A key added or changed later takes effect without a restart.
+
+**Check:** on the first tool call LayoutBridge verifies the key online;
+after that at most once every 24 hours. If the service cannot be reached,
+LayoutBridge keeps working for 14 days from the last valid check and
+appends a warning to every response; after that, or if no valid check has
+ever taken place, the tools are locked until the key can be verified
+again.
+
+**Without a valid key** every tool answers with `ok: false` and
+`error.kind: "license"`. The message says in plain words whether the key is
+missing, expired, invalid, for another product or cannot be verified right
+now, and names the location where the key was expected; `error.details`
+adds the support address and the licence terms. InDesign® is not
+contacted.
+
+**What is stored and transmitted:** the result of the last check is stored
+in `license-state.json` next to `license.key` – with a fingerprint of the
+key, never the key itself, and without customer data. For the check, the
+licence key and an identifier of this workstation go to the payment service
+Polar (`api.polar.sh`, USA). The identifier is a random
+name of the form `layoutbridge-<8 characters>`, created the first time and
+stored in `instance-name` next to `license.key`; the computer name is not
+used. Anyone who wants a readable name in the merchant account sets
+`LAYOUTBRIDGE_LIGHT_INSTANCE_NAME`. Document contents, file paths and tool
+calls are never transmitted.
+
+## Changing computers
+
+A licence is active on one workstation. Release it on the old computer
+before entering the key on the new one – no InDesign®, no Claude Desktop
+needed, but Node.js version 20 or newer:
+
+```
+npx layoutbridge-light --deactivate
+```
+
+The command reports in plain text whether the release worked and deletes
+the local check result. It reads the key from the same places as the
+server (see “Licence key”); with the installation package the key is kept
+by Claude Desktop, so put it into `license.key` first or write to support.
+If you have no Node.js because you only use the installation package, or
+if the old computer is no longer available, you can release the activation
+yourself in the Polar customer portal or write to support; they release
+the activation.
+
+## Server configuration
+
+Defaults that differ from workplace to workplace can be set in a JSON file
+that the server reads at start: path from the environment variable
+`LAYOUTBRIDGE_LIGHT_CONFIG`, otherwise on the Mac
+`~/Library/Application Support/layoutbridge-light/config.json`, on Windows
+`%USERPROFILE%\.layoutbridge-light\config.json`. If the file is missing, the
+neutral defaults apply. All keys are optional; a parameter in the call
+always takes precedence.
+
+```json
+{
+  "tracking_warn_beyond": 20,
+  "min_ppi": 300,
+  "export_pdf": {
+    "preset": "Name of the PDF preset",
+    "fallback_preset": "Name of the fallback preset",
+    "fallback_over_bytes": 4194304
+  }
+}
+```
+
+| Key | Effect |
+|---|---|
+| `tracking_warn_beyond` | `apply_character_format_to_range` warns if the absolute tracking value exceeds it. Without an entry, no warning. |
+| `min_ppi` | Default for the parameter `min_ppi` of `place_image`, `scale_image_in_frame` and `fit_frame` (warning below this effective resolution). Without an entry 300. |
+| `export_pdf.preset` | Default for `preset` of `export_pdf`. Without an entry the localised “High Quality Print”. |
+| `export_pdf.fallback_preset`, `export_pdf.fallback_over_bytes` | Second pass with this preset if the file is larger. Without an entry no second pass. |
+| `print_on_demand` | Limits of a print-on-demand service for `check_print_on_demand` (`min_page_count`, `max_page_count`, `page_count_multiple`, `inside_margin_tiers` as a list of `max_pages` and `min_mm`, `min_outside_margin_mm`, `bleed_mm`, `min_font_size_pt`) and dimensions for `create_book_cover` (`spine_per_page_mm`, `bleed_mm`, `safety_margin_mm`, `spine_safety_mm`, `barcode_area` with `width_mm`, `height_mm`, `offset_x_mm`, `offset_y_mm`). Take the values from the current requirements of your service. Without an entry the check skips that point. |
+| `epub.min_ppi` | Lowest effective image resolution that `check_epub` accepts for the document check. Without an entry the image resolution is not checked (the general `min_ppi` does not apply to e-books). |
+
+Unknown keys and wrong types are reported by the server at start on
+standard error and ignored.
+
+## Log
+
+One line per call, one file per running instance:
+`~/Library/Logs/layoutbridge-light/` on the Mac,
+`%USERPROFILE%\.layoutbridge-light\logs\` on Windows; other location via the
+environment variable `LAYOUTBRIDGE_LIGHT_LOG_DIR`. The log stays on your
+computer; it is not sent anywhere.
+
+**What the line contains (default `basic`):** timestamp, tool name,
+duration, success, error kind and error text, warnings and the **names** of
+the parameters passed. Values appear only where they are needed for
+troubleshooting and harmless (numbers, identifiers, enumeration values,
+file paths). Text that can be document content appears only as a length –
+`"<Text, 248 Zeichen>"`. In paths your home folder is replaced by `~`. The
+licence key is never logged.
+
+**Setting the depth –** `LAYOUTBRIDGE_LIGHT_LOG_LEVEL`:
+
+| Value | Meaning |
+|---|---|
+| `off` | no logging, no file is created |
+| `basic` | **default**, filtered as described above |
+| `full` | all parameters verbatim, paths with user name – only for troubleshooting, at the request of support |
+
+When `full` is active, the first line of the log and the server's start
+message say so. Afterwards switch back to `basic`.
+
+**Retention:** at start the server deletes log files older than **30
+days**. Other period via `LAYOUTBRIDGE_LIGHT_LOG_KEEP_DAYS` (number of days;
+`0` switches deletion off).
+
+## License terms
+
+Use of LayoutBridge Light for Adobe InDesign® is governed by the
+licence terms (EULA). The German version is authoritative.
+
+- English: https://mcp-interfaces.com/layoutbridge-light/license.html
+- Deutsch: https://mcp-schnittstellen.de/layoutbridge-light/lizenzbedingungen.html
+
+The server names the address in its start line and in every response of the
+error kind `license` (`error.details.license_terms`).
+
+## Privacy Policy
+
+Which data the server processes – licence check with the payment service,
+log on your own computer, nothing else – is set out in the
+product's privacy policy:
+
+- English: https://mcp-interfaces.com/layoutbridge-light/privacy.html
+- Deutsch: https://mcp-schnittstellen.de/layoutbridge-light/datenschutz.html
+
+The licence check calls the payment service Polar; its
+privacy policy: https://polar.sh/legal/privacy.
+
+## Support
+
+Questions and error reports to **kontakt@mcp-interfaces.com**. We answer
+on working days, aiming for within two working days. Helpful are:
+tool name, error text verbatim, time, InDesign version and
+operating system. **Never send us your licence key.**
+
+A copied error message may contain file names and the folder path below
+your home folder as well as names from the document
+(pages, frames, styles) – no user name, no
+document text, no licence key. Bug fixes are implemented
+as quickly as possible.
+
+## Third-party notices
+
+The package contains third-party software (runtime dependencies including
+transitive packages). Name, version, licence, copyright line and full
+licence text per package are in `THIRD-PARTY-NOTICES.md` (included in the
+npm package and in the installation package).
+
+## Versions and changelog
+
+One release a month with a catalogue of new features; bug fixes are
+implemented as quickly as possible, independently of that release cycle. All changes
+are listed in `CHANGELOG.md` (included in the package). Within a
+major version, tool names, parameters and return fields remain stable;
+additions are additive.
+
+## Licence
+
+Proprietary, all rights reserved. See `LICENSE`.