@seamward/setup-mcp 0.1.0-alpha.9

package/LICENSE

@@ -0,0 +1,31 @@
+Seamward Setup MCP Proprietary License
+
+Copyright (c) 2026 Seamward. All rights reserved.
+
+This software and its accompanying documentation are proprietary to Seamward.
+Possession, installation, or availability through a package registry does not
+grant a licence to use, copy, modify, distribute, sublicense, sell, or create
+derivative works from the software.
+
+You may use the software only to the extent expressly permitted by a written
+agreement with Seamward, including an applicable customer, evaluation, pilot,
+or partner agreement. If that agreement conflicts with this notice, the
+written agreement controls.
+
+Except where applicable law does not permit the restriction, you may not:
+
+1. redistribute, publish, sublicense, lease, sell, or transfer the software;
+2. reverse engineer, decompile, disassemble, or attempt to derive source code
+   from any distributed binary or package; or
+3. remove or alter proprietary notices.
+
+THE SOFTWARE IS PROVIDED "AS IS" TO THE MAXIMUM EXTENT PERMITTED BY LAW,
+WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, SEAMWARD IS NOT
+LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES,
+OR FOR LOSS OF DATA, REVENUE, PROFITS, OR BUSINESS OPPORTUNITY, ARISING FROM OR
+RELATED TO THE SOFTWARE.
+
+No trademark rights are granted. All rights not expressly granted in a written
+agreement with Seamward are reserved.

package/README.md

@@ -0,0 +1,270 @@
+# Seamward local setup MCP
+
+`@seamward/setup-mcp` is a repository-scoped stdio server for coding agents.
+It analyzes one backend service, identifies its independent integration
+boundaries, proposes collector instrumentation, verifies the reviewed source,
+and connects each binding to the matching Seamward Integration.
+
+The normal experience starts with one request:
+
+> Set up Seamward in this project.
+
+That is the entire customer prompt. The MCP owns repository analysis, boundary
+and contract discovery, change previews, repository verification, environment
+file safety, and remote status checks. The customer does not name a provider,
+protocol, contract path, setup action, or verification command.
+
+The coding agent handles discovery and setup sequencing. You approve only two
+meaningful trust boundaries:
+
+1. Apply the proposed local dependency, generated file, and source changes.
+2. Connect the reviewed contract to Seamward. This either registers and
+   activates a new version or links an exact already-active version to the
+   reviewed local evidence without a remote write.
+
+The server never reads or edits environment files. It does not return source
+contents, credential values, absolute paths, or customer data.
+
+## Install and configure a client
+
+Use the project installer from one deployable backend service:
+
+```bash
+npx @seamward/setup@alpha
+```
+
+The installer completes browser authorization, stores the short-lived
+credential outside the repository, installs this package at an exact version,
+and adds project-scoped configuration for Claude Code, Cursor, and Codex. It
+previews every project file before applying the changes. Node.js 22 or newer is
+required.
+
+The project root and approved application environment cannot be changed through
+an MCP tool call. Run one setup server per deployable service. Manual stdio configuration
+remains supported for embedded and headless clients, but it is not the default
+customer path.
+
+## What the agent does
+
+The default server exposes five high-level operations:
+
+| Operation              | Effect                                                                |
+| ---------------------- | --------------------------------------------------------------------- |
+| `prepare_setup`        | Read-only analysis and a readable proposal                            |
+| `apply_local_setup`    | One approved local apply and deterministic source verification        |
+| `review_remote_setup`  | Preview Integration create/reuse decisions and exact contract effects |
+| `connect_remote_setup` | Apply the approved Integration and contract lifecycle idempotently    |
+| `check_setup_status`   | Read-only local, contract, and first-observation status               |
+
+Internal plan records remain inside `.seamward/`. A user does not copy setup
+identifiers or protocol confirmation phrases between calls.
+
+If discovery finds clear integration boundaries and contract candidates,
+preparation proceeds automatically for all of them. Each business boundary gets
+its own plan, generated collector binding, runtime Connection key and ingest
+token variable names, contract lifecycle, and first-observation status. Bindings
+that share one application source may use the same token value under their
+separate generated variable names. If a boundary is ambiguous, the tool
+returns readable choices such as `inbound webhooks`, `outbound HTTP API`, `queue
+consumer`, or `scheduled feed`, then waits for the user to choose. Unsupported
+service shapes stop with a manual-setup explanation.
+
+The read-only preparation output includes stable local binding identifiers for
+the coding agent. A reviewer may include or exclude bindings before local
+approval without copying those identifiers. Scripts, tests, fixtures, mocks,
+tools, build output, and provider simulators are excluded from automatic
+service discovery.
+
+Automatic source transformation currently supports outbound Node.js HTTP
+client calls and inbound Node.js webhook handlers. The same one-line prompt can
+discover inbound HTTP servers, queue publishers, queue consumers, and scheduled
+feeds, but preparation stops before approval and gives the manual integration
+path for those boundaries. It never labels discovery-only coverage as an
+automatic setup.
+
+During the local approval, the server installs the exact supported collector,
+writes plan-owned files, applies supported JavaScript or TypeScript source
+instrumentation, runs the project's verification scripts, and records evidence
+that binds the resulting source files to that successful run. The operation
+restores package metadata, lockfiles, generated files, setup state, and source
+files if verification fails. Unsupported or uncertain source shapes stop with
+manual guidance instead of leaving partial edits or asking the coding agent to
+bypass the reviewed plan with separate editing tools.
+
+Verification receives an allowlisted child-process environment with no
+application credentials. The setup engine supplies an internal
+verification-only mode so the generated collector cannot start or transmit an
+observation while existing handler results and errors remain testable. The
+generated collector is also inert when `NODE_ENV=test`, so a project's ordinary
+test suite does not require production credentials or transmit observations.
+The setup engine does not open environment files. Project verification scripts
+still run exactly as the repository defines them, including any file or network
+access those scripts perform. Outside setup verification and test processes, an
+observed operation fails clearly when its Connection key or ingest token is
+missing or invalid, rather than silently running without monitoring.
+
+Repeating the same reviewed setup reuses the verified plan and leaves source
+unchanged. Replanning a contract does not wrap an already observed webhook
+boundary again. Existing collector-backed webhook files are recorded as
+already instrumented rather than wrapped with a second collector.
+
+During the remote approval, the server proposes a readable name and provider for
+every reviewed local binding. It reuses one exact existing Integration when the
+business identity and scope match, otherwise it previews creating a new
+Integration in the approved application environment. The reviewer can edit the
+name and provider or select a preferred existing Integration before applying the
+remote operation. No customer copies an internal Integration ID into a prompt.
+It then connects each exact reviewed OpenAPI contract. When no exact active version
+exists, it registers one immutable draft and activates that version. When the
+active version already matches, it links the existing version without a remote
+write. Identical retries reconcile safely. An ambiguous mapping stops before
+any remote change and asks the user to choose in plain language.
+
+An exact Integration command remains available as compatibility mode. The
+normal source-scoped authorization lets the setup API create or reuse reviewed
+Integrations without broad workspace write access.
+
+JSON Schema requires an explicit operation binding. Automatic setup reports
+that limitation before local approval and routes the user to the manual CLI
+contract workflow, where the binding can be reviewed explicitly.
+
+## Authorization and runtime configuration
+
+The project installer uses OAuth with PKCE and binds its grant to one user,
+workspace, and one application environment source. Access tokens are short-lived and refresh only
+while the grant remains active. The credential file is stored in the user's
+configuration directory with owner-only permissions. The MCP receives a
+credential reference, not the token value.
+
+The installer and MCP never open `.env` files, and no MCP operation accepts a
+credential value. A workspace API key and process environment remain available
+only as an advanced compatibility path for headless automation.
+
+Runtime observation delivery is a separate boundary. The deployed service
+needs every binding's public Connection key and its source ingest token in the
+generated secret-environment variable names. The setup MCP does not read,
+write, or manage those entries.
+
+Package installation receives a reduced environment that excludes Seamward and
+common credential variables. Project verification receives a strict allowlist
+of operating-system process variables plus the internal verification flag.
+Credentials are never printed in tool output.
+
+## Status and recovery
+
+`check_setup_status` is read-only. It reports one of these states:
+
+| State                    | Meaning                                                              |
+| ------------------------ | -------------------------------------------------------------------- |
+| `not_prepared`           | Run setup preparation                                                |
+| `local_changes_required` | Apply or finish the proposed source changes                          |
+| `ready_to_connect`       | Local verification passed; review or reconcile the remote connection |
+| `waiting_for_traffic`    | Current contract evidence is active; send an instrumented request    |
+| `partially_connected`    | At least one binding is connected while another still needs action   |
+| `connected`              | Seamward accepted traffic from this setup                            |
+| `stale`                  | Verified source changed; review and apply local setup again          |
+| `conflict`               | Local or remote state changed and needs a fresh review               |
+
+A failed remote connection can be retried through the same approved operation.
+If draft registration succeeded before activation failed, the retry uses the
+recorded draft instead of creating another one.
+
+For a multi-Integration connection, each binding reports its own outcome. If a
+remote service failure interrupts the batch, completed bindings stay recorded,
+the failed binding reports its stable error code, and later bindings report
+`not_attempted`. Retrying the same approved operation reconciles completed
+work instead of creating duplicate contract versions.
+
+An interrupted exact-active reconciliation is also safe to retry. If local
+registration evidence was recorded before local activation evidence, the retry
+revalidates the current source, contract, setup state, and active version, then
+converges without a remote mutation. `waiting_for_traffic` is reported only
+when current source evidence is verified and the locally recorded activation
+still matches Seamward's active version.
+
+Multi-binding plans are loaded from `.seamward/integrations/` when the MCP
+process restarts. Status therefore reports every prepared binding rather than
+falling back to `not_prepared` after the coding agent is reopened.
+
+If an Integration boundary is removed from the source, the next setup preview
+lists that binding as a removal. Seamward snapshots current and retired binding
+files together, applies the reviewed changes, removes only unchanged generated
+files and local state that it owns, then verifies the final project tree. Any
+failure restores the full snapshot. The remote Integration and contract stay
+active deliberately so deleting local source cannot silently destroy remote
+evidence. A customer can retire the remote Integration separately after
+reviewing its retention requirements.
+
+## Error contract
+
+Every failed operation returns `schemaVersion` plus an `error` object with
+`code`, `message`, `retryable`, and `recovery`. `retryable: true` means the same
+request may succeed after waiting or restoring network health. It never means
+that an agent may bypass a fresh review when local or remote state changed.
+
+| Code                           | Retryable | Recovery                                                                                                |
+| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------- |
+| `plan_not_found`               | No        | Run `prepare_setup`                                                                                     |
+| `legacy_plan_requires_replan`  | No        | Run `prepare_setup` and review the replacement plan                                                     |
+| `confirmation_required`        | No        | Approve the requested trust boundary                                                                    |
+| `no_matching_actions`          | No        | Prepare again and choose a proposed operation                                                           |
+| `invalid_input`                | No        | Correct the request to match the tool schema                                                            |
+| `scan_limit_exceeded`          | No        | Narrow the service root, then prepare again                                                             |
+| `generated_file_conflict`      | No        | Review the changed generated file before preparing again                                                |
+| `apply_in_progress`            | Yes       | Wait for the active local apply, then retry                                                             |
+| `setup_preview_stale`          | No        | Run `review_remote_setup` again and approve the current Integration preview                             |
+| `idempotency_conflict`         | No        | Use the original request for that key, or review again before applying a different request              |
+| `verification_failed`          | No        | Fix the source or project checks, then prepare and apply again                                          |
+| `setup_state_conflict`         | No        | Check status, then prepare and review current state                                                     |
+| `stale_setup_lock`             | No        | Confirm no apply is running, remove only the reported lock, then prepare                                |
+| `configuration_required`       | No        | Run `npx @seamward/setup@alpha` to authorize the application environment, then restart the coding agent |
+| `contract_preview_expired`     | No        | Run `review_remote_setup` again                                                                         |
+| `contract_activation_conflict` | No        | Read contract state and run `review_remote_setup` again                                                 |
+| `authentication_required`      | No        | Run `npx @seamward/setup@alpha` and approve the application environment again                           |
+| `insufficient_scope`           | No        | Reauthorize the application environment with `npx @seamward/setup@alpha`, then restart the coding agent |
+| `integration_scope_mismatch`   | No        | Choose the correct boundary and prepare again                                                           |
+| `integration_mapping_required` | No        | Select the matching existing Integration or adjust the proposal, then review again                      |
+| `contract_version_conflict`    | No        | Choose a new version or review the existing immutable version                                           |
+| `source_verification_required` | No        | Run `apply_local_setup` and resolve source verification                                                 |
+| `not_found`                    | No        | Verify workspace and Integration access, then review again                                              |
+| `remote_conflict`              | No        | Read remote state and run `review_remote_setup` again                                                   |
+| `rate_limited`                 | Yes       | Wait for the retry interval, then repeat the same request                                               |
+| `service_unavailable`          | Yes       | Wait for service recovery, then repeat the same request                                                 |
+| `remote_request_failed`        | No        | Verify the request and access configuration, then review again                                          |
+| `remote_response_invalid`      | No        | Report the invalid service response before trying again                                                 |
+| `plan_conflict`                | No        | Run `prepare_setup` and review the current plan                                                         |
+| `internal_error`               | No        | Inspect local logs and report the failure                                                               |
+
+Older alpha setup state is migrated only during an approved local apply. If an
+existing generated target cannot be proven safe, migration stops without
+overwriting it.
+
+## Privacy and trust boundaries
+
+- Repository analysis is local and read-only.
+- Environment files are neither read nor changed.
+- Source contents, literal private URLs, credentials, and absolute paths are
+  not returned from operations.
+- Current-file evidence is stored locally in `.seamward/setup-state.json`.
+- Editing a verified source file makes its evidence stale.
+- Seamward Cloud receives only an explicitly registered contract and redacted
+  collector observations. Exact-active reconciliation changes local evidence
+  only and creates no remote audit event.
+- The local and remote writes remain distinct host approval boundaries.
+
+## CLI fallback
+
+`@seamward/cli` uses the same discovery, planning, verification, and remote API
+implementation. Use the CLI for terminal automation and CI when a coding agent
+cannot run a local MCP server. The CLI is an advanced interface; the MCP is the
+recommended interactive setup experience.
+
+## Compatibility
+
+The default stdio server publishes setup schema `seamward.setup-mcp/4` and only
+the five high-level operations above. The legacy alpha registry is supported
+through `@seamward/setup-mcp` 0.1.x for migration only. Applications embedding
+the package can enable it with `legacyTools: true` while they move to the
+high-level operations and per-Integration state under
+`.seamward/integrations/`. The legacy registry will be removed in the first
+`0.2.0` release. It is not the default and must not be presented to new users.