@adrata/adrata-mcp 1.0.49 → 1.0.50

package/tools/threads/work-idea-tools.js

@@ -0,0 +1,172 @@
+/**
+ * Idea tools: a big idea with the VECTOR it arrived on and its source, a
+ * state history (never a flag), and the edges to the scopes, cards and other
+ * ideas that realize or relate to it. See work-thread-tools.js for the model
+ * and CONTRACT.md for the routes.
+ *
+ * Promotion is deliberately NOT a verb here. Turning an idea into an epic is
+ * `add_to_roadmap` (which creates the proposed scope and hands you the git
+ * half) followed by `link_idea` with the new scopeId. One verb per act; the
+ * roadmap tool already says what the PR must contain.
+ */
+
+import {
+  AUDIENCES,
+  GOVERNED_NOTE,
+  IDEA_STATES,
+  VECTORS,
+  audienceQuery,
+  buildQuery,
+  compactBody,
+  governedArgs,
+  pickExactlyOne,
+  validateBody,
+  validateEnum,
+  validateReason,
+  validateStateReason,
+  validateTitle,
+} from './shared.js';
+
+const BASE = '/api/v1/work-ideas';
+
+/** Which link segment and body key a link_idea target maps to. Exported for the test. */
+export const IDEA_LINK_TARGETS = {
+  scopeId: { segment: 'scopes', reading: 'this initiative/epic realizes the idea' },
+  workItemId: { segment: 'items', reading: 'this card realizes part of the idea' },
+  relatedIdeaId: { segment: 'links', reading: 'these two ideas are connected' },
+};
+
+export function registerWorkIdeaTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_ideas',
+    'List the ideas — each with its state (captured | explored | parked | committed | realized | dropped), the vector it arrived on (owner | customer | buyer_demand | competitor | keynote | internal_audit | technology | regulation), its source, audience, progress as COUNTS over the cards it reaches, and how many scopes and decisions touch it. Narrow by state, vector or audience. Check here before capture_idea: a near-duplicate idea is a list nobody reads.',
+    {
+      state: z.enum(IDEA_STATES).optional().describe('Narrow to one state.'),
+      vector: z.enum(VECTORS).optional().describe('Narrow to one arrival vector.'),
+      audience: z.array(z.enum(AUDIENCES)).optional().describe('Narrow to these audiences. Omit for all.'),
+    },
+    async (args) => {
+      const query = buildQuery({ state: args.state, vector: args.vector, audience: audienceQuery(args.audience) });
+      const data = await api('GET', `${BASE}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'get_idea',
+    'Read one idea whole: title, body, vector and source, its state HISTORY (every move with its reason), the scopes that realize it (with the git folder when the importer knows it), the cards it reaches with their columns, related ideas, the decisions that shaped it, the goals it serves, and the discussion count.',
+    {
+      ideaId: z.string().describe('Idea id from list_ideas.'),
+    },
+    async (args) => {
+      const data = await api('GET', `${BASE}/${encodeURIComponent(args.ideaId)}`);
+      return ok({ idea: data?.data ?? null });
+    }
+  );
+
+  server.tool(
+    'capture_idea',
+    `Capture a big idea in state captured. vector and source are REQUIRED: say honestly where it came from (owner | customer | buyer_demand | competitor | keynote | internal_audit | technology | regulation) and name the source (URL, doc path, customer name, transcript title) so the next reader can go back to it. An idea is not a card and not an epic: it has no column and no board. To promote one to an epic later, use add_to_roadmap (which creates the proposed scope and gives you the git half), then link_idea with the scopeId — do not re-create the idea as a scope. Check list_ideas first.${GOVERNED_NOTE}`,
+    {
+      title: z.string().describe('The idea as an outcome statement, at most 160 characters.'),
+      body: z.string().describe('Markdown: what it is, who it is for, why now, what it would take. Quote the source where you can.'),
+      vector: z.enum(VECTORS).describe('Where it arrived from. Pick the true one, not the flattering one.'),
+      source: z.string().describe('The specific source: URL, document path, customer name, transcript title, audit name.'),
+      audience: z.enum(AUDIENCES).describe('Who the idea serves.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      validateEnum(args.vector, VECTORS, 'vector');
+      if (!String(args.source ?? '').trim()) throw new Error('source is required and cannot be blank');
+      const body = compactBody({
+        title: validateTitle(args.title),
+        body: validateBody(args.body),
+        vector: args.vector,
+        source: args.source,
+        audience: args.audience,
+      });
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path: BASE,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldCreate: body });
+      const data = await api('POST', BASE, { body, headers: buildMutationHeaders(args) });
+      return ok({ created: true, idea: data?.data });
+    }
+  );
+
+  server.tool(
+    'set_idea_state',
+    `Move an idea to a new state: captured → explored → committed → realized, or parked / dropped. Every move appends to the idea's state history with the reason; nothing is overwritten. parked and dropped REQUIRE a reason the next reader can act on ("parked until the API lands" beats "later"). committed usually means an epic now exists: run add_to_roadmap and link_idea first, then commit. The reason is recorded on the transition and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      ideaId: z.string().describe('Idea id from list_ideas.'),
+      state: z.enum(IDEA_STATES).describe('The new state.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why the state changes. Recorded in the history; also the audit reason.'),
+    },
+    async (args) => {
+      validateEnum(args.state, IDEA_STATES, 'state');
+      const reason = validateStateReason(args.state, args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.ideaId)}/state`;
+      const body = { state: args.state, reason };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldChange: { ideaId: args.ideaId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ updated: true, idea: data?.data });
+    }
+  );
+
+  server.tool(
+    'link_idea',
+    `Connect an idea to what realizes it or relates to it. Exactly one of: scopeId (an initiative/epic realizes the idea — this is the second half of promotion, after add_to_roadmap), workItemId (a card realizes part of it), relatedIdeaId (two ideas are connected). An edge with a reason; nothing moves. Linking a pair that is already linked replaces the reason (an upsert). The reason is recorded on the link and doubles as the audit reason.${GOVERNED_NOTE}`,
+    {
+      ideaId: z.string().describe('Idea id from list_ideas.'),
+      scopeId: z.string().optional().describe('Initiative or epic id from list_work_scopes (or the scope add_to_roadmap just created).'),
+      workItemId: z.string().optional().describe('Card id.'),
+      relatedIdeaId: z.string().optional().describe('Another idea id from list_ideas.'),
+      ...governedArgs(z),
+      reason: z.string().describe('Why they connect, in a sentence. Recorded on the link; also the audit reason.'),
+    },
+    async (args) => {
+      const { key, value } = pickExactlyOne({
+        scopeId: args.scopeId,
+        workItemId: args.workItemId,
+        relatedIdeaId: args.relatedIdeaId,
+      });
+      const reason = validateReason(args.reason);
+      const path = `${BASE}/${encodeURIComponent(args.ideaId)}/${IDEA_LINK_TARGETS[key].segment}`;
+      const body = { [key]: value, reason };
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldLink: { ideaId: args.ideaId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders({ ...args, reason }) });
+      return ok({ linked: true, ideaId: args.ideaId, [key]: value, idea: data?.data });
+    }
+  );
+}
+
+export const WORK_IDEA_TOOL_NAMES = ['list_ideas', 'get_idea', 'capture_idea', 'set_idea_state', 'link_idea'];

package/tools/threads/work-indicator-tools.js

@@ -0,0 +1,129 @@
+/**
+ * Indicator tools: a named measure with a definition, unit, direction and
+ * target, measuring one goal or strategy, and the readings that say whether
+ * the goal is on track. Status is DERIVED on read, never stored. See
+ * work-thread-tools.js for the model and CONTRACT.md for the routes.
+ */
+
+import {
+  AUDIENCES,
+  GOVERNED_NOTE,
+  INDICATOR_DIRECTIONS,
+  INDICATOR_KINDS,
+  audienceQuery,
+  buildQuery,
+  compactBody,
+  governedArgs,
+  validateDate,
+  validateTitle,
+} from './shared.js';
+
+const BASE = '/api/v1/work-indicators';
+
+export function registerWorkIndicatorTools(
+  server,
+  { z, api, ok, validateApiBridgeRequest, buildMutationHeaders, getGrantedScope = () => undefined }
+) {
+  server.tool(
+    'list_indicators',
+    'List the indicators — each a named measure with its definition, unit, direction (up | down), kind (leading | lagging), target, the goal or strategy it measures, its LATEST reading and the derived status: no_reading | achieved | on_track | off_track | unknown_pace (a reading with no expected value says nothing about pace). Narrow by goalId to see what measures one goal, or by audience. Status is derived, never stored, and there is no percentage.',
+    {
+      goalId: z.string().optional().describe('Only the indicators measuring this goal or strategy.'),
+      audience: z.array(z.enum(AUDIENCES)).optional().describe('Narrow to these audiences. Omit for all.'),
+    },
+    async (args) => {
+      const query = buildQuery({ goalId: args.goalId, audience: audienceQuery(args.audience) });
+      const data = await api('GET', `${BASE}${query}`);
+      const items = data?.data || [];
+      return ok({ count: items.length, items });
+    }
+  );
+
+  server.tool(
+    'create_indicator',
+    `Create an indicator: name the measure, DEFINE it (how it is computed, so two people read the same number), give its unit, its direction (up = higher is better, down = lower is better), whether it is leading (moves before the outcome) or lagging (the outcome itself), its target and the source the readings come from. Attach it to a goal or strategy with goalId. counterOfIndicatorId names the indicator this one guards against Goodhart's law (the measure you watch so the target does not get gamed). Check list_indicators first.${GOVERNED_NOTE}`,
+    {
+      goalId: z.string().optional().describe('The goal or strategy this measures, from list_goals. Omit only for a company-wide measure not yet tied to a goal.'),
+      name: z.string().describe('Short name, at most 160 characters. e.g. "CRO harness GREEN cases".'),
+      definition: z.string().describe('How it is computed and where. The sentence that stops two people reading two numbers.'),
+      unit: z.string().describe('e.g. "count", "USD", "%", "days". Use "" for a bare count if you must.'),
+      direction: z.enum(INDICATOR_DIRECTIONS).describe('up = higher is better; down = lower is better.'),
+      kind: z.enum(INDICATOR_KINDS).describe('leading moves before the outcome; lagging is the outcome.'),
+      targetValue: z.number().optional().describe('The value that means "achieved", in the unit.'),
+      targetOn: z.string().optional().describe('When the target should be met, YYYY-MM-DD.'),
+      source: z.string().describe('Where readings come from: a query, a dashboard, a script, a person.'),
+      audience: z.enum(AUDIENCES).describe('Who this measure is for.'),
+      counterOfIndicatorId: z.string().optional().describe('The indicator this one guards against being gamed.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      const body = compactBody({
+        goalId: args.goalId,
+        name: validateTitle(args.name, 'name'),
+        definition: args.definition,
+        unit: args.unit ?? '',
+        direction: args.direction,
+        kind: args.kind,
+        targetValue: args.targetValue,
+        targetOn: validateDate(args.targetOn, 'targetOn'),
+        source: args.source,
+        audience: args.audience,
+        counterOfIndicatorId: args.counterOfIndicatorId,
+      });
+      if (!String(body.definition ?? '').trim()) throw new Error('definition is required and cannot be blank');
+      if (!String(body.source ?? '').trim()) throw new Error('source is required and cannot be blank');
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path: BASE,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldCreate: body });
+      const data = await api('POST', BASE, { body, headers: buildMutationHeaders(args) });
+      return ok({ created: true, indicator: data?.data });
+    }
+  );
+
+  server.tool(
+    'record_indicator_reading',
+    `Append a reading to an indicator: the value observed, optionally the value the plan EXPECTED by that date (this is what turns a reading into on_track / off_track), when it was observed (defaults to now), and the source it was read from. Readings are appended, never edited — a wrong reading is corrected by a new reading with a note. Each call adds one row; do not retry with a fresh idempotencyKey.${GOVERNED_NOTE}`,
+    {
+      indicatorId: z.string().describe('Indicator id from list_indicators.'),
+      value: z.number().describe('The observed value, in the indicator\'s unit.'),
+      expected: z.number().optional().describe('What the plan expected by observedAt. Omit if there is no plan line; the status will be unknown_pace.'),
+      observedAt: z.string().optional().describe('ISO-8601 timestamp of the observation. Defaults to now.'),
+      source: z.string().describe('Where this number was read from — a query, a report, a run id.'),
+      note: z.string().optional().describe('Context for the reader: a correction, an anomaly, a caveat.'),
+      ...governedArgs(z),
+    },
+    async (args) => {
+      if (!Number.isFinite(Number(args.value))) throw new Error('value must be a finite number');
+      if (!String(args.source ?? '').trim()) throw new Error('source is required and cannot be blank');
+      const path = `${BASE}/${encodeURIComponent(args.indicatorId)}/readings`;
+      const body = compactBody({
+        value: args.value,
+        expected: args.expected,
+        observedAt: args.observedAt,
+        source: args.source,
+        note: args.note,
+      });
+      const preview = validateApiBridgeRequest({
+        method: 'POST',
+        path,
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+        grantedScope: getGrantedScope(),
+      });
+      if (preview?.dryRun) return ok({ ...preview, wouldCreate: { indicatorId: args.indicatorId, ...body } });
+      const data = await api('POST', path, { body, headers: buildMutationHeaders(args) });
+      return ok({ recorded: true, indicatorId: args.indicatorId, indicator: data?.data });
+    }
+  );
+}
+
+export const WORK_INDICATOR_TOOL_NAMES = ['list_indicators', 'create_indicator', 'record_indicator_reading'];