@bicon/mcp-composer 0.9.0 → 0.12.0

package/README.md

@@ -28,6 +28,14 @@ via API keys is a separate, security-reviewed phase.
 | `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), 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`. |
+| `load_portfolio` | Reads the organisation's **full backup** (Import/Export → Backup → Export, a `bicon-portfolio-backup-YYYY-MM-DD.json`, format version 10 or newer) from a local `path` (inline `backup` JSON only for small files), runs it through the app's own sanitiser, strips author fields, and returns a short **portfolioId** plus a summary (counts by status, business unit and driver, skills, capabilities, saved portfolios, snapshots, currency, budget cap, export date). |
+| `query_initiatives` | Filters the loaded portfolio (status, business unit, category, driver, tags, saved portfolio, capability, skill, score ranges, overdue milestones / follow-ups, severe risks) and returns chosen columns, sorted, plus aggregates over the whole scope. At most 200 rows per call. |
+| `portfolio_readings` | Computes portfolio readings with the app's own libs: KPIs, concentration bars and HHI, the seven operating-model readings, capability impact, the risk register, early-warning signals and Board Actions. |
+| `rank_initiatives` | Runs the Prioritisation ranking and cut line (the organisation's rule book, budget envelope, exclusions and skill caps), with what-if inputs: cap, budget field, trade-off percent, skill FTE deltas, promoted / excluded ids, queue statuses, regulatory-first switch. |
+| `initiative_detail` | One initiative in full (by id, externalId or name), with its derived bucket, risks, milestones, follow-ups, status reports, decision log and links. |
+| `compare_snapshots` | The backup's state ("now") against a snapshot, or two snapshots; without `from`, the newest snapshot before `to`: the four Steering KPIs with direction, counts by status, budget sum, initiatives added, left (retired, archived, deleted, out of the filter) or changed (status, scores beyond a threshold, budget, driver, business unit), and how the risk register moved. Initiatives match by id, else by a unique name. |
+| `board_slices` | The data of the Board Memo's chapters from the functions the memo and pack use: KPIs since the baseline snapshot, capacity (cut line, parked by reason, must-do block), milestones (missed, next 90 days), risks (heat map, top severe, issues and rises since the baseline), capability impact. Raw values, for the assistant to write a memo section, a committee note or slides. |
+| `skill_allocation` | Per skill (all, or the ones named): FTE cap against pipeline demand, run FTE of systems in production and the baseline cut line's funded use; every initiative drawing on it (FTE, build or run, funded or parked and why: budget, a skill cap, a dependency, excluded); the Roadmap's monthly demand (24 months by default, up to 48; run teams open-ended only with `includeRunTeams`, off by default as on the page) with the months over cap and who makes up the peak; what-ifs with FTE deltas or excluded initiatives. |
 
 ### The portfolio context — how the Composer learns an organisation's settings
 
@@ -82,7 +90,7 @@ 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, dates
+(`aiAct: Unrecognized key: "literacy"`), enum values, dates
 (dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd — real calendar dates, normalised to
 yyyy-mm-dd) and blank names are caught with field paths, and the advertised JSON Schema
 (`additionalProperties: false`, no `$ref` pointers) means what it says. A
@@ -134,6 +142,28 @@ pins the keys to the contract in both directions. `server.test.ts` drives the re
 the real SDK client over an in-memory transport, so what is asserted is what a
 client sees.
 
+## Portfolio analysis — read-only, from the backup
+
+The analysis tools answer questions the app's pages do not ask directly
+("which Pilot initiatives in Finance lack a risk owner?", "what drops below the
+cut line if the budget shrinks 15 %?"). They compute with the same rules the
+app uses: the analysis libs live in `@workspace/initiative-model` and both the
+app and this server import them, so a number here matches the page.
+
+- **Input is the full backup file**, read from disk. Nothing is fetched,
+  nothing is sent anywhere by the server, and no credentials are involved.
+- **Privacy:** the AI client sees what the tools return, i.e. the portfolio's
+  data. Load a backup only into a client your organisation allows for that
+  data. The app's author stamps (`createdBy`, `updatedBy`, `recordedBy`,
+  `scoredBy`, `checkedBy`) are removed on load; names typed into the data
+  stay (risk owners, follow-up assignee names, status-report authors,
+  decision owners). Member ids are not returned.
+- **Size limits:** at most 200 rows per call and about 60 KB per answer; a
+  larger result is cut (rows first, then long texts and lists) and says so.
+- **Freshness:** the data is as of the backup's export date, which every
+  summary states. Export a new backup to analyse newer data.
+- Loaded portfolios live in memory for the session only.
+
 ## Install for users
 
 ### Claude Desktop — the extension (recommended, no Node needed)
@@ -316,7 +346,7 @@ resolve), so what ships is `dist/index.mjs` + this README with
 
 ## 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
+No authentication, no live `POST /initiatives`, no live read of the API (the
+analysis tools read a backup file instead), 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.