@bicon/mcp-composer 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# BICon Initiative Composer (MCP server)
+
+An [MCP](https://modelcontextprotocol.io) server that helps an AI client — e.g.
+Claude Desktop — set up a portfolio initiative conversationally. Creating an
+initiative by hand means filling ~15 metadata fields **and rating 30
+sub-dimensions across four scoring dimensions** (plus optional economics and a
+large EU-AI-Act block); this server lets an assistant run that interview and
+produce a complete, valid initiative.
+
+## Draft-first by design — no auth, no API calls
+
+The server holds **no credentials and never talks to the BICon API**. Its tools
+assemble and validate an initiative and hand back an **import file**; you load
+that file through the app's existing, authenticated import UI. The
+"Add as new → Confirm" step in the app is the human-in-the-loop — nothing
+reaches your organisation until you confirm it in the browser.
+
+Why: the API only accepts short-lived browser session tokens (there is no API
+key), and a draft-first flow adds zero new attack surface. Live create/update
+via API keys is a separate, security-reviewed phase.
+
+## Tools & resource
+
+| 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:
+
+```json
+{
+  "mcpServers": {
+    "bicon-composer": {
+      "command": "npx",
+      "args": ["-y", "@bicon/mcp-composer"]
+    }
+  }
+}
+```
+
+That's the whole install. `npx -y` fetches (and caches) the published version;
+no repository, no terminal work.
+
+## 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)
+```
+
+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.
+
+## 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**.
+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):
+
+```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
+```
+
+Then verify from a clean machine: `npx -y @bicon/mcp-composer` should start
+(it waits for stdio input; Ctrl-C to exit).
+
+## Not in scope (Phase 2)
+
+No authentication, no live `POST /initiatives`, no read/list/update tools, no
+hosted/HTTP transport. Those require an API-key auth path in the API server that
+doesn't exist yet — deliberately deferred to a separate, security-reviewed
+phase after the production Clerk split.