santismm-knowledge-mcp 0.2.1 → 0.3.0

package/dist/shape.js

@@ -78,6 +78,22 @@ const DOMAIN_INFO = {
         lookup: "HRN id (e.g. HRN-001) or slug",
     },
 };
+/**
+ * Newest `updated` across a set of units, or null if none carries one.
+ *
+ * Dates are ISO `YYYY-MM-DD`, so a string comparison is the date comparison.
+ * Derived from the loaded content rather than stamped at build time, so it is
+ * correct in every deployment without anyone remembering to update it.
+ */
+function newestUpdated(items) {
+    let newest = null;
+    for (const it of items) {
+        const u = it.updated;
+        if (typeof u === "string" && (newest === null || u > newest))
+            newest = u;
+    }
+    return newest;
+}
 /** Distinct, sorted category values — read off the content, never hand-listed. */
 function categoriesOf(items) {
     return [...new Set(items.map((e) => e.category).filter((c) => Boolean(c)))].sort();
@@ -168,6 +184,14 @@ function stem(token) {
     return token;
 }
 /** Relative importance of each field when scoring a search hit. */
+/**
+ * Cuánto puede sumar como mucho la centralidad. Por debajo del peso de un
+ * acierto en título (6) a propósito: desempata y matiza dentro de un empate,
+ * nunca adelanta a una unidad que acertó más términos de la consulta.
+ */
+const CENTRALITY_NUDGE = 1.5;
+/** Satura: pasar de 0 a 4 enlaces importa; de 40 a 44, ya no. */
+const centralityBonus = (inbound) => CENTRALITY_NUDGE * (inbound / (inbound + 4));
 const FIELD_WEIGHTS = {
     name: 6,
     slug: 5,
@@ -215,6 +239,7 @@ function buildSearchFields(entry) {
         name: norm(names.join(" ")),
         slug: norm(entry.slug ?? ""),
         id: norm(str(raw.id)),
+        aliases: norm(arr(raw.aliases)),
         summary: norm(summaries.join(" ")),
         category: norm(entry.category ?? ""),
         keyConcepts: norm(concepts.join(" ")),
@@ -432,8 +457,70 @@ function summarizeHomeric(kind, e, locale) {
         api_url: `${SITE_URL}/api/homeric/${kind}/${e.slug}`,
     };
 }
-export function makeContent(loadAll, loadHandbook, loadHomeric) {
+export function makeContent(loadAll, loadHandbook, loadHomeric, loadClaims) {
     const getOne = (domain, slug) => loadAll(domain).find((e) => e.slug === slug);
+    /**
+     * Enlaces entrantes por unidad — la única señal de centralidad que este
+     * corpus ya tiene, y la que decide un empate de puntuación.
+     *
+     * Para una consulta de una palabra, toda unidad que la lleve en el título
+     * saca exactamente la misma nota: "memory" empataba 4 unidades y "harness" 7,
+     * y el orden lo resolvía `localeCompare`. Cuál es la canónica no está en el
+     * texto — está en quién apunta a quién.
+     *
+     * Cuenta TODAS las aristas declaradas, incluidas las del manual, que
+     * referencia por identificador (`HRN-003`, `GOV-001`, `ARCH-001`) y no por
+     * slug: medirlo solo sobre los cuatro dominios JSON dejaba a los 14 capítulos
+     * a cero por artefacto y habría hundido el manual entero fingiendo que era
+     * una señal.
+     */
+    let inboundCache = null;
+    const inboundLinks = () => {
+        if (inboundCache)
+            return inboundCache;
+        const bySlug = new Map(); // ARCH-001 / HRN-003 -> slug
+        const entries = [];
+        for (const domain of DOMAINS) {
+            for (const e of loadAll(domain)) {
+                entries.push(e);
+                const id = e.id;
+                if (typeof id === "string")
+                    bySlug.set(id.toUpperCase(), e.slug);
+                const aliases = e.aliases;
+                if (Array.isArray(aliases)) {
+                    for (const alias of aliases)
+                        if (typeof alias === "string")
+                            bySlug.set(alias.toUpperCase(), e.slug);
+                }
+            }
+        }
+        if (loadHandbook) {
+            for (const c of loadHandbook()) {
+                entries.push(c);
+                if (c.id)
+                    bySlug.set(String(c.id).toUpperCase(), c.slug);
+            }
+        }
+        const inb = new Map();
+        for (const e of entries) {
+            for (const field of ["related", "patterns", "knowledge", "architectures", "governance"]) {
+                const refs = e[field];
+                if (!Array.isArray(refs))
+                    continue;
+                for (const r of refs) {
+                    if (typeof r !== "string")
+                        continue;
+                    // Una referencia que no resuelve acaba bajo una clave que ninguna
+                    // unidad tiene, así que no confiere centralidad a nadie. Quien avisa
+                    // de que existen es `npm run validate`, no esto.
+                    const slug = bySlug.get(r.toUpperCase()) ?? r;
+                    inb.set(slug, (inb.get(slug) ?? 0) + 1);
+                }
+            }
+        }
+        inboundCache = inb;
+        return inb;
+    };
     const card = (d, e, locale, type) => ({
         type,
         ...summarize(d, e, locale),
@@ -463,6 +550,15 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                 license_url: LICENSE_INFO.url,
                 total: domains.reduce((n, d) => n + d.count, 0),
                 domains,
+                corpus: {
+                    newest_unit: newestUpdated([
+                        ...DOMAINS.flatMap((d) => loadAll(d)),
+                        ...(loadHandbook ? loadHandbook() : []),
+                    ]),
+                    freshness: `This describes the copy answering the call. ${SITE_URL}/mcp is redeployed on ` +
+                        "every content change; a published package carries the corpus frozen at publish " +
+                        "time. If total or newest_unit differ from that endpoint's, you are holding a snapshot.",
+                },
                 next: "search(query, locale) to answer a question across the whole corpus; " +
                     "list_<domain> to browse one; get_<domain>(slug) for a full unit with its " +
                     "Evidence-First provenance; get_related(domain, slug) to traverse the graph. " +
@@ -472,6 +568,12 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                     llms_full_txt: `${SITE_URL}/llms-full.txt`,
                     graph: `${SITE_URL}/api/graph.json`,
                     homeric_atlas: `${SITE_URL}/api/homeric-atlas.json`,
+                    articles: "https://articles.santismm.com/llms-full.txt",
+                    articles_index: "https://articles.santismm.com/ai-index.json",
+                    articles_api: "https://articles.santismm.com/api/articles.json",
+                    labs: "https://labs.santismm.com/llms-full.txt",
+                    labs_api: "https://labs.santismm.com/api/labs",
+                    labs_openapi: "https://labs.santismm.com/openapi.json",
                 },
             };
         },
@@ -513,11 +615,13 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
             // measured across the corpus actually being searched.
             const wantHandbook = domains.includes("handbook");
             const structured = domains.filter((d) => d !== "handbook");
+            const inb = inboundLinks();
             const docs = [];
             for (const domain of structured) {
                 for (const entry of loadAll(domain)) {
                     docs.push({
                         fields: searchFields(entry),
+                        slug: entry.slug,
                         card: () => summarize(domain, entry, locale),
                     });
                 }
@@ -528,6 +632,7 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                 for (const e of loadHandbook()) {
                     docs.push({
                         fields: handbookFields(e),
+                        slug: e.slug,
                         card: () => summarizeHandbook(e, locale),
                     });
                 }
@@ -546,12 +651,54 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
             const scored = [];
             for (const d of docs) {
                 const hit = scoreEntry(d.fields, tokens, idf);
-                if (hit)
-                    scored.push({ ...d.card(), ...hit });
+                if (!hit)
+                    continue;
+                // La centralidad se suma DESPUÉS de puntuar el texto: decide entre
+                // unidades que ya empataron por relevancia, no compite con ella.
+                const score = Math.round((hit.score + centralityBonus(inb.get(d.slug) ?? 0)) * 100) / 100;
+                scored.push({ ...d.card(), ...hit, score });
             }
             scored.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
             return scored.slice(0, limit);
         },
+        /**
+         * Claims (ADR 0003). The card carries the type and the confidence, because
+         * that is the whole point: an agent must be able to tell an observed fact
+         * from a bet without reading the prose and guessing.
+         */
+        listClaims(type, locale = "en") {
+            if (!loadClaims)
+                return [];
+            return loadClaims()
+                .filter((c) => !type || c.claimType === type)
+                // Orden estable por id: el del directorio no lo es, y un listado que
+                // cambia de orden entre llamadas es un listado en el que no se confía.
+                .sort((a, b) => String(a.id).localeCompare(String(b.id)))
+                .map((c) => {
+                const L = (c.locales ?? {})[locale] ?? {};
+                return {
+                    type: "claim",
+                    id: c.id,
+                    slug: c.slug,
+                    claim_type: c.claimType,
+                    confidence_level: c.confidenceLevel,
+                    statement: L.statement,
+                    supports: c.supports,
+                    reviewed: c.reviewed,
+                };
+            });
+        },
+        /** By `HE-CLAIM-nnn` or slug: an agent that saw either can come back. */
+        getClaim(id, locale = "en") {
+            if (!loadClaims)
+                return undefined;
+            const key = String(id).toUpperCase();
+            const c = loadClaims().find((x) => String(x.id).toUpperCase() === key || x.slug === id);
+            if (!c)
+                return undefined;
+            const L = (c.locales ?? {})[locale] ?? {};
+            return { type: "claim", ...c, body: L };
+        },
         listHomeric(kind, locale = "en") {
             if (!loadHomeric)
                 return [];

package/dist/tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ARTICLES_API_URL, articleCard, articlesForLocale, loadArticles, searchArticleCorpus, } from "./articles.js";
 /**
  * Single, framework-agnostic definition of the Santismm Knowledge MCP server:
  * its identity and the tool registry. Both transports — the stdio CLI
@@ -7,11 +8,12 @@ import { z } from "zod";
  * between them. The data source is injected as `content` (an `McpContent`
  * provider); both providers read the same `content/{domain}/*.json` files.
  */
-export const SERVER_INFO = { name: "santismm-knowledge", version: "0.2.1" };
+export const SERVER_INFO = { name: "santismm-knowledge", version: "0.3.0" };
 /**
- * Every tool here reads a static corpus and nothing else, so all four hints are
- * literally true rather than aspirational: nothing mutates, the same arguments
- * always produce the same answer, and no tool reaches outside this corpus.
+ * Core tools read a static local corpus, so all four hints are literally true:
+ * nothing mutates, the same arguments produce the same answer, and no core
+ * tool reaches outside this corpus. Federated Article tools override only the
+ * open-world hint because they read another first-party origin.
  *
  * Declaring them matters because a client deciding whether a call needs
  * confirmation, and an aggregator deciding how to present the server, both read
@@ -24,6 +26,8 @@ const READ_ONLY = {
     idempotentHint: true,
     openWorldHint: false,
 };
+/** Article tools read another first-party origin, so clients must know they are open-world. */
+const READ_ONLY_REMOTE = { ...READ_ONLY, openWorldHint: true };
 const localeSchema = z
     .enum(["en", "es", "pt"])
     .optional()
@@ -122,6 +126,8 @@ const unitOutput = z.object({
     domain: z.string().optional(),
     id: z.string().optional(),
     slug: z.string().optional(),
+    /** Legacy identifiers that resolve to this canonical unit. */
+    aliases: z.array(z.string()).optional(),
     category: z.string().optional(),
     updated: z.string().optional(),
     version: z.string().optional(),
@@ -223,6 +229,8 @@ const ESPACIOS = [
     { domain: "homeric/places", listTool: "list_homeric_places", getTool: "get_homeric_place" },
     { domain: "homeric/episodes", listTool: "list_homeric_episodes", getTool: "get_homeric_episode" },
     { domain: "homeric/routes", listTool: "list_homeric_routes", getTool: "get_homeric_route" },
+    { domain: "claims", listTool: "list_claims", getTool: "get_claim" },
+    { domain: "articles", listTool: "list_articles", getTool: "get_article" },
 ];
 /** Every identifier a card answers to: its id (handbook chapters) and its slug. */
 function identificadores(cards) {
@@ -240,8 +248,14 @@ function identificadores(cards) {
 }
 /** The cards of one space, whichever loader serves it. */
 function cardsDe(content, domain, locale) {
+    // Federated Articles are asynchronous and have their own recovery payload;
+    // keep them out of the synchronous cross-space lookup used by local units.
+    if (domain === "articles")
+        return [];
     if (domain === "handbook")
         return content.listHandbook(locale);
+    if (domain === "claims")
+        return content.listClaims(undefined, locale);
     if (domain.startsWith("homeric/")) {
         return content.listHomeric(domain.slice("homeric/".length), locale);
     }
@@ -349,6 +363,26 @@ function noEncontrado(content, domain, pedido, locale) {
         pistas.push(`${espacio.listTool} returns every identifier this tool accepts.`);
     }
     pistas.push("Identifiers are not interchangeable between spaces; do not invent one by analogy.");
+    /**
+     * The third reason a lookup fails, and the one this answer could not express.
+     *
+     * A published package carries the corpus frozen at publish time, so an agent
+     * holding one gets `not_found` for a unit that exists — and everything above
+     * tells it, truthfully but misleadingly, that the identifier is not in the
+     * corpus. Stating the date of this copy turns that into something the caller
+     * can check instead of a dead end wearing a helpful face.
+     */
+    try {
+        const fecha = content.overview().corpus.newest_unit;
+        if (fecha) {
+            cuerpo.corpus_newest_unit = fecha;
+            pistas.push(`This copy holds nothing newer than ${fecha}. If the unit was added after that, ` +
+                "a package snapshot is the reason and the hosted endpoint has it.");
+        }
+    }
+    catch {
+        // La recuperación nunca puede ser la que rompa la respuesta.
+    }
     cuerpo.hint = pistas.join(" ");
     return {
         content: [{ type: "text", text: JSON.stringify(cuerpo, null, 2) }],
@@ -396,6 +430,77 @@ const homericListOutput = {
     results: z.array(homericCard),
 };
 const homericUnitOutput = z.object({}).passthrough();
+/**
+ * Claims get their own shape for the same reason the atlas does: forcing them
+ * into the corpus card would mean inventing an `evidence` block they do not
+ * have. A claim is not a unit with provenance — it IS the provenance, and what
+ * it carries instead is the rung of the ladder it sits on.
+ */
+const claimCard = z.object({
+    type: z.literal("claim"),
+    id: z.string(),
+    slug: z.string(),
+    claim_type: z.enum(["observed_fact", "industry_synthesis", "santismm_thesis", "strategic_hypothesis"]),
+    confidence_level: z.string(),
+    statement: z.string().optional(),
+    supports: z.array(z.string()),
+    reviewed: z.string(),
+});
+const claimListOutput = { count: z.number(), results: z.array(claimCard) };
+const claimUnitOutput = z.object({}).passthrough();
+const articleCardSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+    summary: z.string(),
+    language: z.string(),
+    published: z.string(),
+    modified: z.string(),
+    topics: z.array(z.string()),
+    translation_key: z.string().optional(),
+    canonical_url: z.string().describe("Cite this URL."),
+    api_url: z.string(),
+});
+const articleUnitOutput = articleCardSchema.extend({
+    body: z.string().describe("Full Markdown-like article body."),
+});
+const articleListOutput = { count: z.number(), results: z.array(articleCardSchema) };
+const articleSearchOutput = {
+    query: z.string(),
+    count: z.number(),
+    results: z.array(articleCardSchema.extend({
+        score: z.number(),
+        matchedFields: z.array(z.string()),
+        matchedTerms: z.array(z.string()),
+    })),
+};
+function articleFailure(error) {
+    const body = {
+        error: "articles_unavailable",
+        source: ARTICLES_API_URL,
+        hint: "The first-party Articles API could not be read. Retry later or use its llms-full.txt corpus directly.",
+        detail: error instanceof Error ? error.message : String(error),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+        isError: true,
+    };
+}
+function articleNotFound(articles, slug) {
+    const available = articles.map((article) => article.slug).sort();
+    const body = {
+        error: "not_found",
+        domain: "articles",
+        slug,
+        available_count: available.length,
+        available,
+        list_tool: "list_articles",
+        hint: "Call list_articles for every valid slug; article slugs are not interchangeable with core corpus identifiers.",
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+        isError: true,
+    };
+}
 export function registerTools(server, content) {
     // ── Orientation ────────────────────────────────────────────────────────────
     server.registerTool("get_overview", {
@@ -421,6 +526,12 @@ export function registerTools(server, content) {
                 url: z.string(),
                 api_url: z.string(),
             })),
+            corpus: z
+                .object({
+                newest_unit: z.string().nullable().describe("Newest unit date in THIS copy (YYYY-MM-DD)."),
+                freshness: z.string(),
+            })
+                .describe("Whether this copy is current. Compare against the hosted endpoint: a lower total or an older newest_unit means you are holding a snapshot, not that the corpus lacks what you asked for."),
             next: z.string(),
             bulk: z.record(z.string(), z.string()),
         }),
@@ -545,6 +656,61 @@ export function registerTools(server, content) {
         const results = content.search(query, domains, limit ?? 20, (locale ?? "en"));
         return outList(results, { query });
     });
+    // ── First-party articles (federated) ─────────────────────────────────────
+    server.registerTool("list_articles", {
+        title: "List first-party essays",
+        annotations: READ_ONLY_REMOTE,
+        description: "List every long-form essay published on articles.santismm.com, with language, dates, topics and citable canonical URLs. Use this to browse the essay catalogue; use `search_articles` when you have a topic rather than a slug.",
+        inputSchema: z.object({
+            locale: localeSchema.describe("Restrict to en, es or pt. Omit to return every language."),
+        }),
+        outputSchema: articleListOutput,
+    }, async ({ locale }) => {
+        try {
+            const articles = articlesForLocale(await loadArticles(), locale);
+            return outList(articles.map(articleCard));
+        }
+        catch (error) {
+            return articleFailure(error);
+        }
+    });
+    server.registerTool("get_article", {
+        title: "Get a first-party essay",
+        annotations: READ_ONLY_REMOTE,
+        description: "Get one complete essay by slug, including its clean Markdown-like body, metadata, licence context and canonical URL. Use this after `list_articles` or `search_articles` has returned the slug you need.",
+        inputSchema: z.object({
+            slug: slugSchema.describe("Article slug, e.g. 'the-stopwatch-and-the-exam'."),
+        }),
+        outputSchema: articleUnitOutput,
+    }, async ({ slug }) => {
+        try {
+            const articles = await loadArticles();
+            const article = articles.find((candidate) => candidate.slug === slug);
+            return article ? out(article) : articleNotFound(articles, slug);
+        }
+        catch (error) {
+            return articleFailure(error);
+        }
+    });
+    server.registerTool("search_articles", {
+        title: "Search first-party essays",
+        annotations: READ_ONLY_REMOTE,
+        description: "Ranked, accent-insensitive full-text search over every first-party essay, including titles, summaries, topics and bodies. Use this when you need long-form analysis about a topic; follow with `get_article` for the complete essay.",
+        inputSchema: z.object({
+            query: querySchema.describe("Keyword or phrase to search for in any supported language."),
+            locale: localeSchema.describe("Restrict to en, es or pt. Omit to search every language."),
+            limit: z.number().int().positive().max(20).optional().describe("Maximum results (default 10)."),
+        }),
+        outputSchema: articleSearchOutput,
+    }, async ({ query, locale, limit }) => {
+        try {
+            const articles = articlesForLocale(await loadArticles(), locale);
+            return outList(searchArticleCorpus(articles, query, limit ?? 10), { query });
+        }
+        catch (error) {
+            return articleFailure(error);
+        }
+    });
     // ── Graph traversal ────────────────────────────────────────────────────────
     server.registerTool("get_related", {
         title: "Traverse the Knowledge Graph",
@@ -629,6 +795,38 @@ export function registerTools(server, content) {
         const entry = content.getHomeric("routes", slug, locale);
         return entry ? out(entry) : noEncontrado(content, "homeric/routes", slug, (locale ?? "en"));
     });
+    // ── Claims (ADR 0003) ────────────────────────────────────────────────────
+    // Everything else in this server answers "what does the corpus say?". These
+    // two answer "how strongly, and on what?" — which of the corpus's statements
+    // are observed fact, which are a reading of the industry, which are our own
+    // position and which are a bet. Without them an agent has to infer the
+    // epistemic status from prose, and prose does not distinguish those.
+    server.registerTool("list_claims", {
+        title: "List the corpus claims and their epistemic status",
+        annotations: READ_ONLY,
+        description: "List the load-bearing claims of the corpus, each tagged as observed_fact, industry_synthesis, santismm_thesis or strategic_hypothesis, with its confidence and the units it underpins. Use this before quoting the handbook to know whether a statement is evidence, a reading of the industry, or a position taken. Filter by `claim_type` to get only what is checkable.",
+        inputSchema: z.object({
+            claim_type: z
+                .enum(["observed_fact", "industry_synthesis", "santismm_thesis", "strategic_hypothesis"])
+                .optional()
+                .describe("Restrict to one rung of the ladder. Omit for all."),
+            locale: localeSchema,
+        }),
+        outputSchema: claimListOutput,
+    }, async ({ claim_type, locale }) => outList(content.listClaims(claim_type, (locale ?? "en"))));
+    server.registerTool("get_claim", {
+        title: "Get one claim with its limits and what would refute it",
+        annotations: READ_ONLY,
+        description: "Get one claim by id (HE-CLAIM-001) or slug: the statement, what it rests on, its structured sources, and — always present — what it does NOT establish and the observation that would retire it. Use this to cite the corpus honestly, or to check whether a result you have just measured confirms or falsifies a claim it makes.",
+        inputSchema: z.object({
+            id: z.string().describe("Claim id (e.g. 'HE-CLAIM-001') or slug."),
+            locale: localeSchema,
+        }),
+        outputSchema: claimUnitOutput,
+    }, async ({ id, locale }) => {
+        const c = content.getClaim(id, locale);
+        return c ? out(c) : noEncontrado(content, "claims", id, (locale ?? "en"));
+    });
 }
 /**
  * The tools this server exposes, as advertised metadata (name + description).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "santismm-knowledge-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "MCP server for the Santismm Knowledge Platform — harness engineering, agentic AI patterns, reference architectures and AI governance. Ships the corpus; the hosted endpoint at https://santismm.com/mcp is the always-fresh alternative.",
   "type": "module",