@bicon/mcp-composer 0.1.0 → 0.1.7

package/README.md

@@ -23,110 +23,175 @@ 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), confidence scale, optional sections, and the handoff steps. **Read this first.** |
-| `assemble_initiative` | Compact spec (metadata + named sub-ratings 0–100 + confidence per dimension) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints id/timestamps, **derives** the four dimension scores (mean of subs, like the app), returns `{ok, initiative, derivedScores, warnings, errors}` with precise per-field errors. |
-| `export_initiative_file` | Wraps an assembled initiative in the app's single-initiative JSON envelope; returns `{filename, json, importInstructions, derivedScores}`. |
-
-The score derivation is a test-pinned copy of the app's `scoring.ts`
-(golden test against the "Advisor Copilot" demo seed → 77 / 61 / 73 / 90),
-and a catalog-drift test fails the build if the OpenAPI contract's enums or
-sub-dimension keys change without a catalog update.
-
-## Install for users (no clone, no build)
-
-The package is published to npm as `@bicon/mcp-composer` — a single
-self-contained bundle whose only runtime dependency is the MCP SDK. Any user
-with Node ≥ 20 adds this to Claude Desktop's `claude_desktop_config.json`
-(Settings → Developer → Edit Config) and restarts:
+| 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) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints id/timestamps, **derives** the four dimension scores (the app's own scoring function), returns `{ok, initiative, derivedScores, warnings, errors}`. |
+| `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. |
+| `composer_version` | Returns `{composerVersion, capabilities}`. Every *successful* tool result also carries `composerVersion`. |
+
+### How validation works (and why it lives at the wire)
+
+The MCP SDK validates every call with the registered schema **and hands the
+handler the parsed value** — whatever the schema strips, the server never sees.
+So the spec schema is registered as a full **strict** object, with every
+optional section a **deep-strict copy of the API contract**: an unknown key
+anywhere is rejected by the SDK with its exact path
+(`Unrecognized key(s) in object: 'literacy' at aiAct`), enum values, date
+formats (`YYYY-MM-DD`, real calendar dates), blank names and non-UUID ids are
+caught with field paths, and the advertised JSON Schema
+(`additionalProperties: false`, no `$ref` pointers) means what it says. A
+section may also be sent as a **JSON string** (clients working from a stale
+tool descriptor did that); it is parsed and validated identically. What a JSON
+Schema cannot express — the 30 named ratings, the AI-Act controlled
+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.
+
+Errors the SDK raises before a handler runs (`Input validation error: …`) carry
+no `composerVersion` — that is normal. A *successful* result without it means an
+old build is answering (see next section).
+
+### Stale instances (reinstall is not enough — quit the app)
+
+Claude Desktop runs an extension in **two** places: a chat-UI instance, which
+every reinstall restarts, and a session-facing instance
+(`LocalMcpServerManager` in Desktop's `main.log`) that serves Claude Code,
+Cowork and remote claude.ai chats reaching the device. The session-facing
+instance is started once at app launch and is only replaced on a **full app
+quit** — reinstalling or disabling/enabling the extension leaves it running
+the old code. Observed on 2026-08-18: five reinstalls, the chat-UI copy was
+current every time, and every session still got the original build.
+
+Tell: a successful tool result without `composerVersion`, or
+`composer_version` missing from the tool list. Fix: install the new `.mcpb`,
+then **quit Claude Desktop completely** (tray icon → Quit — closing the window
+is not enough), reopen, and check with `composer_version`.
+
+### One source for the domain
+
+The Composer imports the app's own domain leaf, `@workspace/initiative-model`
+(types and value lists incl. the AI-Act vocabularies, the score derivation, the
+portfolio-mode wording overlays, the backup-format version) — the same package
+the web app renders and validates with — and derives its enum lists from the
+generated API contract. The only hand-listed part is the 30 sub-dimension keys
+with the app's base wording; `catalog-drift.test.ts` pins them to the
+contract in both directions. `server.test.ts` drives the real server through
+the real SDK client over an in-memory transport, so what is asserted is what a
+client sees.
+
+## Install for users
+
+### Claude Desktop — the extension (recommended, no Node needed)
+
+Download **`bicon-composer.mcpb`** from the BICon app (Import/Export → *Set
+up initiatives with an AI assistant*, or directly at
+`https://www.bicon.digital/downloads/bicon-composer.mcpb`) and open it —
+double-click, or Claude Desktop → Settings → Extensions → Install. Claude
+Desktop runs the server on its own built-in Node runtime, so there is nothing
+else to install and no configuration file to edit. Then **quit Claude Desktop
+completely and reopen** (see *Stale instances*), start a **new chat** and ask:
+*"Use the BICon Initiative Composer to help me set up a new initiative."*
+
+Why the extension is primary: current Claude Desktop builds manage local MCP
+servers as Desktop Extensions and treat `claude_desktop_config.json` as their
+own preferences store — a hand-pasted `mcpServers` block there is silently
+overwritten. There is no supported config-file route for Claude Desktop.
+
+### Other MCP clients — the npm package
+
+`@bicon/mcp-composer` on npm is a single self-contained bundle whose only
+runtime dependency is the MCP SDK. Any MCP-capable client with Node ≥ 20 can
+run it; for a client that reads a `mcpServers` config, add this and restart
+the client:
 
 ```json
 {
   "mcpServers": {
     "bicon-composer": {
       "command": "npx",
-      "args": ["-y", "@bicon/mcp-composer"]
+      "args": ["-y", "@bicon/mcp-composer@latest"]
     }
   }
 }
 ```
 
-That's the whole install. `npx -y` fetches (and caches) the published version;
-no repository, no terminal work.
+`@latest` matters: an unpinned `npx` spec keeps serving whatever it cached
+first. Check what you got with the `composer_version` tool — the registry
+version and the extension version are released together (see *Publishing*);
+if npm is behind, use the extension.
+
+**Prerequisite:** Node.js ≥ 20 on the **same operating system as the client**.
+On Windows with Node only inside WSL, launch the server *through* WSL:
+`"command": "wsl.exe", "args": ["-d", "Ubuntu", "--", "/path/to/npx", "-y",
+"@bicon/mcp-composer@latest"]` (replace `/path/to/npx` with the output of
+`which npx` in WSL). Restart the client afterwards.
 
 ## Build & run from source (contributors)
 
 ```bash
-pnpm --filter @bicon/mcp-composer run build   # → dist/index.mjs (single ESM bundle)
-pnpm --filter @bicon/mcp-composer run test    # vitest
-node lib/integrations/mcp/dist/index.mjs      # stdio server (used by the client, not by hand)
+pnpm --filter @bicon/mcp-composer run build        # → dist/index.mjs (npm bundle) + dist/mcpb/composer-<v>.mjs (extension bundle)
+pnpm --filter @bicon/mcp-composer run test         # vitest, incl. the SDK-boundary suite (builds the bundles itself)
+pnpm --filter @bicon/mcp-composer run build:mcpb   # → dist/bicon-composer.mcpb, copied to the web app's public/downloads
+node lib/integrations/mcp/dist/index.mjs           # stdio server (used by a client, not by hand)
 ```
 
-Point Claude Desktop at the local build with the **absolute path**:
-
-```json
-{
-  "mcpServers": {
-    "bicon-composer": {
-      "command": "node",
-      "args": ["/ABSOLUTE/PATH/TO/lib/integrations/mcp/dist/index.mjs"]
-    }
-  }
-}
-```
-
-On Windows with the repo in WSL, run the server **inside WSL** so it sees the
-Linux `node`:
-
-```json
-{
-  "mcpServers": {
-    "bicon-composer": {
-      "command": "wsl.exe",
-      "args": ["-d", "Ubuntu", "--", "/home/<user>/.nvm/versions/node/<version>/bin/node",
-               "/home/<user>/projects/ai-portfolio-steering/lib/integrations/mcp/dist/index.mjs"]
-    }
-  }
-}
-```
-
-Restart Claude Desktop; the tools appear under the tools menu.
+For a client that reads a `mcpServers` config, point it at the local build
+with an absolute path (`"command": "node", "args": ["/ABSOLUTE/PATH/TO/lib/integrations/mcp/dist/index.mjs"]`;
+on Windows with the repo in WSL, run through `wsl.exe` with the WSL `node`).
+For Claude Desktop, build and install the extension instead.
+
+`build:mcpb` stages the manifest (version, entry point and launch args written
+from `package.json` — the checked-in `mcpb/manifest.json` carries
+placeholders), adds the single self-contained bundle, and — before zipping —
+boots the staged server and drives it through the protocol: `initialize`
+(version), `tools/list` (four tools, no `$ref`), `composer_version`,
+`resources/list`, and an `assemble_initiative` call with an unknown AI-Act key
+that must be rejected by name. It then copies the `.mcpb` to
+`artifacts/bicon-portfolio/public/downloads/` and writes
+`src/lib/composer-extension.json` (version + path), which the Import/Export
+card imports. Requires `python3` for the zip container.
 
 ## Using it (the interview → import flow)
 
 1. Ask Claude: *"Help me set up a new initiative in BICon."* It reads
    `initiative://schema` and interviews you — metadata first, then the 30
-   sub-dimensions with the app's own help text, then a confidence per dimension.
-2. Claude calls `assemble_initiative` and shows you the **derived scores** as a
-   sanity check (fix and re-run if anything looks off).
-3. Claude calls `export_initiative_file` → save the returned JSON under the
-   suggested filename (`initiative-<name>-<date>.json`).
-4. In the app (signed in to the target organisation): **Import/Export →
-   Single initiative** card → drop the file → the preview should show
-   **0 warnings** → **Add as new** → **Confirm**.
+   sub-dimensions with the app's own help text (ask which portfolio mode you
+   work in; digital and innovation portfolios use different wording for some
+   of them), then a confidence per dimension.
+2. Claude calls `assemble_initiative` and shows you the **derived scores** and
+   any warnings as a sanity check (fix and re-run if anything looks off).
+3. Claude calls `export_initiative_file` with the same spec → save the returned
+   JSON under the suggested filename (`initiative-<name>-<date>.json`).
+4. In the app (signed in to the target organisation): if the initiative carries
+   EU-AI-Act data, make sure the portfolio is in **AI mode** (the app strips
+   AI-Act fields on import when it is not — the file's `sourceMode` is
+   informational and cannot override that). Then **Import/Export → Single
+   initiative** card → drop the file → the preview should show **0 warnings**
+   → **Add as new** → **Confirm**.
 5. The initiative appears in the Inventory with exactly the scores Claude
    reported.
 
-`sourceMode` (default `ai`) must match the target portfolio's mode, otherwise the
-importer strips the AI-Act fields.
-
 ## Publishing (maintainers)
 
-The bundle inlines `zod` and `@workspace/api-zod` (a workspace-only
-devDependency the registry cannot resolve), so what ships is
-`dist/index.mjs` + this README with `@modelcontextprotocol/sdk` as the sole
-runtime dependency — `publish-shape.test.ts` guards exactly that. Publish under
-the BICon npm account (business identity, 2FA on):
+Release = extension + npm together, from one version:
 
 ```bash
 cd lib/integrations/mcp
-pnpm run pack:check          # builds, then `npm pack --dry-run` — inspect the file list
-npm login                    # once, as the BICon npm account
-npm version patch|minor      # bumps package.json version + creates a git tag
-npm publish                  # prepack runs the build; publishConfig.access is public
+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 login                    # once, as the BICon npm account (business identity, 2FA on)
+npm publish                  # prepack builds; publishConfig.access is public
 ```
 
-Then verify from a clean machine: `npx -y @bicon/mcp-composer` should start
-(it waits for stdio input; Ctrl-C to exit).
+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
+`@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 —
+`publish-shape.test.ts` guards exactly that.
 
 ## Not in scope (Phase 2)