@axonity-ai/mcp 0.17.0 → 0.19.0

package/dist/tools/conventions.js

@@ -345,8 +345,9 @@ made any time before you attach them.
   then wire with the \`attach_*\` tools — see Wiring.
 - A reference doc has NO kind any more. What used to be a semantic note lives
   in the model itself: a word is a concept (\`create_concept\`), a table card
-  is the table's description and grain, a source query is the table's
-  \`provenance\`, an example question is a measure's \`questions\`. The
+  is the table's description and grain, a source query is a query of its
+  own (\`create_query\`, the table's \`fillingQueryId\`), an example question
+  is a measure's \`questions\`. The
   platform refuses \`semanticKind\`, \`semanticDetails\`, \`subjectTableId\`
   and \`subjectSourceId\` on a reference doc, and says where each one went.
   Building the SEMANTIC MODEL? Read \`axonity_semantic_conventions\` first —
@@ -970,6 +971,15 @@ the rows; the rows come from \`read_data_table\`.
   the box, call \`list_toolbox_dependent_tools\` — it names the tools that would
   start failing at run time with a bare 401.
 
+## Who may read what
+Every policy, skill, reference doc and table carries a label: \`level\`
+(public, internal, confidential) and \`audienceIds\`, whom it is meant for. An
+agent and a workflow carry a \`clearance\`; so does your token, and you read
+with it. Look audience ids up with \`list_audiences\` — never guess one, and
+compare on id, never on name. \`level: null\` makes a thing readable by nobody.
+Narrowing a label is always allowed; widening it is a colleague's act, never
+yours.
+
 ## Tenant
 - Your token fixes the tenant. You cannot act across tenants; never send a
   tenant id in a body.
@@ -1013,7 +1023,7 @@ const SEMANTIC_KNOWLEDGE_UNAVAILABLE = "## Semantic knowledge — NOT AVAILABLE\
     "The rules for writing the semantic layer could not be read from this deploy " +
     `(\`GET ${SEMANTIC_KNOWLEDGE_ROUTE}\`). This connector does not carry a copy ` +
     "of them. Do not build the semantic model — no concept, no measure, no " +
-    "table provenance — until they can be read: call " +
+    "query — until they can be read: call " +
     "`axonity_semantic_conventions` again, and if it still fails, report it " +
     "rather than deciding what the knowledge should say yourself.";
 /**
@@ -1065,11 +1075,21 @@ columns and the dimensions each table reaches.
 - **Derived** — arithmetic over other measures by name: a sum over two facts,
   a margin, a share of the total with \`ignore\`.
 - **Time** and **cumulative** — the same measure in another window, or a
-  running total. Use them only where the spec marks them \`available\`.
-
-**Row logic belongs in the table's source query, not in a measure.** A value
-per row (net = gross − discount) is a column, added to the table's
-\`provenance.sql\` and described like any other column. A measure is computed
+  running total, measured in a calendar of the workspace's date table.
+
+**Time runs over one date table.** One table per workspace is the date table
+(\`dateTable: true\`, a row per day), and its \`calendars\` say which column
+holds the year, quarter, month, week and day — a production calendar is just
+another calendar. Every fact reaches it through its own time axis, so a week
+means the same thing to each of them. A series runs over the calendar's
+periods: a period without rows is shown empty, not left out. A window's total
+is the window ending at the end of the period asked for; a running total per
+month is the standing at the end of each month, never their sum. A fact kept
+per month is not asked per week (\`grain_too_fine\`).
+
+**Row logic belongs in the query that fills the table, not in a measure.** A
+value per row (net = gross − discount) is a column, added to that query's
+\`sql\` and described like any other column. A measure is computed
 per question — period, grain, split, filters — and is never stored.
 
 **How a number is computed.** Each leaf is aggregated on its own table, over
@@ -1083,8 +1103,15 @@ rests on itself, euros added to dogs, a format that does not fit what the
 number counts: each is refused with a code. \`validate_measure\` returns them
 before you save; repair on the code before asking a person.
 
+**Explain a number by its parts.** \`query_measures\` with \`explain: true\`
+gives what each part of the formula answered, on the total and per period and
+group. Use it to say why a number moved, instead of reading rows.
+
 **Order.** Base measures first, each with its \`quantity\`; then the derived
-ones; \`validate_measure\` before every save; publish from the bottom up.
+ones; \`validate_measure\` before every save; publish from the bottom up — a
+published measure over an unpublished one is refused. A measure knows what
+rests on it (\`usedBy\`, \`dashboards\` on \`read_measure\`): read that before
+you change or delete one, because those numbers move with it.
 `;
 /** Read this deploy's semantic-knowledge rules, or say why not. Exported for testing. */
 export async function readSemanticKnowledgeRules(client) {
@@ -1112,7 +1139,7 @@ export function registerConventions(server, client) {
         ],
     }));
     server.tool("axonity_semantic_conventions", "Read BEFORE building a workspace's semantic model: the tables with " +
-        "their provenance and grain, the measures, and the concepts that say " +
+        "the queries that fill them and their grain, the measures, and the concepts that say " +
         "what a word or a number means. Returns this deploy's rules for writing " +
         "it: what a concept owes, what a measure's description and questions " +
         "must say, and what a table's grain must say about one row. Read live " +

package/dist/tools/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/tools/conventions.ts"],"names":[],"mappings":"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"}

package/dist/tools/dataSources.d.ts

@@ -10,11 +10,11 @@
  * shows, and duplicating a dashboard.
  *
  * **There are no sync tools any more.** A sync was a separate object beside
- * the table it filled; the semantic model made it the table's own
- * `provenance` (source, query, grain, key, mode, schedule), so a changed query
- * goes through the same approval as a changed column. Filling a table is now
- * `create_data_table` / `update_data_table` with `provenance`, and running it
- * early is `refresh_data_table` (tools/dataTables.ts). A measure is no longer
+ * the table it filled. The semantic model first made it the table's own
+ * `provenance`; axonity-flow#2013 then moved the source, SQL and grain into a
+ * named query (tools/queries.ts), leaving the table its `filledBy`,
+ * `fillingQueryId` and `rhythm`. Running a fill early is `refresh_data_table`
+ * (tools/dataTables.ts). A measure is no longer
  * a field on a table either: it is its own versioned entity (`create_measure`
  * and the rest of the generic family).
  *

package/dist/tools/dataSources.js

@@ -10,11 +10,11 @@
  * shows, and duplicating a dashboard.
  *
  * **There are no sync tools any more.** A sync was a separate object beside
- * the table it filled; the semantic model made it the table's own
- * `provenance` (source, query, grain, key, mode, schedule), so a changed query
- * goes through the same approval as a changed column. Filling a table is now
- * `create_data_table` / `update_data_table` with `provenance`, and running it
- * early is `refresh_data_table` (tools/dataTables.ts). A measure is no longer
+ * the table it filled. The semantic model first made it the table's own
+ * `provenance`; axonity-flow#2013 then moved the source, SQL and grain into a
+ * named query (tools/queries.ts), leaving the table its `filledBy`,
+ * `fillingQueryId` and `rhythm`. Running a fill early is `refresh_data_table`
+ * (tools/dataTables.ts). A measure is no longer
  * a field on a table either: it is its own versioned entity (`create_measure`
  * and the rest of the generic family).
  *
@@ -57,14 +57,15 @@ export function registerDataSourceTools(server, client) {
         "query. `containerWord` is what this warehouse calls the container " +
         "(\"dataset\" on BigQuery, \"schema\" on PostgreSQL). Column types are " +
         "the warehouse's own names, passed through. Read this before writing a " +
-        "query or a table's provenance, rather than guessing table names. " +
+        "query, rather than guessing table names. " +
         "On a source restricted to `policy.allowedDatasets` it reads those " +
         "datasets one by one, so it answers even when the key may not list " +
         "the whole project.", { id: SOURCE_ID }, async ({ id }) => guard(async () => jsonResult(await client.get(`${SOURCES}/${id}/schema`))));
     server.tool("query_data_source", "Run a READ-ONLY SQL query against the warehouse and get the rows back. " +
         "For looking — checking what a warehouse table holds, trying the " +
-        "query a table's provenance will run. To fill a table regularly, give " +
-        "it a `provenance` (create_data_table / update_data_table). " +
+        "statement before it becomes a query. To fill a table regularly, make " +
+        "it a query (create_query, try it with test_query) and point the table " +
+        "at it: `filledBy: \"query\"`, `fillingQueryId`, `rhythm`. " +
         "\n\nTHE ROWS ARE CAPPED. `truncated: true` means rows were left out: " +
         "`rowCount` is what came back, `totalRows` is what matched. Never report " +
         "a count or a total off a truncated answer — aggregate in the SQL " +
@@ -86,7 +87,7 @@ export function registerDataSourceTools(server, client) {
             .int()
             .optional()
             .describe("How many rows you want back. Clamped by the platform — a bigger " +
-            "answer belongs in a table with provenance, not in a response."),
+            "answer belongs in a table filled by a query, not in a response."),
     }, async ({ id, sql, maxRows }) => guard(async () => jsonResult(await client.post(`${SOURCES}/${id}/query`, {
         sql,
         ...(maxRows !== undefined ? { maxRows } : {}),
@@ -103,7 +104,11 @@ export function registerMeasureTools(server, client) {
         "this table, and create_measure defines one. Read this for the column " +
         "names a measure's formula, `splitBy` or `filters` may use — or " +
         "get_measure_formula_spec({ includeWorkspace: true }) for every " +
-        "table's columns at once.", {
+        "table's columns at once. " +
+        "\n\nOn the workspace's date table it also says `dateTable: true` and " +
+        "its `calendars`, each naming the column that holds the year, quarter, " +
+        "month, week and day: what a time window (shift, to_date, rolling, " +
+        "running) can be measured in.", {
         tableId: z.string().describe("The dynamic table's id."),
         useDraft: z
             .boolean()
@@ -115,7 +120,7 @@ export function registerMeasureTools(server, client) {
         "own. Read-only. This is where a dashboard's numbers come from. " +
         "\n\nEach question is " +
         "`{ key, measure, tableId?, period?, start?, end?, compare?, grain?, " +
-        "splitBy?, filters?, limit?, useDraft? }`. `key` is your own label and " +
+        "splitBy?, filters?, limit?, useDraft?, useDraftChain?, explain? }`. `key` is your own label and " +
         "comes back on the answer. `measure` is the measure's NAME — its " +
         "handle, unique in the workspace (list_measures); `tableId` is " +
         "optional and no longer what finds it. `period` is one of: " +
@@ -124,16 +129,35 @@ export function registerMeasureTools(server, client) {
         "(YYYY-MM-DD) for a custom range. `compare` is none, previous_period or " +
         "previous_year. `grain` (none, auto, day, week, month, quarter, year) " +
         "draws a series. `splitBy` names a column to group by; `limit` (1-50) " +
-        "keeps the largest groups. " +
+        "keeps the largest groups. `useDraft` reads this measure's draft; " +
+        "`useDraftChain` also the drafts of the measures UNDER it — each part's " +
+        "`readFrom` then says which version it read. " +
         "\n\nA MEASURE OVER OTHER MEASURES is computed per group: each of " +
         "its parts is aggregated on its own table, and the formula is applied " +
         "to the results. Its TOTAL is computed again over the whole period, " +
         "never added up from the groups — the total of a margin % is total " +
         "margin over total revenue, not the average of the monthly " +
         "percentages. Report the total you are given; do not sum the series. " +
-        "read_measure shows which parts a number is made of. " +
+        "A time window is the window ENDING at the end of the period asked " +
+        "for, and a running total per month is the standing at the end of " +
+        "each month, not their sum. " +
+        "\n\nTO EXPLAIN A NUMBER, ask `explain: true`: the answer's `leaves` " +
+        "are the parts of the formula (table, aggregation, conditions, window) " +
+        "and `parts` holds what each part gave for the total, in the order of " +
+        "`leaves` — and each point of `series` and each entry of `groups` " +
+        "carries its own `parts`. \"The margin fell\" is not an explanation; " +
+        "\"revenue held and cost rose\" is. Use it instead of reading rows. " +
         "\n\nONE BAD QUESTION DOES NOT FAIL THE CALL: every answer carries " +
-        "`ok`, and `ok: false` comes with an `error` of its own. Check each one. " +
+        "`ok`, and `ok: false` comes with an `error` of its own and, where it " +
+        "has one, a `code` from get_measure_formula_spec — `grain_too_fine` " +
+        "(a fact kept per month asked per week: ask a coarser grain), " +
+        "`unreachable_dimension`, or `breaks_measure` (a column, table or " +
+        "relationship it reads is gone: the measure must be repaired, not the " +
+        "question). Check each one. `warnings` do not make it wrong but are " +
+        "worth saying: `empty_leaf` means one PART found no rows in this " +
+        "period — in a sum that side counts as nought, which is also what a " +
+        "feed that stopped loading looks like. A period with no rows in a " +
+        "series is shown empty, not left out. " +
         "\n\n`freshAsOf` says how old the newest row behind the number is; " +
         "`certified: false` means it was computed from a draft; `tables` names " +
         "every table the number came from. Say so when you " +

package/dist/tools/dataSources.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataSources.js","sourceRoot":"","sources":["../../src/tools/dataSources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataSources.js","sourceRoot":"","sources":["../../src/tools/dataSources.ts"],"names":[],"mappings":"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"}

package/dist/tools/dataTables.js

@@ -159,17 +159,19 @@ export function registerDataTableTools(server, client) {
     // The page envelope is forwarded WHOLE — unwrapping to `items` would
     // rebuild the silent truncation this tool exists to avoid.
     jsonResult(await client.get(`${BASE}/${tableId}/rows`, { q, limit, cursor }))));
-    server.tool("refresh_data_table", "Fill a table from its source NOW instead of at its next scheduled time. " +
-        "Replaces run_data_source_sync: a table's fill is its own `provenance` " +
-        "now, not a separate sync. " +
+    server.tool("refresh_data_table", "Fill a table from its query NOW instead of at its next scheduled time " +
+        "— or at all, for a table with no `rhythm`, which fills only when " +
+        "asked. Replaces run_data_source_sync: what fills a table is the query " +
+        "its `fillingQueryId` names, not a separate sync. " +
         "\n\nTHIS DOES NOT WAIT FOR THE RESULT. The query can take tens of " +
         "seconds, so the platform brings the table's next fill forward and its " +
         "scheduler runs it. The response is the table, with `fill.nextAt` set " +
         "to now. To see how it went, read_data_table again after a moment: " +
         "`fill.lastAt`, `fill.lastRowCount` and `fill.lastError` describe the " +
         "run. " +
-        "\n\nRefused with a 422 when the table has no `provenance` — its rows " +
-        "come from a workflow or an author, and there is nothing to run.", { id: z.string().describe("The table's id.") }, async ({ id }) => guard(async () => jsonResult(await client.post(`${BASE}/${id}/refresh`))));
+        "\n\nRefused with a 422 when the table is not filled by a query " +
+        "(`filledBy` is `author` or `workflow`) — its rows come from a workflow " +
+        "or an author, and there is nothing to run.", { id: z.string().describe("The table's id.") }, async ({ id }) => guard(async () => jsonResult(await client.post(`${BASE}/${id}/refresh`))));
     server.tool("list_data_table_tools", "Which tools this table yields, and which of them a RUN can actually " +
         "reach. Read-only. " +
         "\n\nA published table mints its own CRUD tools, so giving an agent " +

package/dist/tools/dataTables.js.map

@@ -1 +1 @@
-{"version":3,"file":"dataTables.js","sourceRoot":"","sources":["../../src/tools/dataTables.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dataTables.js","sourceRoot":"","sources":["../../src/tools/dataTables.ts"],"names":[],"mappings":"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"}

package/dist/tools/knowledgeGraph.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Reading what the platform has learned: the knowledge graph (axonity-mcp#88,
+ * S5; the platform half is axonity-flow#1918).
+ *
+ * Runs, documents and colleagues teach the workspace facts. Each fact has a
+ * certainty, a validity, the topics it belongs to and the passages it was
+ * learned from. These tools let an agent look — to check what a run learned,
+ * or why an answer said what it said.
+ *
+ * **It reads with the token's clearance.** The platform filters every read in
+ * its own queries: a fact the token may not read is not in a search, not in
+ * its topic, and not found by id. So an empty answer is an answer about what
+ * THIS TOKEN may see, and the descriptions say so.
+ *
+ * **Looking, never judging.** Confirming, rejecting, correcting, archiving,
+ * relabelling and erasing a fact, answering a decision or a learning round:
+ * all of that ends with a person by design, and `test/denyList.ts` records it.
+ * So do the work lists of the Oversight screen — they hold only what the
+ * reader maintains or was handed, and a token maintains nothing, so a tool
+ * over them could only ever answer an empty list.
+ *
+ * **The module can be off.** Every route here sits behind the Cortex module;
+ * switched off, each answers 403 with the module's sentence, which
+ * `ForbiddenError` turns into plain words rather than "your token may not".
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AxonityClient } from "../client.js";
+export declare function registerKnowledgeGraphTools(server: McpServer, client: AxonityClient): void;

package/dist/tools/knowledgeGraph.js

@@ -0,0 +1,126 @@
+/**
+ * Reading what the platform has learned: the knowledge graph (axonity-mcp#88,
+ * S5; the platform half is axonity-flow#1918).
+ *
+ * Runs, documents and colleagues teach the workspace facts. Each fact has a
+ * certainty, a validity, the topics it belongs to and the passages it was
+ * learned from. These tools let an agent look — to check what a run learned,
+ * or why an answer said what it said.
+ *
+ * **It reads with the token's clearance.** The platform filters every read in
+ * its own queries: a fact the token may not read is not in a search, not in
+ * its topic, and not found by id. So an empty answer is an answer about what
+ * THIS TOKEN may see, and the descriptions say so.
+ *
+ * **Looking, never judging.** Confirming, rejecting, correcting, archiving,
+ * relabelling and erasing a fact, answering a decision or a learning round:
+ * all of that ends with a person by design, and `test/denyList.ts` records it.
+ * So do the work lists of the Oversight screen — they hold only what the
+ * reader maintains or was handed, and a token maintains nothing, so a tool
+ * over them could only ever answer an empty list.
+ *
+ * **The module can be off.** Every route here sits behind the Cortex module;
+ * switched off, each answers 403 with the module's sentence, which
+ * `ForbiddenError` turns into plain words rather than "your token may not".
+ */
+import { z } from "zod";
+import { guard, jsonResult } from "./result.js";
+const KNOWLEDGE = "/api/v1/knowledge";
+/** Said on every tool: an empty answer is about the token, not the graph. */
+const CLEARANCE_NOTE = "\n\nYOU READ WITH YOUR TOKEN'S CLEARANCE: what it may not read is " +
+    "left out entirely, so an empty answer means nothing THIS TOKEN may see, " +
+    "not that nothing was learned. If Cortex is switched off in the " +
+    "workspace, the call is refused and says so.";
+const PAGE_NOTE = "\n\nTHE RESPONSE IS ONE PAGE: { items, nextCursor, pageSize, hasMore }. " +
+    "While hasMore is true you have not seen them all — pass nextCursor back " +
+    "as cursor for the next page. Never build a cursor yourself, and never " +
+    "count from one page.";
+const LIMIT = z
+    .number()
+    .int()
+    .optional()
+    .describe("Page size. Omit for the platform's default.");
+const CURSOR = z
+    .string()
+    .optional()
+    .describe("The previous response's nextCursor, to get the next page. Omit for the " +
+    "first page.");
+const AS_OF = z
+    .string()
+    .optional()
+    .describe("A date (YYYY-MM-DD): answer as the graph stood at the end of that day — " +
+    "what was valid then. Omit for now.");
+export function registerKnowledgeGraphTools(server, client) {
+    server.tool("search_knowledge_graph", "Search what the workspace has learned, with a question in plain words. " +
+        "Read-only. The same search an agent in a run gets. " +
+        "\n\nThe answer lands on up to eight places (`landing`), each a fact " +
+        "or a topic with what hangs around it. A fact never comes bare: its " +
+        "`certainty`, `status`, validity (`validFrom`, `validUntil`), its " +
+        "topics and its `passages` — the evidence, each with its source, the " +
+        "source's score and a date. Report a fact with its certainty and " +
+        "source, not as plain truth. `tips` are facts below the threshold for " +
+        "an answer; they are only shown to someone who maintains them. " +
+        "\n\nUse read_fact for one fact's full card and read_source for where " +
+        "it came from." +
+        CLEARANCE_NOTE, {
+        q: z.string().describe("The question, in plain words (at most 2000 characters)."),
+        asOf: AS_OF,
+    }, async ({ q, asOf }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/search`, { q, as_of: asOf }))));
+    server.tool("list_knowledge_topics", "The topics of the knowledge graph, newest first, each with its summary, " +
+        "its label and how many facts it holds. Read-only. A topic is a " +
+        "subject facts are grouped under; list_topic_facts opens one." +
+        PAGE_NOTE +
+        CLEARANCE_NOTE, { limit: LIMIT, cursor: CURSOR }, async ({ limit, cursor }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/topics`, { limit, cursor }))));
+    server.tool("list_topic_facts", "The facts of one topic, each with its certainty, status, label and " +
+        "validity. Read-only. read_fact gives one fact's passages, sources " +
+        "and history." +
+        PAGE_NOTE +
+        CLEARANCE_NOTE, {
+        topicId: z
+            .string()
+            .describe("The topic's id, from list_knowledge_topics or a search."),
+        limit: LIMIT,
+        cursor: CURSOR,
+    }, async ({ topicId, limit, cursor }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/topics/${topicId}/facts`, { limit, cursor }))));
+    server.tool("read_fact", "One fact's whole card. Read-only. Beside the text and its certainty: " +
+        "`passages` (the evidence, each with its source), `topics` and " +
+        "`about` (what it is about), `formulations` (other ways it was said), " +
+        "`provenance` (which run or document taught it), `events` (its " +
+        "history: learned, confirmed, corrected, archived), `knownSince`, " +
+        "`shelfLifeUntil`, and whether it waits on a person (`doubtful`, " +
+        "`pendingCorrection`, `questionOpen`). " +
+        "\n\nTo check what a run learned, look for that run in `provenance` " +
+        "and `events[].runId`. A fact this token may not read answers as not " +
+        "found, exactly like one that does not exist." +
+        CLEARANCE_NOTE, { id: z.string().describe("The fact's id, from a search or a topic.") }, async ({ id }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/facts/${id}`))));
+    server.tool("read_source", "Where facts came from: one source's card. Read-only. Its type and " +
+        "score (`score`, and the `startScore` its type gave it), how often it " +
+        "was right, wrong or silent (`nRight`, `nWrong`, `nSilent`), whether " +
+        "its score is pinned, how many facts rest on it, and its history. A " +
+        "fact's passages name their source by id." +
+        CLEARANCE_NOTE, { id: z.string().describe("The source's id, from a fact's passages.") }, async ({ id }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/sources/${id}`))));
+    server.tool("list_knowledge_tree", "One level of the knowledge graph's tree: the top layer, or the " +
+        "children of `parent`. Read-only. Each node is a group or a topic, " +
+        "with its summary, label, fact count and `hasChildren` — call again " +
+        "with its id as `parent` to go one level down." +
+        PAGE_NOTE +
+        CLEARANCE_NOTE, {
+        parent: z
+            .string()
+            .optional()
+            .describe("The node to open. Omit for the top layer."),
+        limit: LIMIT,
+        cursor: CURSOR,
+    }, async ({ parent, limit, cursor }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/tree`, { parent, limit, cursor }))));
+    server.tool("list_related_topics", "The topics and groups nearest to one node of the tree, nearest first — " +
+        "at most five, so the answer is always complete (`nextCursor` is " +
+        "always null). Read-only. Use it to step sideways from a topic." +
+        CLEARANCE_NOTE, { nodeId: z.string().describe("A topic or group id, from the tree or a search.") }, async ({ nodeId }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/tree/${nodeId}/related`))));
+    server.tool("list_archived_facts", "What was archived recently (the platform keeps them visible for a " +
+        "while, thirty days to start with), so a second pair of eyes can look " +
+        "afterwards. Read-only. Restoring one is a colleague's decision, not " +
+        "something a token can do: report what you found." +
+        PAGE_NOTE +
+        CLEARANCE_NOTE, { limit: LIMIT, cursor: CURSOR }, async ({ limit, cursor }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/archived`, { limit, cursor }))));
+}
+//# sourceMappingURL=knowledgeGraph.js.map

package/dist/tools/knowledgeGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledgeGraph.js","sourceRoot":"","sources":["../../src/tools/knowledgeGraph.ts"],"names":[],"mappings":"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"}

package/dist/tools/measureFormula.d.ts

@@ -17,14 +17,14 @@
  * **Checking is the platform's too.** `validate_measure` forwards to
  * `POST /measures/validate`, the route the editor calls while somebody types,
  * so an agent and a person can never disagree about whether a formula is
- * acceptable. `read_measure` asks that same route to write the stored tree back
- * as text, rather than this connector unparsing it.
+ * acceptable. `read_measure` asks that same route for the leaves a stored tree
+ * folds down to; the text is the platform's own `formula` on the measure.
  *
  * The one rule held HERE is the shape of a write: a measure is written as
  * `definition.expression`, and the fields from before the formula are refused
- * with `legacy_field`. The platform still accepts them while its own form is
- * replaced; an agent has no such form to keep working, and a measure written
- * the old way today is one that has to be migrated again.
+ * with `legacy_field`. The platform refuses them too since its form writes only
+ * `expression`; the check stays here because a `definition` WITHOUT
+ * `expression` is still stored there as a `sum` nobody wrote.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { AxonityClient } from "../client.js";

package/dist/tools/measureFormula.js

@@ -17,14 +17,14 @@
  * **Checking is the platform's too.** `validate_measure` forwards to
  * `POST /measures/validate`, the route the editor calls while somebody types,
  * so an agent and a person can never disagree about whether a formula is
- * acceptable. `read_measure` asks that same route to write the stored tree back
- * as text, rather than this connector unparsing it.
+ * acceptable. `read_measure` asks that same route for the leaves a stored tree
+ * folds down to; the text is the platform's own `formula` on the measure.
  *
  * The one rule held HERE is the shape of a write: a measure is written as
  * `definition.expression`, and the fields from before the formula are refused
- * with `legacy_field`. The platform still accepts them while its own form is
- * replaced; an agent has no such form to keep working, and a measure written
- * the old way today is one that has to be migrated again.
+ * with `legacy_field`. The platform refuses them too since its form writes only
+ * `expression`; the check stays here because a `definition` WITHOUT
+ * `expression` is still stored there as a `sum` nobody wrote.
  */
 import { z } from "zod";
 import { guard, jsonResult } from "./result.js";
@@ -82,12 +82,18 @@ export function assertFormulaShape(fields) {
 /**
  * The stored tree, written back as text with its leaves, by the platform.
  *
+ * The text is the measure's own `formula` — the platform writes it on every
+ * read since phase 4 — and the validate route's only where a deploy does not
+ * carry it yet. The leaves always come from the validate route: a read of the
+ * measure does not fold it.
+ *
  * Best effort, and said so: a read must not fail because the explanation
  * could not be produced. When it cannot, the measure comes back as stored with
- * a sentence saying why its formula text is missing.
+ * a sentence saying why its leaves are missing.
  */
 async function explainFormula(client, measure, useDraftChain) {
     const expression = measure.definition?.expression;
+    const ownText = typeof measure.formula === "string" && measure.formula !== "" ? measure.formula : null;
     if (expression === undefined || expression === null) {
         return {
             formula: null,
@@ -106,7 +112,7 @@ async function explainFormula(client, measure, useDraftChain) {
         }));
         return {
             formula: {
-                text: checked.formula,
+                text: ownText ?? checked.formula,
                 tree: expression,
                 leaves: checked.leaves ?? [],
                 quantity: checked.quantity ?? null,
@@ -117,8 +123,8 @@ async function explainFormula(client, measure, useDraftChain) {
     }
     catch (err) {
         return {
-            formula: { text: null, tree: expression },
-            formulaNote: "The formula text and its leaves could not be read from this deploy " +
+            formula: { text: ownText, tree: expression },
+            formulaNote: `The ${ownText === null ? "formula text and its leaves" : "leaves"} could not be read from this deploy ` +
                 `(\`POST ${VALIDATE_ROUTE}\`: ${err instanceof Error ? err.message : String(err)}). ` +
                 "The stored tree is above.",
         };
@@ -138,7 +144,8 @@ export function registerMeasureFormulaTools(server, client) {
         "(`not_yet_supported`) — do not use it. " +
         "\n\n`includeWorkspace: true` adds THIS workspace's vocabulary as " +
         "`workspace`: its measures (name, label, quantity, status), its tables " +
-        "and columns, and which dimensions each table reaches — the names a " +
+        "and columns, which dimensions each table reaches, and the date " +
+        "table's calendars with the grains each one has — the names a " +
         "formula may use. The answer is then `{ spec, workspace }`; without " +
         "it, the spec itself.", {
         includeWorkspace: z
@@ -182,7 +189,16 @@ export function registerMeasureFormulaTools(server, client) {
         "message), `too_complex` (give a part its own name), " +
         "`quantity_mismatch` (adding euros to dogs, or a format that does not " +
         "fit), `unreachable_dimension` (declare the relationship, or write " +
-        "`ignore` to mean the total on purpose), `not_yet_supported`. " +
+        "`ignore` to mean the total on purpose), `no_date_table` / " +
+        "`no_time_axis` (a time window needs the workspace's date table and a " +
+        "time axis on the table the part reads), `calendar_missing_grain` / " +
+        "`unknown_calendar` (map the grain in the calendar, or name one that " +
+        "exists), `stock_over_time` (a running total of a `latest` or `first` " +
+        "means nothing), `not_yet_supported`. " +
+        "\n\nEach leaf also says what it was read from (`readFrom`: every " +
+        "measure walked to reach it, then the table, each with the version " +
+        "read) and over which `window` — shift, to_date, rolling, running, " +
+        "with its calendar. Empty `window` is the period asked for. " +
         "`quantity_generic` is a warning: the migration left the placeholder " +
         "quantity — say what the number counts.", {
         expression: z
@@ -219,7 +235,12 @@ export function registerMeasureFormulaTools(server, client) {
         "folds down to, each on its own table — `formula.quantity`, and " +
         "`formula.problems`: a measure that rests on a column or measure that " +
         "has since gone says so here. `readsTables` follows from the leaves; " +
-        "there is no home table.", {
+        "there is no home table. " +
+        "\n\nWHAT IT IS CONNECTED TO: `dependsOn` is every measure it rests " +
+        "on — the whole chain, which publishing checks; `usedBy` every " +
+        "measure that rests on IT; `dashboards` every dashboard with a tile " +
+        "on it. Read `usedBy` and `dashboards` before you change or delete a " +
+        "measure: those numbers move with it.", {
         id: z.string().describe("The measure's id."),
         useDraftChain: z
             .boolean()