@axonity-ai/mcp 0.20.1 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -25,4 +25,17 @@
|
|
|
25
25
|
*/
|
|
26
26
|
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
27
27
|
import type { AxonityClient } from "../client.js";
|
|
28
|
+
export interface SearchWait {
|
|
29
|
+
sleep?: (ms: number) => Promise<void>;
|
|
30
|
+
now?: () => number;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Start the platform's "Search knowledge" run and wait for its answer.
|
|
34
|
+
*
|
|
35
|
+
* The search route only starts a run and returns its handle, so this polls the
|
|
36
|
+
* run until it reaches an end state, then reads the answer the search step
|
|
37
|
+
* wrote. A run that is still going after the wait limit is returned as such,
|
|
38
|
+
* not as an error: it keeps running, and `read_run` can pick it up later.
|
|
39
|
+
*/
|
|
40
|
+
export declare function searchKnowledge(client: AxonityClient, q: string, { sleep, now }?: SearchWait): Promise<Record<string, unknown>>;
|
|
28
41
|
export declare function registerKnowledgeGraphTools(server: McpServer, client: AxonityClient): void;
|
|
@@ -26,6 +26,67 @@
|
|
|
26
26
|
import { z } from "zod";
|
|
27
27
|
import { guard, jsonResult } from "./result.js";
|
|
28
28
|
const KNOWLEDGE = "/api/v1/knowledge";
|
|
29
|
+
/** The platform workflow step whose output is the search answer. */
|
|
30
|
+
const SEARCH_STEP = "search-knowledge";
|
|
31
|
+
/** That step's one output: the answer the gate held to 'knowledge-answer-v1'. */
|
|
32
|
+
const SEARCH_ANSWER_OUTPUT = "answer";
|
|
33
|
+
const TERMINAL = new Set(["completed", "failed", "cancelled", "expired"]);
|
|
34
|
+
const POLL_EVERY_MS = 1500;
|
|
35
|
+
/** Stop waiting after this long; the run keeps going on the platform. */
|
|
36
|
+
const WAIT_LIMIT_MS = 90_000;
|
|
37
|
+
/** Digest marker a large step output leaves behind instead of the text. */
|
|
38
|
+
function isValueMarker(value) {
|
|
39
|
+
return (typeof value === "object" &&
|
|
40
|
+
value !== null &&
|
|
41
|
+
typeof value.$run_value === "string");
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Start the platform's "Search knowledge" run and wait for its answer.
|
|
45
|
+
*
|
|
46
|
+
* The search route only starts a run and returns its handle, so this polls the
|
|
47
|
+
* run until it reaches an end state, then reads the answer the search step
|
|
48
|
+
* wrote. A run that is still going after the wait limit is returned as such,
|
|
49
|
+
* not as an error: it keeps running, and `read_run` can pick it up later.
|
|
50
|
+
*/
|
|
51
|
+
export async function searchKnowledge(client, q, { sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = {}) {
|
|
52
|
+
const start = (await client.get(`${KNOWLEDGE}/search`, { q }));
|
|
53
|
+
const began = now();
|
|
54
|
+
let run = (await client.get(`/api/v1/runs/${start.id}`));
|
|
55
|
+
const stateOf = (r) => {
|
|
56
|
+
if (typeof r?.status !== "string") {
|
|
57
|
+
throw new Error("The platform returned a run without a status.");
|
|
58
|
+
}
|
|
59
|
+
return r.status;
|
|
60
|
+
};
|
|
61
|
+
while (!TERMINAL.has(stateOf(run))) {
|
|
62
|
+
if (now() - began >= WAIT_LIMIT_MS) {
|
|
63
|
+
return {
|
|
64
|
+
runId: start.id,
|
|
65
|
+
status: stateOf(run),
|
|
66
|
+
finished: false,
|
|
67
|
+
note: "The search is still running after 90 seconds. Call read_run with " +
|
|
68
|
+
"this runId later to read its result.",
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
await sleep(POLL_EVERY_MS);
|
|
72
|
+
run = (await client.get(`/api/v1/runs/${start.id}`));
|
|
73
|
+
}
|
|
74
|
+
const step = run.stepStates?.[SEARCH_STEP];
|
|
75
|
+
if (run.status !== "completed") {
|
|
76
|
+
const reason = typeof step?.error === "string" ? step.error : "no reason was recorded";
|
|
77
|
+
throw new Error(`The search run ended as ${run.status}: ${reason}`);
|
|
78
|
+
}
|
|
79
|
+
// The step's output, never its free text: the text is a closing remark and
|
|
80
|
+
// was "" on a run whose answer passed the gate.
|
|
81
|
+
let answer = step?.structuredOutputs?.[SEARCH_ANSWER_OUTPUT];
|
|
82
|
+
if (isValueMarker(answer)) {
|
|
83
|
+
answer = await client.get(`/api/v1/runs/${start.id}/values/${answer.$run_value}`);
|
|
84
|
+
}
|
|
85
|
+
if (typeof answer !== "string" || answer.trim() === "") {
|
|
86
|
+
throw new Error("The search run completed without an answer from its search step.");
|
|
87
|
+
}
|
|
88
|
+
return { runId: start.id, status: "completed", finished: true, answer };
|
|
89
|
+
}
|
|
29
90
|
/** Said on every tool: an empty answer is about the token, not the graph. */
|
|
30
91
|
const CLEARANCE_NOTE = "\n\nYOU READ WITH YOUR TOKEN'S CLEARANCE: what it may not read is " +
|
|
31
92
|
"left out entirely, so an empty answer means nothing THIS TOKEN may see, " +
|
|
@@ -45,27 +106,21 @@ const CURSOR = z
|
|
|
45
106
|
.optional()
|
|
46
107
|
.describe("The previous response's nextCursor, to get the next page. Omit for the " +
|
|
47
108
|
"first page.");
|
|
48
|
-
const AS_OF = z
|
|
49
|
-
.string()
|
|
50
|
-
.optional()
|
|
51
|
-
.describe("A date (YYYY-MM-DD): answer as the graph stood at the end of that day — " +
|
|
52
|
-
"what was valid then. Omit for now.");
|
|
53
109
|
export function registerKnowledgeGraphTools(server, client) {
|
|
54
|
-
server.tool("search_knowledge_graph", "
|
|
55
|
-
"Read-only.
|
|
56
|
-
"
|
|
57
|
-
"
|
|
58
|
-
"
|
|
59
|
-
"
|
|
60
|
-
"
|
|
61
|
-
"
|
|
62
|
-
"
|
|
63
|
-
"\n\
|
|
64
|
-
"
|
|
110
|
+
server.tool("search_knowledge_graph", "Ask what the workspace has learned, with a question in plain words. " +
|
|
111
|
+
"Read-only. It runs the same platform search a person gets from the " +
|
|
112
|
+
"search bar: a short run (\"Search knowledge\") whose librarian reads " +
|
|
113
|
+
"the graph and writes a list of what it found. This tool starts that " +
|
|
114
|
+
"run and waits for the list, up to 90 seconds. " +
|
|
115
|
+
"\n\nThe answer is that list, in words, with no fact ids in it. Report " +
|
|
116
|
+
"it as what the search found, not as a verified truth, and keep any " +
|
|
117
|
+
"uncertainty the list states. Use read_fact or read_source only when " +
|
|
118
|
+
"you have a fact id from somewhere else. " +
|
|
119
|
+
"\n\nIf the search is still running after 90 seconds, the answer says " +
|
|
120
|
+
"so and gives the run's id: read_run reads its result later." +
|
|
65
121
|
CLEARANCE_NOTE, {
|
|
66
122
|
q: z.string().describe("The question, in plain words (at most 2000 characters)."),
|
|
67
|
-
|
|
68
|
-
}, async ({ q, asOf }) => guard(async () => jsonResult(await client.get(`${KNOWLEDGE}/search`, { q, as_of: asOf }))));
|
|
123
|
+
}, async ({ q }) => guard(async () => jsonResult(await searchKnowledge(client, q))));
|
|
69
124
|
server.tool("list_knowledge_topics", "The topics of the knowledge graph, newest first, each with its summary, " +
|
|
70
125
|
"its label and how many facts it holds. Read-only. A topic is a " +
|
|
71
126
|
"subject facts are grouped under; list_topic_facts opens one." +
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"knowledgeGraph.js","sourceRoot":"","sources":["../../src/tools/knowledgeGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC,6EAA6E;AAC7E,MAAM,cAAc,GAClB,oEAAoE;IACpE,0EAA0E;IAC1E,iEAAiE;IACjE,6CAA6C,CAAC;AAEhD,MAAM,SAAS,GACb,0EAA0E;IAC1E,0EAA0E;IAC1E,wEAAwE;IACxE,sBAAsB,CAAC;AAEzB,MAAM,KAAK,GAAG,CAAC;KACZ,MAAM,EAAE;KACR,GAAG,EAAE;KACL,QAAQ,EAAE;KACV,QAAQ,CAAC,6CAA6C,CAAC,CAAC;AAE3D,MAAM,MAAM,GAAG,CAAC;KACb,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CACP,yEAAyE;IACvE,aAAa,CAChB,CAAC;AAEJ,MAAM,
|
|
1
|
+
{"version":3,"file":"knowledgeGraph.js","sourceRoot":"","sources":["../../src/tools/knowledgeGraph.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@axonity-ai/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.21.0",
|
|
4
4
|
"description": "Model Context Protocol server for Axonity Flow — lets an external agent (e.g. Claude Code) read, draft, and update workflows, agents and tools in an Axonity tenant.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|