@bicon/mcp-composer 0.3.1 → 0.3.4

package/README.md

@@ -58,6 +58,10 @@ naming the fix, never a wrong answer. Effects:
   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);
+- 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
+  carry no step and are not checked);
 - every EU-AI-Act field the app strips is warned about while the
   organisation's AI-Act module is off; the export file defaults to the
   context's mode and language; a file newer than the Composer knows is flagged.

package/dist/index.mjs

@@ -12,7 +12,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/version.ts
-var COMPOSER_VERSION = true ? "0.3.1" : readPackageVersion();
+var COMPOSER_VERSION = true ? "0.3.4" : readPackageVersion();
 
 // ../../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports = {};
@@ -4193,6 +4193,7 @@ var ListSnapshotsResponseItem = objectType({
   "initiatives": arrayType(objectType({
     "id": stringType(),
     "name": stringType(),
+    "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
     "businessUnit": stringType(),
     "owner": stringType(),
     "description": stringType(),
@@ -4445,6 +4446,7 @@ var CreateSnapshotBody = objectType({
   "initiatives": arrayType(objectType({
     "id": stringType(),
     "name": stringType(),
+    "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
     "businessUnit": stringType(),
     "owner": stringType(),
     "description": stringType(),
@@ -4702,6 +4704,7 @@ var RenameSnapshotResponse = objectType({
   "initiatives": arrayType(objectType({
     "id": stringType(),
     "name": stringType(),
+    "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
     "businessUnit": stringType(),
     "owner": stringType(),
     "description": stringType(),
@@ -4950,6 +4953,7 @@ var DeleteSnapshotParams = objectType({
 var ListInitiativesResponseItem = objectType({
   "id": stringType(),
   "name": stringType(),
+  "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
   "businessUnit": stringType(),
   "owner": stringType(),
   "description": stringType(),
@@ -5194,6 +5198,7 @@ var ListInitiativesResponse = arrayType(ListInitiativesResponseItem);
 var CreateInitiativeBody = objectType({
   "id": stringType(),
   "name": stringType(),
+  "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
   "businessUnit": stringType(),
   "owner": stringType(),
   "description": stringType(),
@@ -5446,6 +5451,7 @@ var GetInitiativeParams = objectType({
 var GetInitiativeResponse = objectType({
   "id": stringType(),
   "name": stringType(),
+  "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
   "businessUnit": stringType(),
   "owner": stringType(),
   "description": stringType(),
@@ -5692,6 +5698,7 @@ var UpdateInitiativeParams = objectType({
 var UpdateInitiativeBody = objectType({
   "id": stringType(),
   "name": stringType(),
+  "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
   "businessUnit": stringType(),
   "owner": stringType(),
   "description": stringType(),
@@ -5941,6 +5948,7 @@ var UpdateInitiativeBody = objectType({
 var UpdateInitiativeResponse = objectType({
   "id": stringType(),
   "name": stringType(),
+  "externalId": stringType().optional().describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026)"),
   "businessUnit": stringType(),
   "owner": stringType(),
   "description": stringType(),
@@ -8602,6 +8610,13 @@ var REQUIRED_FIELDS = [
 ];
 var OPTIONAL_SECTIONS = [
   { key: "tags", hint: { en: "Free-text tags", de: "Freie Schlagworte" } },
+  {
+    key: "externalId",
+    hint: {
+      en: "The organisation's own initiative reference (project number, Jira key, IC id) \u2014 the app's 'Initiative ID' field",
+      de: "Eigene Referenz der Organisation (Projektnummer, Jira-Key, IC-Nummer) \u2014 das Feld \u201EInitiativen-ID\u201C der App"
+    }
+  },
   {
     key: "docsUrl / pmUrl",
     hint: {
@@ -8721,7 +8736,7 @@ function buildSchemaDescriptor(sectionShapes) {
       ...AI_ACT_VOCABULARIES,
       note: "prohibitedPractices/art50Flags: arrays of these ids. artifacts/obligations: maps keyed by these ids. annexIIICategory: one of these, or omit when no Annex III area applies (record the reasoning in classificationRationale; annexExceptionRationale is only for an Art. 6(3) exception claim). Empty is honest; invented values are rejected."
     },
-    portfolioContext: "Ask the user for the organisation's portfolio-context file first (in the app: Import/Export \u2192 'Download portfolio context'). Call read_portfolio_context on it: it returns the interview plan in the organisation's own wording, the sub-dimensions that are switched off, and the organisation's business units, categories, tags, skills and initiatives \u2014 with the file, business unit and category MUST be from those lists (no inventing) and skill / dependency ids are validated. Pass the same context to assemble_initiative and export_initiative_file. Without the file, interview with the wording below and treat business unit / category as free text.",
+    portfolioContext: "Ask the user for the organisation's portfolio-context file first (in the app: Import/Export \u2192 'Download portfolio context'). Call read_portfolio_context on it: it returns the interview plan in the organisation's own wording, the sub-dimensions that are switched off, the slider step the ratings must follow, and the organisation's business units, categories, tags, skills and initiatives \u2014 with the file, business unit and category MUST be from those lists (no inventing) and skill / dependency ids are validated. Pass the same context to assemble_initiative and export_initiative_file. Without the file, interview with the wording below and treat business unit / category as free text.",
     handoff: "Call assemble_initiative with the compact spec (+ context), review derivedScores (and any warnings) with the user, then call export_initiative_file with the SAME spec (+ context) \u2192 save the JSON \u2192 in the app: Import/Export \u2192 Single initiative \u2192 drop the file \u2192 'Add as new' \u2192 Confirm. If the initiative carries EU-AI-Act data, the organisation's EU-AI-Act module must be switched on (Settings \u203A AI Act) when importing."
   };
 }
@@ -8825,6 +8840,7 @@ var compactSpecSchema = external_exports.object({
     "ONLY to UPDATE an existing initiative: its id (from read_portfolio_context \u2192 lists.initiatives, or the app). The exported file then updates that initiative in place. Omit for a new initiative \u2014 never invent an id."
   ),
   name: requiredText(),
+  externalId: external_exports.preprocess((v) => typeof v === "string" && v.trim() === "" ? void 0 : v, external_exports.string().trim().min(1).optional()).describe("The organisation's own reference for the initiative (project number, Jira key, IC id, \u2026) \u2014 ask for it when the organisation uses such references"),
   businessUnit: requiredText().describe("With a portfolio context: one of the organisation's business units (read_portfolio_context \u2192 lists.businessUnits)"),
   owner: requiredText(),
   description: requiredText(),
@@ -8938,11 +8954,13 @@ var portfolioContextSchema = external_exports.object({
   currency: external_exports.string(),
   aiActEnabled: external_exports.boolean(),
   discountRatePct: external_exports.number(),
+  /** Slider step (5/10/20/25). Files from before 2026-08-21 lack it → no grid check. */
+  sliderGranularity: external_exports.number().int().positive().max(100).optional(),
   businessUnits: external_exports.array(external_exports.string()),
   categories: external_exports.array(external_exports.string()),
   suggestedTags: external_exports.array(external_exports.string()),
   skills: external_exports.array(external_exports.object({ id: external_exports.string().min(1), name: external_exports.string() }).passthrough()),
-  initiatives: external_exports.array(external_exports.object({ id: external_exports.string().min(1), name: external_exports.string(), status: external_exports.enum(STATUS_VALUES) }).passthrough()),
+  initiatives: external_exports.array(external_exports.object({ id: external_exports.string().min(1), externalId: external_exports.string().trim().optional(), name: external_exports.string(), status: external_exports.enum(STATUS_VALUES) }).passthrough()),
   sliders: external_exports.array(sliderSchema)
 }).passthrough();
 var CONTEXT_SUPPORTED_VERSION = PORTFOLIO_CONTEXT_VERSION;
@@ -9001,6 +9019,15 @@ function checkAgainstContext(spec, ctx) {
   const warnings = [];
   const v = versionNotice(ctx);
   if (v) warnings.push(v);
+  const specExt = spec.externalId?.trim().toLowerCase();
+  if (specExt) {
+    const holder = ctx.initiatives.find((x) => (x.externalId ?? "").trim().toLowerCase() === specExt && x.id !== spec.id);
+    if (holder) {
+      warnings.push(
+        spec.id ? `externalId "${spec.externalId.trim()}" already belongs to "${holder.name}" (${holder.id}) \u2014 two initiatives would share the same organisation reference.` : `externalId "${spec.externalId.trim()}" already belongs to "${holder.name}" (${holder.id}) \u2014 pass that id as \`id\` to UPDATE it instead of creating a duplicate.`
+      );
+    }
+  }
   const bus = ctx.businessUnits;
   let businessUnit = spec.businessUnit;
   const buMatch = canonical(spec.businessUnit, bus);
@@ -9053,6 +9080,10 @@ function resolveSub(base, ctxSlider, mode, lang) {
   if (note) out.note = note;
   return out;
 }
+function gridExample(step) {
+  const pts = [0, step, 2 * step].filter((v) => v < 100);
+  return `${pts.join(", ")} \u2026 100`;
+}
 function buildInterviewPlan(ctx, contextId) {
   const mode = ctx.portfolioMode;
   const lang = ctx.language;
@@ -9073,7 +9104,8 @@ function buildInterviewPlan(ctx, contextId) {
     ...allOff.length ? [`Dimension(s) with EVERY sub-dimension switched off (${allOff.join(", ")}) still need an entry in evaluation: { subs: {}, confidence } \u2014 the score is 0 there; ask only for the confidence.`] : [],
     ctx.businessUnits.length && ctx.categories.length ? "businessUnit MUST be one of lists.businessUnits and aiCategory one of lists.categories (matched case-insensitively, normalised to the organisation's spelling) \u2014 the Composer rejects anything else; new ones are created in the app's Settings, not in the interview." : "This organisation has no business units and/or categories configured yet \u2014 they must be added in the app's Settings and the context downloaded again before an initiative can be assembled.",
     "dependsOn entries must be ids from lists.initiatives; requiredSkills[].skillId must be ids from lists.skills. Never invent an id; leave the list empty when unsure.",
-    "To UPDATE an existing initiative instead of creating a new one, pass its id (from lists.initiatives) as `id` in the spec \u2014 the exported file then updates it in the app (Import/Export \u2192 Single initiative \u2192 'Update'). Omit id for a new initiative.",
+    "To UPDATE an existing initiative instead of creating a new one, pass its id (from lists.initiatives) as `id` in the spec \u2014 the exported file then updates it in the app (Import/Export \u2192 Single initiative \u2192 'Update'). Omit id for a new initiative. Entries in lists.initiatives may carry externalId \u2014 the organisation's own reference (e.g. IC-26-118) \u2014 use it to recognise which initiative the user means. An update REPLACES the whole record: any field, section or row you omit is CLEARED \u2014 decision log, status reports and links included \u2014 so re-send everything that must survive. Exception: the organisation's externalId is carried over automatically when omitted.",
+    ...ctx.sliderGranularity ? [`Ratings are in steps of ${ctx.sliderGranularity} (the organisation's slider step \u2014 Settings \u203A Slider granularity): ask for and send only multiples of ${ctx.sliderGranularity} between 0 and 100 (${gridExample(ctx.sliderGranularity)}); any other value is rejected.`] : [],
     "Dates: talk to the user in dd/mm/yyyy; you may send dates as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd \u2014 the Composer stores yyyy-mm-dd.",
     ctx.aiActEnabled ? "The organisation's EU-AI-Act module is ON: collect the AI-Act block and governance flags." : "The organisation's EU-AI-Act module is OFF: skip the AI-Act block and governance flags (the app would remove them on import).",
     `Pass \`context: "${contextId}"\` (this contextId \u2014 or the whole file again) to assemble_initiative and export_initiative_file so scores are derived over the enabled sub-dimensions and ids are validated. Amounts are in ${ctx.currency}; the default discount rate is ${ctx.discountRatePct}%.`,
@@ -9088,6 +9120,7 @@ function buildInterviewPlan(ctx, contextId) {
       currency: ctx.currency,
       aiActEnabled: ctx.aiActEnabled,
       discountRatePct: ctx.discountRatePct,
+      ...ctx.sliderGranularity ? { sliderGranularity: ctx.sliderGranularity } : {},
       contextExportedAt: ctx.exportedAt
     },
     lists: {
@@ -9095,7 +9128,7 @@ function buildInterviewPlan(ctx, contextId) {
       categories: ctx.categories,
       suggestedTags: ctx.suggestedTags,
       skills: ctx.skills.map((s) => ({ id: s.id, name: s.name })),
-      initiatives: ctx.initiatives.map((i) => ({ id: i.id, name: i.name, status: i.status }))
+      initiatives: ctx.initiatives.map((i) => ({ id: i.id, ...i.externalId ? { externalId: i.externalId } : {}, name: i.name, status: i.status }))
     },
     interview: {
       dimensions,
@@ -9110,7 +9143,7 @@ function buildInterviewPlan(ctx, contextId) {
 // src/assembler.ts
 var uuidSchema = external_exports.string().uuid();
 var isUuid = (v) => typeof v === "string" && uuidSchema.safeParse(v).success;
-function checkSubs(dim, subs, errors, disabled) {
+function checkSubs(dim, subs, errors, disabled, step) {
   const expected = DIMENSION_SUBS[dim];
   const enabled = expected.filter((k) => !disabled.has(k));
   if (!subs || typeof subs !== "object") {
@@ -9122,6 +9155,7 @@ function checkSubs(dim, subs, errors, disabled) {
     if (v === void 0) errors.push(`evaluation.${dim}.subs.${key} is missing`);
     else if (typeof v !== "number" || !Number.isFinite(v)) errors.push(`evaluation.${dim}.subs.${key} must be a number`);
     else if (v < 0 || v > 100) errors.push(`evaluation.${dim}.subs.${key} must be within 0\u2013100 (got ${v})`);
+    else if (step && v % step !== 0) errors.push(`evaluation.${dim}.subs.${key} must be a multiple of ${step} \u2014 the organisation's slider step (got ${v})`);
   }
   for (const key of Object.keys(subs)) {
     if (!expected.includes(key)) errors.push(`evaluation.${dim}.subs.${key} is not a known sub-dimension (expected: ${enabled.join(", ")})`);
@@ -9183,7 +9217,7 @@ function assembleInitiative(input, now = /* @__PURE__ */ new Date()) {
       errors.push(`evaluation.${dim} is missing`);
       continue;
     }
-    checkSubs(dim, d.subs, errors, disabled);
+    checkSubs(dim, d.subs, errors, disabled, context?.sliderGranularity);
     if (!d.confidence) errors.push(`evaluation.${dim}.confidence is missing (Low | Medium | High)`);
     for (const key of Object.keys(d.subs ?? {})) {
       if (disabled.has(key)) warnings.push(`evaluation.${dim}.subs.${key}: this sub-dimension is switched off in the organisation \u2014 value ignored (stored as 0, not scored).`);
@@ -9215,11 +9249,20 @@ function assembleInitiative(input, now = /* @__PURE__ */ new Date()) {
       return [dim, { score: dimensionScore(subs, disabled), confidence: d.confidence, subs }];
     })
   );
+  let externalId = spec.externalId;
+  if (externalId === void 0 && spec.id && context) {
+    const kept = context.initiatives.find((i) => i.id === spec.id)?.externalId?.trim();
+    if (kept) {
+      externalId = kept;
+      warnings.push(`externalId "${kept}" carried over from the organisation's records \u2014 send externalId explicitly to change or clear it.`);
+    }
+  }
   const stamp = now.toISOString();
   const aiAct = spec.aiAct;
   const candidate = {
     ...spec,
     id: spec.id ?? randomUUID(),
+    ...externalId !== void 0 ? { externalId } : {},
     businessUnit,
     aiCategory,
     tags: spec.tags ?? [],
@@ -9265,7 +9308,7 @@ var IMPORT_INSTRUCTIONS = [
   "2. In the BICon app (signed in to the target organisation), open Import/Export.",
   "3. If the initiative carries EU-AI-Act data, make sure the organisation's EU-AI-Act module is switched on (Settings \u203A AI Act) \u2014 the app strips AI-Act fields while it is off.",
   "4. In the 'Single initiative' card, drop the file (or Browse).",
-  "5. Review the preview \u2014 it should show 0 warnings \u2014 then choose 'Add as new' (or 'Update' when the file carries an existing initiative's id or the same name \u2014 the app then keeps that initiative's id and history) and Confirm.",
+  "5. Review the preview \u2014 it should show 0 warnings \u2014 then choose 'Add as new' (or 'Update' when the file carries an existing initiative's id, Initiative ID or name \u2014 the app keeps that initiative's id and creation date, and REPLACES everything else with this file, decision log and status reports included) and Confirm.",
   "6. The initiative appears in the Inventory with the derived dimension scores."
 ].join("\n");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicon/mcp-composer",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "MCP server that helps an AI client compose a valid BICon portfolio initiative and hand it back as an import file (draft-first, no auth, no API calls).",
   "license": "UNLICENSED",
   "author": "BICon Establishment",