keywordgraph-mcp-server 1.7.0 → 1.7.3

package/dist/utils/graphInput.js

@@ -0,0 +1,167 @@
+import { fetchUrlContentAsText } from "./urlContent.js";
+import { prepareStatementsPayload, prepareWikilinksPayload, statementsContextSettings, } from "./wikilinksMode.js";
+// ISO 8601 only, deliberately. The API's convertAnyDate() reorders D/M/Y and
+// M/D/Y only when one component exceeds 12, so "03.05.2026" meant as 3 May is
+// stored as 5 March — silent, plausible, wrong. And what it cannot read at all
+// it returns false for, which becomes 1970-01-01 downstream. Neither failure is
+// visible to the caller, so anything ambiguous is refused here instead.
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function timestampIsParsable(value) {
+    const trimmed = value.trim();
+    return ISO_DATE.test(trimmed) && Number.isFinite(Date.parse(trimmed));
+}
+/**
+ * Validate a caller-supplied statements array and its parallel metadata.
+ * Returns null when valid, otherwise the error message to hand back.
+ */
+export function validateStatementsInput(statements, categories, timestamps) {
+    if (statements.length === 0)
+        return "statements must not be an empty array";
+    if (statements.some((statement) => !statement?.trim()))
+        return "statements must not contain empty entries — drop them (and their categories / timestamps entry) before sending";
+    // Empty metadata arrays mean "none provided" — only enforce the per-statement
+    // pairing when there is actual metadata to pair
+    if (categories && categories.length > 0 && categories.length !== statements.length)
+        return `categories must have exactly one entry per statement (got ${categories.length} categories for ${statements.length} statements); use an empty array for statements without metadata`;
+    if (timestamps && timestamps.length > 0) {
+        if (timestamps.length !== statements.length)
+            return `timestamps must have exactly one entry per statement (got ${timestamps.length} timestamps for ${statements.length} statements); use an empty string for statements without a date`;
+        const bad = timestamps.find((timestamp) => timestamp?.trim() && !timestampIsParsable(timestamp));
+        if (bad)
+            return `timestamp "${bad}" is not ISO 8601 — use 2026-08-02 or 2026-08-02T14:30:00Z. Day-first and month-first formats are refused because the API cannot tell them apart below the 13th of the month.`;
+    }
+    return null;
+}
+/**
+ * Resolve the mutually exclusive content inputs (text / url / statements) into
+ * the body fields of a graph request. `statements` skips the text-splitting
+ * path entirely and carries optional parallel `categories` (metadata labels)
+ * and `timestamps` (dates) arrays, one entry per statement.
+ */
+export async function resolveGraphInput(params) {
+    const { statements, categories, timestamps, wikilinksMode } = params;
+    const hasText = Boolean(params.text?.trim());
+    const hasUrl = Boolean(params.url);
+    if (statements && statements.length > 0) {
+        if (hasText || hasUrl) {
+            return {
+                ok: false,
+                error: "Provide only one of: statements, text, or url — not statements together with text/url",
+            };
+        }
+        const invalid = validateStatementsInput(statements, categories, timestamps);
+        if (invalid)
+            return { ok: false, error: invalid };
+        return {
+            ok: true,
+            payload: prepareStatementsPayload(statements, categories, wikilinksMode, timestamps),
+        };
+    }
+    let contentText;
+    if (hasUrl) {
+        const result = await fetchUrlContentAsText(params.url);
+        if (!result.ok)
+            return { ok: false, error: result.error };
+        contentText = result.contentText;
+        if (!contentText?.trim())
+            return { ok: false, error: "URL did not return any text content" };
+    }
+    else if (hasText) {
+        contentText = params.text;
+    }
+    else {
+        return {
+            ok: false,
+            error: "Provide one of: text, url, or statements for analysis",
+        };
+    }
+    return {
+        ok: true,
+        payload: {
+            text: contentText,
+            ...prepareWikilinksPayload(contentText, wikilinksMode),
+        },
+    };
+}
+/**
+ * Resolve the `contexts` array of the multi-graph comparison tools into the
+ * items of a /graphsAndStatements body.
+ *
+ * Statements are only read when EVERY context has them (routes/graphs.js:
+ * `contexts.every(context => context.statements)`), so a statements item in a
+ * mixed array is joined into text — what url and graphName items resolve to
+ * anyway, and its categories and timestamps are dropped with it.
+ *
+ * Naming is the app's job: getContextForEntry (lib/context.js) gives every
+ * unnamed statements context a uuid fragment, because upstream creates the
+ * context by name. Sending statements to an app that predates that fix hangs
+ * for two minutes and returns 504, as does sending timestamps to one that
+ * predates the missing-`Instruments`-require fix in routes/graphs.js.
+ */
+export async function resolveContexts(items, fetchGraphTextByName) {
+    const resolved = [];
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if ("statements" in item) {
+            const invalid = validateStatementsInput(item.statements, item.categories, item.timestamps);
+            if (invalid)
+                return { ok: false, error: `Context at index ${i}: ${invalid}` };
+            resolved.push({
+                statements: item.statements,
+                ...(item.categories?.length ? { categories: item.categories } : {}),
+                ...(item.timestamps?.length ? { timestamps: item.timestamps } : {}),
+            });
+            continue;
+        }
+        if ("text" in item) {
+            if (!item.text.trim())
+                return { ok: false, error: `Context at index ${i} has empty text.` };
+            resolved.push({ text: item.text });
+            continue;
+        }
+        if ("url" in item) {
+            const result = await fetchUrlContentAsText(item.url);
+            if (!result.ok)
+                return {
+                    ok: false,
+                    error: `URL at context index ${i} failed: ${result.error}`,
+                };
+            if (!result.contentText?.trim())
+                return {
+                    ok: false,
+                    error: `URL at context index ${i} did not return any text content`,
+                };
+            resolved.push({ text: result.contentText });
+            continue;
+        }
+        if ("graphName" in item) {
+            const result = await fetchGraphTextByName(item.graphName);
+            if (!result.ok)
+                return {
+                    ok: false,
+                    error: `Graph at context index ${i} failed: ${result.error}`,
+                };
+            resolved.push({ text: result.text });
+            continue;
+        }
+        return {
+            ok: false,
+            error: `Context at index ${i} must be { text }, { statements }, { url }, or { graphName }.`,
+        };
+    }
+    if (!resolved.every((item) => "statements" in item)) {
+        return {
+            ok: true,
+            contexts: resolved.map((item) => "statements" in item ? { text: item.statements.join("\n") } : item),
+        };
+    }
+    const hasCategories = resolved.some((item) => "categories" in item &&
+        (item.categories ?? []).some((entry) => entry.length > 0));
+    const contextSettings = statementsContextSettings(undefined, hasCategories);
+    return {
+        ok: true,
+        contexts: resolved,
+        ...(Object.keys(contextSettings).length > 0 ? { contextSettings } : {}),
+    };
+}
+//# sourceMappingURL=graphInput.js.map

package/dist/utils/graphInput.js.map

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

package/dist/utils/wikilinksMode.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * LLM-facing presets for how [[wikilinks]] in the submitted text are turned
+ * into graph nodes. Each preset maps to a consistent combination of the
+ * engine's textProcessingSettings (and, for the parent modes, a statements +
+ * per-statement categories payload), so callers never compose the raw
+ * vocabulary (doubleSquarebracketsProcessing / mentionsProcessing /
+ * partOfSpeechToProcess / categoriesAsMentions) themselves.
+ *
+ * The settings are applied by the backend only when the graph context is
+ * created: always for doNotSave generation (ephemeral context), and on the
+ * FIRST upload for saved graphs. An existing saved graph keeps the settings
+ * it was created with.
+ *
+ * Parent modes ('obsidianStyle', 'parentAndConcepts') use the same mechanism
+ * as the InfraNodus Obsidian plugin: statements travel as an array with a
+ * per-statement categories array, and categoriesAsMentions turns each
+ * category into a mention token attached to that statement only. The engine
+ * names those mentions [[category]] (bracketed) when doublebrackets are
+ * processed and single squarebrackets are ignored — so parent-page nodes
+ * share the exact [[name]] namespace with inline wikilinks and merge with
+ * nodes from graphs built in 'default'/'wikilinksOnly' modes.
+ *
+ * Parent extraction contract (parent modes), in priority order per line:
+ *   1. A markdown heading (# through ######) sets the CURRENT PARENT for all
+ *      statements below it, until the next heading. `## [[Page A]]` sets the
+ *      parent to "Page A"; a plain heading `## Introduction` sets it to
+ *      "Introduction". Heading lines are not statements themselves.
+ *   2. A line starting with `[[Parent Page]]: ` (colon required) overrides
+ *      the section parent for that line only; the prefix is removed from the
+ *      statement text.
+ *   3. Any other line becomes a statement under the current section parent
+ *      (or no parent before the first heading).
+ * Note `#tag` without a space after the hashes is a hashtag, not a heading.
+ */
+export declare const WikilinksModeEnum: z.ZodEnum<["default", "wikilinksOnly", "obsidianStyle", "parentAndConcepts", "plainText"]>;
+export type WikilinksMode = z.infer<typeof WikilinksModeEnum>;
+export declare const wikilinksModeDescription: string;
+export interface WikilinksPayload {
+    text?: string;
+    statements?: string[];
+    categories?: string[][];
+    timestamps?: string[];
+    contextSettings?: Record<string, unknown>;
+}
+/**
+ * Payload for callers that already hold discrete statements (and optionally
+ * parallel per-statement categories / timestamps arrays), so nothing has to be
+ * parsed out of a text blob. Mode-specific bracket handling still applies and
+ * overrides the category defaults where the two disagree.
+ */
+export declare function prepareStatementsPayload(statements: string[], categories: string[][] | undefined, mode: WikilinksMode | undefined, timestamps?: string[]): WikilinksPayload;
+/**
+ * Processing settings for a statements upload. The API reads these from the
+ * top level of the body (`contextSettings`), so multi-context requests share
+ * one set across all of their contexts.
+ */
+export declare function statementsContextSettings(mode: WikilinksMode | undefined, hasCategories: boolean): Record<string, unknown>;
+/**
+ * Translate the mode + content into the request-body fields to merge into
+ * the /graphAndStatements payload. Returns {} for 'default' so callers can
+ * spread it unconditionally over a body that already carries `text`.
+ */
+export declare function prepareWikilinksPayload(contentText: string, mode: WikilinksMode | undefined): WikilinksPayload;
+//# sourceMappingURL=wikilinksMode.d.ts.map

package/dist/utils/wikilinksMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wikilinksMode.d.ts","sourceRoot":"","sources":["../../src/utils/wikilinksMode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,iBAAiB,4FAM5B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE9D,eAAO,MAAM,wBAAwB,QAS4E,CAAC;AAQlH,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAsDD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACvC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,SAAS,EAClC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,UAAU,CAAC,EAAE,MAAM,EAAE,GACnB,gBAAgB,CAiBlB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACxC,IAAI,EAAE,aAAa,GAAG,SAAS,EAC/B,aAAa,EAAE,OAAO,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACtC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,aAAa,GAAG,SAAS,GAC7B,gBAAgB,CAyClB"}

package/dist/utils/wikilinksMode.js

@@ -0,0 +1,188 @@
+import { z } from "zod";
+/**
+ * LLM-facing presets for how [[wikilinks]] in the submitted text are turned
+ * into graph nodes. Each preset maps to a consistent combination of the
+ * engine's textProcessingSettings (and, for the parent modes, a statements +
+ * per-statement categories payload), so callers never compose the raw
+ * vocabulary (doubleSquarebracketsProcessing / mentionsProcessing /
+ * partOfSpeechToProcess / categoriesAsMentions) themselves.
+ *
+ * The settings are applied by the backend only when the graph context is
+ * created: always for doNotSave generation (ephemeral context), and on the
+ * FIRST upload for saved graphs. An existing saved graph keeps the settings
+ * it was created with.
+ *
+ * Parent modes ('obsidianStyle', 'parentAndConcepts') use the same mechanism
+ * as the InfraNodus Obsidian plugin: statements travel as an array with a
+ * per-statement categories array, and categoriesAsMentions turns each
+ * category into a mention token attached to that statement only. The engine
+ * names those mentions [[category]] (bracketed) when doublebrackets are
+ * processed and single squarebrackets are ignored — so parent-page nodes
+ * share the exact [[name]] namespace with inline wikilinks and merge with
+ * nodes from graphs built in 'default'/'wikilinksOnly' modes.
+ *
+ * Parent extraction contract (parent modes), in priority order per line:
+ *   1. A markdown heading (# through ######) sets the CURRENT PARENT for all
+ *      statements below it, until the next heading. `## [[Page A]]` sets the
+ *      parent to "Page A"; a plain heading `## Introduction` sets it to
+ *      "Introduction". Heading lines are not statements themselves.
+ *   2. A line starting with `[[Parent Page]]: ` (colon required) overrides
+ *      the section parent for that line only; the prefix is removed from the
+ *      statement text.
+ *   3. Any other line becomes a statement under the current section parent
+ *      (or no parent before the first heading).
+ * Note `#tag` without a space after the hashes is a hashtag, not a heading.
+ */
+export const WikilinksModeEnum = z.enum([
+    "default",
+    "wikilinksOnly",
+    "obsidianStyle",
+    "parentAndConcepts",
+    "plainText",
+]);
+export const wikilinksModeDescription = "How [[wikilinks]] in the text become graph nodes. " +
+    "'default': wikilinks become [[entity]] nodes; statements that contain wikilinks use only those, statements without any are processed word-by-word. " +
+    "'wikilinksOnly': ONLY [[wikilinks]] become nodes, all other words are ignored; nearby wikilinks connect via a sliding co-occurrence window — use for entity/ontology/link statements like '[[alice]] works with [[bob]]' or '[[Page A]] links to [[Page B]]'. " +
+    "'obsidianStyle': like Obsidian's graph view — markdown headings set the parent page for the statements below them ('## [[Page A]]' or a plain '## Section Title'), and a line may override its parent with a '[[Parent Page]]: ' prefix (colon required); the parent becomes a [[page]] node connected to every concept of its statements, while concepts do NOT connect to each other (star topology around pages/sections). " +
+    "'parentAndConcepts': same heading/prefix parent contract, but concepts also keep their normal co-occurrence connections — best for mixed content (notes, docs, articles) where you want both section/page provenance and a real concept graph. " +
+    "'plainText': brackets are stripped and everything is processed as ordinary words. " +
+    "In all modes parent and wikilink nodes share the [[name]] namespace, so graphs remain comparable/mergeable. " +
+    "With `statements` + `categories` supplied directly, parent extraction is skipped and those categories become the mention labels ('obsidianStyle' still gives the star topology). " +
+    "Takes effect when the graph is generated or first created; an existing saved graph keeps its original setting.";
+const PARENT_PREFIX_RE = /^\s*\[\[([^\]]+)\]\]:\s*/;
+// Heading: 1-6 hashes followed by whitespace ("#tag" without a space is a
+// hashtag, not a heading). Trailing closing hashes (ATX style) are dropped.
+const HEADING_RE = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
+const HEADING_WIKILINK_RE = /^\[\[([^\]]+)\]\]$/;
+/**
+ * Bracket handling for a mode, independent of where the statements come from
+ * (split out of the text or supplied directly by the caller).
+ */
+function bracketSettings(mode) {
+    switch (mode) {
+        case "wikilinksOnly":
+            return {
+                doubleSquarebracketsProcessing: "PROCESS_AS_HASHTAGS_IGNORE_THE_REST",
+                partOfSpeechToProcess: "HASHTAGS_ONLY",
+            };
+        case "plainText":
+            return { doubleSquarebracketsProcessing: "IGNORE_BRACKETS" };
+        default:
+            return {};
+    }
+}
+/**
+ * Settings that turn each per-statement category into a mention node attached
+ * to that statement only. See the module note above for why the bracket
+ * combination matters: it keeps category nodes in the [[name]] namespace.
+ */
+function categorySettings(mode) {
+    if (mode === "plainText") {
+        // Brackets stay stripped in this mode; the mentions still become nodes,
+        // just outside the [[name]] namespace.
+        return {
+            categoriesAsMentions: true,
+            mentionsProcessing: "CONNECT_TO_ALL_CONCEPTS",
+            doubleSquarebracketsProcessing: "IGNORE_BRACKETS",
+        };
+    }
+    return {
+        categoriesAsMentions: true,
+        mentionsProcessing: mode === "obsidianStyle"
+            ? "CONNECT_TO_CONCEPTS_ONLY"
+            : "CONNECT_TO_ALL_CONCEPTS",
+        // IGNORE_BRACKETS on single brackets + processed doublebrackets is the
+        // combination that makes the engine name category mentions [[category]]
+        // instead of @category — keeping them in the same namespace as inline
+        // wikilinks.
+        squareBracketsProcessing: "IGNORE_BRACKETS",
+        doubleSquarebracketsProcessing: "PROCESS_AS_HASHTAGS",
+    };
+}
+/**
+ * Payload for callers that already hold discrete statements (and optionally
+ * parallel per-statement categories / timestamps arrays), so nothing has to be
+ * parsed out of a text blob. Mode-specific bracket handling still applies and
+ * overrides the category defaults where the two disagree.
+ */
+export function prepareStatementsPayload(statements, categories, mode, timestamps) {
+    // Only actual labels matter: a model that sends [[], [], []] for "no
+    // metadata" must not flip the processing settings for the whole upload.
+    const hasCategories = Array.isArray(categories) &&
+        categories.some((entry) => Array.isArray(entry) && entry.length > 0);
+    const hasTimestamps = Array.isArray(timestamps) && timestamps.length > 0;
+    const contextSettings = statementsContextSettings(mode, hasCategories);
+    return {
+        text: "",
+        statements,
+        ...(hasCategories ? { categories } : {}),
+        ...(hasTimestamps ? { timestamps } : {}),
+        // Omit rather than send {} — an empty settings object is not what the
+        // text path sends for the default mode either.
+        ...(Object.keys(contextSettings).length > 0 ? { contextSettings } : {}),
+    };
+}
+/**
+ * Processing settings for a statements upload. The API reads these from the
+ * top level of the body (`contextSettings`), so multi-context requests share
+ * one set across all of their contexts.
+ */
+export function statementsContextSettings(mode, hasCategories) {
+    // Category mentions only survive under the bracket combination in
+    // categorySettings, so it overrides the mode's own bracket handling where
+    // the two disagree. 'wikilinksOnly' keeps its HASHTAGS_ONLY part-of-speech
+    // filter — that is what restricts concept nodes to [[wikilinks]]; its
+    // PROCESS_AS_HASHTAGS_IGNORE_THE_REST would drop the category mentions
+    // along with everything else.
+    return hasCategories
+        ? { ...bracketSettings(mode), ...categorySettings(mode) }
+        : bracketSettings(mode);
+}
+/**
+ * Translate the mode + content into the request-body fields to merge into
+ * the /graphAndStatements payload. Returns {} for 'default' so callers can
+ * spread it unconditionally over a body that already carries `text`.
+ */
+export function prepareWikilinksPayload(contentText, mode) {
+    switch (mode) {
+        case "wikilinksOnly":
+        case "plainText":
+            return { contextSettings: bracketSettings(mode) };
+        case "obsidianStyle":
+        case "parentAndConcepts": {
+            const statements = [];
+            const categories = [];
+            let sectionParent = null;
+            for (const rawLine of contentText.split("\n")) {
+                const line = rawLine.trim();
+                if (!line)
+                    continue;
+                const heading = line.match(HEADING_RE);
+                if (heading) {
+                    const title = heading[2].trim();
+                    const wikilink = title.match(HEADING_WIKILINK_RE);
+                    sectionParent = (wikilink ? wikilink[1] : title).trim() || null;
+                    continue; // heading lines are structure, not statements
+                }
+                const prefix = line.match(PARENT_PREFIX_RE);
+                if (prefix && line.slice(prefix[0].length).trim()) {
+                    statements.push(line.slice(prefix[0].length).trim());
+                    categories.push([prefix[1]]);
+                }
+                else {
+                    statements.push(line);
+                    categories.push(sectionParent ? [sectionParent] : []);
+                }
+            }
+            return {
+                text: "",
+                statements,
+                categories,
+                contextSettings: categorySettings(mode),
+            };
+        }
+        default:
+            return {};
+    }
+}
+//# sourceMappingURL=wikilinksMode.js.map

package/dist/utils/wikilinksMode.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "keywordgraph-mcp-server",
-	"version": "1.7.0",
+	"version": "1.7.3",
 	"description": "KeywordGraph MCP server - A Model Context Protocol server for network thinking and graph analysis",
 	"type": "module",
 	"module": "src/index.ts",