cpi-saper-dev-mcp 0.0.0-stage → 0.9.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes of the `cpi-saper-dev-mcp` server. Versions follow [semantic versioning](https://semver.org/);
+before 1.0, names and behaviour may still change between versions.
+
+## 0.9.0-beta.0 (2026-11-02)
+
+First public beta. **For development tenants only**: do not connect a production tenant (see the README).
+
+### Tools (51)
+
+- **Tenant, read:** `cpi_tenants`, `cpi_packages`, `cpi_artifacts` (iFlows and script collections), `cpi_pull`,
+  `cpi_status` (local vs pulled vs tenant: in sync, modified, changed on the tenant, conflict), `cpi_runtime_status`,
+  `cpi_endpoints`, `cpi_security_material` (names, types, validity; never secrets), `cpi_config_get`.
+- **Understand:** `iflow_describe`, `iflow_render` (Mermaid), `iflow_diff` (also as a `git diff` driver:
+  `cpi-saper-dev-mcp textconv`), `mapping_describe` (message mappings, read-only), `templates_list` (step and adapter
+  catalog).
+- **Edit locally:** `iflow_edit`: steps from the catalog, adapters with their Sender/Receiver boxes, exception
+  subprocess, routers and parallel/sequential multicasts with Join, steps on routes, XSLT and message mapping files,
+  Filter expressions, scripts from script collections, settings, headers and properties, layout of the process;
+  all-or-nothing batches with a dry run. `params_set` for externalized parameters.
+- **Check:** `iflow_validate` (structure, missing files, undeclared parameters, and settings the tenant refuses only at
+  deploy), `xslt_run`, `script_run` (Groovy on the tenant's script runner), `cpi_guidelines`, `cpi_check`.
+- **Change the tenant (development tenants, allowed packages):** `iflow_create`, `iflow_delete`, `cpi_push` (every
+  upload a version, number and comment confirmed by you), `cpi_version_proposal`, `cpi_save_version`, `cpi_deploy`
+  (with SAP's guideline check as an optional gate), `cpi_undeploy`, `cpi_config_set`.
+- **Script collections:** `script_collection_create`, `_pull`, `_push`, `_deploy`, `_delete`.
+- **Test and monitor:** `cpi_send_message`, `cpi_messages`, `cpi_message`, `cpi_trace` (experimental), `cpi_login`.
+- **Runtime data:** `cpi_datastores`, `cpi_datastore_entry`, `cpi_datastore_delete`, `cpi_variables`,
+  `cpi_variable_delete`, `cpi_queues`, `cpi_queue_action` (JMS), `cpi_number_ranges`, `cpi_number_range_set`,
+  `cpi_duplicate_checks`, `cpi_duplicate_check_delete`, `cpi_message_store`.
+
+### Safety
+
+Read-only and development roles per tenant, allowed packages, confirmation of changes through your MCP client
+(configurable; `unattendedTestMode` for agent test runs only), an audit log, credential values never returned.
+
+### Known gaps
+
+- Tried against one tenant (a BTP trial); other tenants may answer differently in places
+  ([docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) lists every difference found).
+- iFlows with local integration processes cannot be laid out or branched by `iflow_edit`.
+- Not offered by design: creating or deleting packages, editing message mappings, managing locks.
+- Planned: `lint`, PNG rendering, user roles for sender authorization.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,8 @@
+cpi-saper-dev-mcp
+Copyright 2026 Damian Kolasa (devstylator)
+
+Originally created by Damian Kolasa (devstylator): https://github.com/devstylator/cpi-saper-dev-mcp
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE). Redistributions, including modified
+versions and derivative works, must keep this NOTICE file (Apache License 2.0, section 4(d)), so the original creator
+stays credited, and modified files must carry a notice that they were changed (section 4(b)).

package/README.md

@@ -1,3 +1,276 @@
-# Temporary Holding Version
+# cpi-saper-dev-mcp
 
-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.
+[![CI](https://github.com/devstylator/cpi-saper-dev-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/devstylator/cpi-saper-dev-mcp/actions/workflows/ci.yml)
+
+> [!WARNING]
+> **For development tenants only. Do not connect this server to a production tenant**, not even with `role:
+> readonly`. It is built for developing and testing on development systems: it uploads, deploys and deletes content,
+> sends test messages, runs scripts, and reads and changes runtime data (data stores, variables, number ranges,
+> queues). Its safety rules protect a development tenant from mistakes, not a production system from risk.
+
+An MCP server that lets an AI agent **develop** SAP Cloud Integration (CPI) content: edit iFlows, Groovy scripts
+and XSLT as local files under git, check them locally, then push, deploy and test them on a development tenant.
+
+> **Status: public beta (0.9.0-beta).** Everything listed as Available was tried against a BTP trial tenant, by
+> the author and by AI agents in test runs. Expect rough edges and report them as
+> [issues](https://github.com/devstylator/cpi-saper-dev-mcp/issues); names and behaviour may still change before
+> 1.0 ([CHANGELOG](CHANGELOG.md)).
+
+## What it does
+
+- **Read** packages, iFlows and their status; pull an iFlow into a local folder.
+- **Understand** an iFlow without reading BPMN XML: a compact model, a Mermaid diagram, readable message mappings.
+- **Edit** iFlows safely: insert steps with correct default settings from a bundled step catalog
+  ([catalog](packages/core/catalog/)), change settings, headers and properties; keep the file formatted like SAP's designer.
+- **Check** locally: structure validation, XSLT 1.0–3.0 runs, readable model-level diffs (also for `git diff`).
+- **Test on the tenant** (development tenants only): push, run SAP's design guideline check, deploy, send a test
+  message, read the message log with the failing step by name, run a single Groovy script without deploying.
+
+## Tools
+
+**Available** tools work and were tried against a real tenant; **Planned** means designed but not built yet.
+
+The agent's own environment (for example Claude Code or VS Code) reads and writes the local files, so the server
+adds no generic file tools.
+
+### Tenant: read
+
+| Tool | What it does | Status |
+|---|---|---|
+| `cpi_login` | Log in with your own SAP account, so the tenant records **you** (not a technical client) as the one who changed or deployed content ([how to set it up](docs/CONFIGURATION.md#recording-changes-under-your-name)) | **Available** |
+| `cpi_tenants` | Configured tenants and what the agent may do on each (read only, or development with writes) | **Available** |
+| `cpi_packages` | List packages; a package can be named by its ID or its display name | **Available** |
+| `cpi_artifacts` | List the iFlows and script collections of a package with version and runtime status | **Available** |
+| `cpi_pull` | Download an iFlow into the local workspace (`<workspace>/<package>/<iflow>/`, SAP's file layout); never overwrites local changes unless asked | **Available** |
+| `cpi_status` | For every pulled iFlow and script collection (or one, or a package's): in sync, modified locally, changed on the tenant, or conflict, with pulled, tenant and deployed versions; with a package also what is not pulled | **Available** |
+| `cpi_runtime_status` | Deployment state and deploy errors, with step IDs translated to step names | **Available** |
+| `cpi_endpoints` | HTTP endpoint URLs of deployed iFlows | **Available** |
+| `cpi_security_material` | Names, types, expiry (days left) and deploy status of keystore entries, user credentials, OAuth2 clients and secure parameters; passwords, secrets, user names, secure values and certificates are never returned | **Available** |
+| `cpi_config_get` | Configured values of externalized parameters, compared with the local `parameters.prop` | **Available** |
+
+### Understand
+
+| Tool | What it does | Status |
+|---|---|---|
+| `iflow_describe` | Compact model of an iFlow (steps, adapters, settings, routes, decoded header tables) instead of BPMN XML; steps numbered `#1`, `#2` … in flow order | **Available** |
+| `iflow_render` | Mermaid diagram of an iFlow; PNG later | **Available** (Mermaid) |
+| `iflow_diff` | Model-level changes between two versions: steps added or removed, settings old → new, table rows, rewired flows; ignores layout and IDs the designer regenerates. Also available as a [`git diff` driver](#readable-git-diff) | **Available** |
+| `mapping_describe` | Message mapping as one line per target field, `target <- expression` (read-only) | **Available** |
+| `templates_list` | The bundled step and adapter catalog ([catalog](packages/core/catalog/)): 106 variants with default settings | **Available** |
+
+### Edit locally
+
+| Tool | What it does | Status |
+|---|---|---|
+| `iflow_edit` | Semantic edits in one all-or-nothing batch: insert a step from the catalog (with settings, headers, properties; for XSLT and message mappings the mapping file, for a Filter its XPath, for a script step a script from a script collection), remove a step, add or remove an adapter (sender to a start event or Poll Enrich, receiver from Request Reply, Send, Content Enricher or an end event; the Sender/Receiver box is reused or created, receivers drawn below their step), add or remove an exception subprocess (steps go inside like anywhere else), add routers (conditions, default route) and parallel or sequential multicasts with a Join, put steps on their routes, edit or remove them, lay out the process (branches in rows, exception subprocess below), change settings of steps, adapters or the iFlow (unknown keys refused), rename, edit Content Modifier headers and properties. Keeps SAP's formatting, lays out the diagram, refuses edits that would break the iFlow, supports a dry run | **Available** |
+| `params_set` | Declare, change or remove externalized parameters: `parameters.propdef` and `parameters.prop` kept consistent in the designer's format; shows where each `{{name}}` is used | **Available** |
+
+### Check
+
+| Tool | What it does | Status |
+|---|---|---|
+| `iflow_validate` | Structural checks: dangling flows, missing diagram shapes, unreachable steps, missing script or mapping files, undeclared parameters; settings the tenant refuses only at deploy (empty split or Filter expression, key alias or mapping file, a Content Enricher or Request Reply without adapter, sender authorization values, Receiver names with spaces) | **Available** |
+| `xslt_run` | Run an XSLT (1.0–3.0) locally with headers and properties as parameters, like a CPI XSLT Mapping step; errors with line numbers | **Available** |
+| `script_run` | Run one Groovy script (also from a script collection) on the tenant without deploying (script runner iFlow, development tenants only); Groovy 2.4 or 4 chosen from the script's imports; returns body, headers, properties, console output and what changed | **Available** |
+| `cpi_guidelines` | Run SAP's design guideline check on the tenant (deploys through the API skip it) | **Available** |
+| `cpi_check` | Run the tenant's model check ("Check for problems") | **Available** |
+| `lint` | Local rules for common mistakes, including those SAP's guideline check flags | Planned |
+
+### Tenant: change (development tenants only)
+
+Changes ask for your confirmation, and every version needs a number and comment you confirm. For letting AI agents
+test the server on their own there is an
+[unattended test mode](docs/CONFIGURATION.md#unattended-test-mode-test-only): **test only, not for real
+development.**
+
+| Tool | What it does | Status |
+|---|---|---|
+| `cpi_push` | Upload a local iFlow as a **new version**: the agent proposes number and one-line comment by the versioning rules, you confirm both in a dialog, and Cloud Integration's version history shows exactly that entry. Refuses when the tenant changed since the pull or the iFlow is open in the designer | **Available** |
+| `cpi_version_proposal` | The versioning rules (default or your own file), the local changes since the last version and a hint (major/minor/patch), so the agent can propose number and comment | **Available** |
+| `cpi_save_version` | Record the tenant's current content as a new version with number and comment, for example after work in the designer | **Available** |
+| `iflow_create` | Create an empty iFlow in an allowed package (as the designer does: Sender and Receiver box, Start → End, version 1.0.0) and pull it; build it with `iflow_edit`, then `cpi_push` gives it its first version | **Available** |
+| `cpi_deploy` | Deploy the current version and wait; SAP's guideline check as an optional gate; errors are reported with step names, one line per problem. A failed deploy also stops the version that was running (Cloud Integration's behaviour), which the confirmation and result point out | **Available** |
+| `cpi_undeploy` | Remove a deployed iFlow or script collection from the runtime | **Available** |
+| `iflow_delete` | Delete an iFlow with its whole version history (for cleaning up test iFlows); refuses deployed iFlows and always asks for confirmation by default | **Available** |
+| `cpi_config_set` | Configure parameter values on the tenant like "Configure" in the designer (no new version; the running iFlow uses them after the next deploy); the local `parameters.prop` follows | **Available** |
+
+### Script collections (development tenants only)
+
+Scripts shared by the iFlows of a package. A Groovy or JavaScript step uses one with `iflow_edit` `insert_step`
+`scriptCollection` (the collection's Id, `settings.script` the file name); the iFlow's manifest requirement is written
+as the designer does. `iflow_validate` checks the script against a collection pulled into the same package folder, and
+`cpi_deploy` refuses while a collection the iFlow uses is missing, in another package or not deployed in its latest version.
+
+| Tool | What it does | Status |
+|---|---|---|
+| `script_collection_create` | Create an empty collection in an allowed package and pull it (`<workspace>/<package>/<id>/`, scripts in `src/main/resources/script/`) | **Available** |
+| `script_collection_pull` | Download a collection; never overwrites local changes unless asked | **Available** |
+| `script_collection_push` | Upload it as a new version: version and comment confirmed by you (hint: a removed script is major, a new one minor); the comment goes to the changelog, since the tenant keeps none for collections | **Available** |
+| `script_collection_deploy` | Deploy it (before the iFlows that use it); with `deploy: manual` you deploy it in the designer | **Available** |
+| `script_collection_delete` | Delete it with its version history; refuses a deployed collection; always asks by default | **Available** |
+
+### Runtime data
+
+What iFlows keep on the tenant between messages. Reading works on every configured tenant; changing only on
+development tenants, for data of iFlows in allowed packages (global data: any development tenant; a JMS queue: every
+iFlow using it must be in an allowed package), with your confirmation (`runtime_data`).
+
+| Tool | What it does | Status |
+|---|---|---|
+| `cpi_datastores` | Data stores (Write steps): all stores with their iFlow or global, entries and overdue entries; with a store, its entries | **Available** |
+| `cpi_datastore_entry` | One entry's stored message: body and headers (credential-like values hidden) | **Available** |
+| `cpi_datastore_delete` | Delete entries or a whole store, for example to reset test data | **Available** |
+| `cpi_variables` | Variables (Write Variables): all with their iFlow or global; with a name, its value | **Available** |
+| `cpi_variable_delete` | Delete a variable, for example to restart a delta load | **Available** |
+| `cpi_queues` | JMS broker (capacity, queues used of the maximum, warnings) and queues with messages, size, state and the iFlows that read or write them; with a queue, its messages (failed, retries, next retry, message log) | **Available** |
+| `cpi_queue_action` | Retry failed messages now, move messages to another queue, delete messages, activate or deactivate a queue | **Available** |
+| `cpi_number_ranges` | Number ranges (used by number range steps): min, max, current value, field length, rotate | **Available** |
+| `cpi_number_range_set` | Create, change (for example reset the current value) or delete a number range; values checked before you are asked | **Available** |
+| `cpi_duplicate_checks` | What was already processed and is skipped when it comes again (idempotent repository: file names of SFTP senders, ids of Idempotent Process Call steps), with expiry | **Available** |
+| `cpi_duplicate_check_delete` | Remove such entries so the same file or id is processed again in the next test | **Available** |
+| `cpi_message_store` | What the Persist steps of one message stored: entries, and an entry's body and headers | **Available** |
+
+### Test
+
+| Tool | What it does | Status |
+|---|---|---|
+| `cpi_send_message` | Call a deployed iFlow's HTTP endpoint; fetches a CSRF token when the sender adapter requires one (the HTTPS sender default); returns status, response and the message log ID (also for failed calls) | **Available** |
+| `cpi_messages` | Search message processing logs | **Available** |
+| `cpi_message` | One message log: status, error, and the processing steps by name (at log level INFO, SAP keeps steps for failed messages only) | **Available** |
+| `cpi_trace` | Body, headers and properties as they entered each step of one message. Uses an undocumented SAP endpoint to switch on tracing, so it sits behind an "experimental" setting | **Available** |
+
+### Not offered, by design
+
+- **Creating or deleting packages.** Packages are set up by people (with their names, vendors and access); the agent
+  works inside existing packages that the configuration allows.
+- **Managing locks.** Message and design-time locks are held by the runtime and the designer for running work; the
+  agent does not release them. Tools only report a lock where it blocks something (for example a push to an iFlow
+  open in the designer).
+- **Editing message mappings.** Message mappings can be read (`mapping_describe`) but not changed: edit them in the
+  designer's mapping editor.
+
+**Safety:** changes are only allowed on tenants configured as development tenants, in allowed packages that are not
+read-only content. A push stops when the iFlow is open in the designer or changed on the tenant since the pull. Create,
+delete, push, deploy and undeploy ask **you** for confirmation through the MCP client (MCP *elicitation*, showing the actual
+changes); clients that cannot ask are refused rather than skipping the question. Every change is written to an audit
+log, and credential values are never shown to the agent. With `"login": "user"`, the tenant records your own user
+for every change instead of the service key's technical client.
+
+## Install
+
+Requires Node.js 22 or later. The server is published on npm as
+[`cpi-saper-dev-mcp`](https://www.npmjs.com/package/cpi-saper-dev-mcp): your AI client starts it with `npx`, which
+downloads it on first use. During the beta the examples use `cpi-saper-dev-mcp@beta` (the newest beta); to pin one
+version, write for example `cpi-saper-dev-mcp@0.9.0-beta.0`.
+
+Create `.cpi/config.json` in your project folder ([docs/CONFIGURATION.md](docs/CONFIGURATION.md)), then connect the
+server to your AI client as shown below.
+
+**How the server finds your configuration:** it asks the client which project folders are open (MCP *roots*) and
+uses the first one that contains `.cpi/config.json`. Clients that do not report roots get the server's working
+folder instead. Without a project, it falls back to `~/.config/cpi-saper-dev-mcp/config.json`, or to the file named
+in the environment variable `CPI_MCP_CONFIG`.
+
+### Claude Code
+
+From your project folder:
+
+```sh
+claude mcp add cpi-saper-dev-mcp -- npx -y cpi-saper-dev-mcp@beta
+```
+
+### GitHub Copilot in VS Code
+
+Add the server to your project in `.vscode/mcp.json` (create the file if it does not exist):
+
+```json
+{
+  "servers": {
+    "cpi-saper-dev-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "cpi-saper-dev-mcp@beta"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+VS Code asks you to trust the server the first time it starts it. The tools are then available to Copilot's agent in
+Copilot Chat. `cwd` makes the project folder the server's working folder, so it finds `.cpi/config.json` even if
+roots are not reported.
+
+VS Code also reads a workspace-root `.mcp.json` in the shared format (the same file Claude Code uses), when the
+setting `chat.mcp.workspaceRootConfig.enabled` is on:
+
+```json
+{
+  "mcpServers": {
+    "cpi-saper-dev-mcp": {
+      "command": "npx",
+      "args": ["-y", "cpi-saper-dev-mcp@beta"]
+    }
+  }
+}
+```
+
+This format has no working-folder setting; the server then relies on the roots VS Code reports.
+
+### GitHub Copilot CLI and other projects
+
+For all projects at once, add the server to Copilot's user configuration `~/.copilot/mcp-config.json` (or
+`$COPILOT_HOME/mcp-config.json`), with the same `mcpServers` entry as above. Keep a shared configuration in
+`~/.config/cpi-saper-dev-mcp/config.json` (with absolute paths to your service keys); a project's own
+`.cpi/config.json` still takes precedence when the client reports that project as a root.
+
+### From source
+
+To run the latest code from this repository instead:
+
+```sh
+git clone https://github.com/devstylator/cpi-saper-dev-mcp.git
+cd cpi-saper-dev-mcp
+npm install
+npm test            # builds and runs the tests
+```
+
+and use `node /path/to/cpi-saper-dev-mcp/packages/mcp-server/dist/index.js` as the command (in place of
+`npx -y cpi-saper-dev-mcp@beta`). `npm run pack:check` builds the npm package and tries it the way users install it.
+
+### Readable git diff
+
+`git diff` of an `.iflw` file shows BPMN XML and diagram coordinates. With the server as git's diff driver, it shows
+the model instead, one fact per line (steps with their settings, adapters, flows; message mappings as
+`target <- expression`), so a change reads as "+ step … / - flow …". In your repository:
+
+```sh
+printf '*.iflw diff=cpi\n*.mmap diff=cpi\n' >> .gitattributes
+git config diff.cpi.textconv "npx -y cpi-saper-dev-mcp@beta textconv"
+```
+
+`npx` looks the package up on every start, which makes diffs of many files slow: for regular use install it once
+(`npm install -g cpi-saper-dev-mcp@beta`) and use `cpi-saper-dev-mcp textconv` as the textconv command.
+
+`git diff --no-textconv` still shows the XML. It applies wherever git shows diffs (`git diff`, `git log -p`, `git show`); merges are unchanged.
+
+## Requirements
+
+- Node.js 22 or later.
+- A Cloud Integration tenant (a BTP trial works) and two service keys of the *Process Integration Runtime*
+  service: plan `api` (OData API) and plan `integration-flow` (calling deployed iFlows).
+- **Optional, for running Groovy scripts on the tenant:** the script runner iFlow from
+  [devstylator/CPI_Iflow_GroovyScriptExe](https://github.com/devstylator/CPI_Iflow_GroovyScriptExe) deployed on a development tenant.
+  Its API is described in [docs/script-runner.openapi.yaml](docs/script-runner.openapi.yaml). The runner executes
+  any code it receives, so never deploy it on test or production tenants.
+
+## Documentation
+
+- [docs/CONFIGURATION.md](docs/CONFIGURATION.md): tenants, roles, service keys and safety settings (planned).
+- [docs/KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md): where local checks differ from Cloud Integration.
+- [docs/script-runner.openapi.yaml](docs/script-runner.openapi.yaml): API of the script runner iFlow.
+
+## License
+
+[Apache License 2.0](LICENSE). Created by Damian Kolasa ([devstylator](https://github.com/devstylator)).
+Free to use, change and share, also commercially; copies and modified versions must keep the [NOTICE](NOTICE)
+file, which credits the original creator, and mark the files they changed.