@bicon/mcp-composer 0.3.6 → 0.5.0

package/README.md

@@ -24,9 +24,9 @@ via API keys is a separate, security-reviewed phase.
 | Name | What it does |
 |---|---|
 | resource `initiative://schema` / tool `get_initiative_schema` | The field catalog: required fields, enum values, the four dimensions with their named sub-dimensions (EN/DE labels + help text, plus the wording the app uses in digital / innovation portfolios), the exact shape of every optional section, the EU-AI-Act vocabularies, and the handoff steps. **Read this first.** |
-| `assemble_initiative` | Compact spec (metadata + named sub-ratings 0–100 + confidence per dimension + optional sections, optionally the organisation's `context`) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints the initiative id and every nested row id (decision-log entries, status reports, incidents — a client never invents ids), **derives** the four dimension scores (the app's own scoring function), accepts dates as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd, returns `{ok, initiative, derivedScores, warnings, errors, contextId}`. Pass `id` (an existing initiative's) only to **update** that initiative. |
+| `assemble_initiative` | Compact spec (metadata + named sub-ratings 0–100 + confidence per dimension + optional sections, optionally the organisation's `context`) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints the initiative id and every nested row id (decision-log entries, status reports, milestones, incidents — a client never invents ids), **derives** the four dimension scores (the app's own scoring function), accepts dates as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd, returns `{ok, initiative, derivedScores, warnings, errors, contextId}`. Pass `id` (an existing initiative's) only to **update** that initiative. |
 | `export_initiative_file` | Takes the **same compact spec**, assembles it and wraps the result in the app's single-initiative JSON envelope; returns `{ok, filename, json, importInstructions, derivedScores, warnings}`. There is one pipeline — a hand-edited initiative object is not an input, so client-supplied scores or unknown keys can never bypass assembly. |
-| `read_portfolio_context` | Takes the organisation's **portfolio-context file** (see below) and returns the interview plan for that organisation — its own labels, help texts and rating notes per sub-dimension, which sub-dimensions are switched off, its business units, categories, tags, skills (id + name) and non-archived initiatives (id + name), currency, discount rate, whether the EU-AI-Act module is on — plus a short **contextId** that stands in for the file in the two other tools. |
+| `read_portfolio_context` | Takes the organisation's **portfolio-context file** (see below) and returns the interview plan for that organisation — its own labels, help texts and rating notes per sub-dimension, which sub-dimensions are switched off, its business units, categories, tags, skills (id + name), non-archived initiatives (id + name) and the capability map's capabilities (id, name, domain, importance, current → target maturity; context version 2), currency, discount rate, whether the EU-AI-Act module is on — plus a short **contextId** that stands in for the file in the two other tools. |
 | `composer_version` | Returns `{composerVersion, capabilities}`. Every *successful* tool result also carries `composerVersion`. |
 
 ### The portfolio context — how the Composer learns an organisation's settings
@@ -56,8 +56,11 @@ naming the fix, never a wrong answer. Effects:
 - `businessUnit` and `aiCategory` **must be on the organisation's lists** (no
   inventing — matched case-insensitively and normalised to the organisation's
   spelling; new ones are created in the app's Settings); `dependsOn`,
-  `requiredSkills[].skillId` and an update `id` must be ids that exist (any
-  id format; Retired initiatives count, archived ones do not);
+  `requiredSkills[].skillId`, `capabilityImpacts[].capabilityId` and an update
+  `id` must be ids that exist (any id format; Retired initiatives count,
+  archived ones do not; a capability, never a domain). A version-1 context
+  file (before 2026-10-15) carries no capabilities: links are refused with a
+  request to download the file again rather than guessed at;
 - ratings must be on the organisation's **slider step** (Settings › Slider
   granularity: 5, 10, 20 or 25) — the plan states it, a value off the grid is
   rejected with the step in the message (files exported before 2026-08-21
@@ -90,7 +93,7 @@ vocabularies (`aiActVocabularies` in the descriptor; the app drops unknown
 obligation keys and never shows unknown artifact keys), the score derivation —
 is checked in the assembler, which reports **all** problems of a call at once
 with the allowed values in the message (id shapes included). Row ids of
-decision-log entries, status reports and incidents are minted by the
+decision-log entries, status reports, milestones and incidents are minted by the
 Composer — a client-supplied UUID is kept, anything else replaced — because
 the app keys those rows per initiative and a re-used id from another
 initiative is exactly what collided on import once.
@@ -228,21 +231,80 @@ card imports. Requires `python3` for the zip container.
 
 ## Publishing (maintainers)
 
-Release = extension + npm together, from one version:
+Release = extension + npm together, from one version, done by two GitHub
+Actions workflows (`docs/composer-release-ci-concept-2026-10-16.md`):
+
+1. **Bump** — Actions → *Composer bump* → Run workflow on `dev` with
+   `patch | minor | major` (the button exists once `main` carries the workflow
+   file; GitHub lists only default-branch workflows). It runs
+   `npm version` (package.json is the ONLY place the version is written), the
+   package tests, `build:mcpb` (bundles, ship-gate smoke, writes the `.mcpb`
+   and `composer-extension.json` into the web app) and the app's
+   `composer-download.test.ts`, then pushes `composer/vX.Y.Z` with those three
+   files. Open its PR into `dev` yourself (the run summary links the compare
+   page); a PR opened by the Actions token would get no CI.
+2. **Merge** the bump PR into `dev`, then release `dev → main` as usual.
+3. **Publish** — on the push to `main`, *Composer publish* compares
+   package.json with the registry; when it is newer, it runs the package tests,
+   `check:mcpb` (rebuilds and proves the served download is the build of this
+   source), `npm publish` via npm trusted publishing (GitHub OIDC, no token in
+   the repo; provenance comes with it once the repository is public) and
+   `publish-smoke.mjs`, which fetches
+   `npx -y @bicon/mcp-composer@<version>` from the registry and requires
+   `initialize` and `composer_version` to answer with the new version.
+
+One-time setting on npmjs.com (package → Settings → Trusted publisher):
+GitHub Actions, repository `volkmarritter/ai-portfolio-steering-saas`,
+workflow `composer-publish.yml`. If the form asks which actions the publisher
+may take, allow direct `npm publish` (the workflow does not stage releases).
+`package.json` names the same repository in `repository.url`, which npm
+compares with the one the workflow runs in. A manual run of *Composer publish* is a
+`--dry-run` unless the box is unticked, and a real publish runs only from
+`main`.
+
+`check:mcpb` compares the served download with a fresh build byte for byte,
+so any change that alters the bundle after the last bump (Composer source, a
+bump of the MCP SDK or zod in the lockfile) makes the publish fail until the
+next *Composer bump* rebuilds the download. CI runs the same gate on every PR
+into `main` (`npm view` against the registry, as the publish does): a version
+ahead of the registry runs `check:mcpb`, so a release that bumps it shows a
+stale download before the merge (run *Composer bump* once more, merge it into
+`dev`, and the release PR goes green); a version behind the registry is red as
+the publish would be; a version the registry already has skips the check, and a
+PR that changes the served `.mcpb` or `composer-extension.json` at such a
+version is red (npm cannot take that version again, so the download and the npm
+package would differ): bump instead. So a green release PR means the publish on
+`main` either skips or is the build of the source `main` carries.
+
+When *Composer publish* is red on `main`, read the run: "behind" or a drift
+failure mean bump again and release; "npm view failed" or "not a plain semver"
+come from reading the registry, so re-run the failed job once the registry
+answers (a bump does not help); a failed `npm publish` step itself (npm
+outage, trusted publisher not yet configured on npmjs.com) is re-run from the
+failed run ("Re-run failed jobs", same commit, the gate evaluates again) or by
+dispatching *Composer publish* from `main` with `dry_run` unticked. Nothing
+re-triggers it on its own, since later releases without a bump do not change
+`package.json`. *Composer bump* runs from `dev` only. A run that fails with "branch composer/vX.Y.Z
+already exists" met an earlier bump to the same version whose PR is still open
+or was closed without merging: merge it, or delete that branch and run again.
+
+Fallback by hand, if Actions is down:
 
 ```bash
 cd lib/integrations/mcp
-npm version patch|minor      # bumps package.json — the ONLY place the version is written
-pnpm run test                # incl. the SDK-boundary suite
-pnpm run build:mcpb          # bundles, ship-gate smoke, copies the .mcpb + version JSON into the web app
+npm version patch|minor --no-git-tag-version
+pnpm run test
+pnpm run build:mcpb
 npm login                    # once, as the BICon npm account (business identity, 2FA on)
 npm publish                  # prepack builds; publishConfig.access is public
+node publish-smoke.mjs <version>  # fetches from the registry in an empty temp dir
 ```
 
-Then commit (the `.mcpb` and `composer-extension.json` are part of the
-release commit) and verify from a clean machine:
-`npx -y @bicon/mcp-composer@latest` starts and `composer_version` reports the
-new version. The bundle inlines `zod`, `@workspace/api-zod` and
+Then commit package.json, the `.mcpb` and `composer-extension.json` together.
+When that version later reaches `main`, *Composer publish* sees it on the
+registry and skips; a hand-published version higher than `main` carries makes
+the workflow fail ("behind") until a bump at least as high lands.
+The bundle inlines `zod`, `@workspace/api-zod` and
 `@workspace/initiative-model` (workspace-only packages the registry cannot
 resolve), so what ships is `dist/index.mjs` + this README with
 `@modelcontextprotocol/sdk` as the sole runtime dependency —