santismm-knowledge-mcp 0.2.2 → 0.4.0

package/dist/labs.js

@@ -0,0 +1,134 @@
+/**
+ * Federated SANTISMM Labs catalogue and deterministic calculators.
+ *
+ * Labs owns the formulas and executes them. The knowledge MCP deliberately
+ * proxies the canonical API instead of copying arithmetic into this package:
+ * one formula version serves the interactive UI, REST callers and MCP agents.
+ */
+export const LABS_API_URL = process.env.SANTISMM_LABS_API_URL ?? 'https://labs.santismm.com/api/labs';
+const LABS_SERVICE_ORIGIN = new URL(LABS_API_URL).origin;
+const LABS_CANONICAL_ORIGIN = 'https://labs.santismm.com';
+const CACHE_TTL_MS = 5 * 60 * 1000;
+let cache;
+let pending;
+function strings(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function validLab(value) {
+    const lab = value;
+    return Boolean(lab &&
+        typeof lab.slug === 'string' &&
+        ['calculator', 'converter', 'experiment', 'educational-game'].includes(String(lab.kind)) &&
+        typeof lab.label === 'string' &&
+        typeof lab.title === 'string' &&
+        typeof lab.description === 'string' &&
+        strings(lab.inputs) &&
+        strings(lab.outputs) &&
+        (lab.formulas === undefined || strings(lab.formulas)) &&
+        strings(lab.assumptions) &&
+        typeof lab.version === 'string' &&
+        typeof lab.updated === 'string' &&
+        typeof lab.canonical_url === 'string' &&
+        lab.canonical_url.startsWith(`${LABS_CANONICAL_ORIGIN}/`) &&
+        typeof lab.api_url === 'string' &&
+        lab.api_url.startsWith(`${LABS_CANONICAL_ORIGIN}/api/labs/`) &&
+        (lab.calculation_url === undefined || lab.calculation_url.startsWith(`${LABS_CANONICAL_ORIGIN}/api/calculate/`)));
+}
+async function fetchCorpus() {
+    const response = await fetch(LABS_API_URL, {
+        headers: { Accept: 'application/json', 'User-Agent': 'santismm-knowledge-mcp/0.4.0' },
+        signal: AbortSignal.timeout(8_000),
+        cache: 'no-store',
+    });
+    if (!response.ok)
+        throw new Error(`Labs API returned HTTP ${response.status}`);
+    const raw = await response.json();
+    if (raw.source !== 'SANTISMM Labs' ||
+        typeof raw.canonical_url !== 'string' ||
+        !Array.isArray(raw.results) ||
+        !raw.results.every(validLab) ||
+        raw.count !== raw.results.length) {
+        throw new Error('Labs API returned an invalid catalogue contract');
+    }
+    return raw;
+}
+export async function loadLabs() {
+    if (cache && cache.expiresAt > Date.now())
+        return cache.corpus.results;
+    if (!pending) {
+        pending = fetchCorpus()
+            .then((corpus) => {
+            cache = { expiresAt: Date.now() + CACHE_TTL_MS, corpus };
+            return corpus;
+        })
+            .finally(() => {
+            pending = undefined;
+        });
+    }
+    return (await pending).results;
+}
+function normalise(value) {
+    return value.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+}
+export function searchLabCorpus(labs, query, limit) {
+    const terms = [...new Set(normalise(query).split(/[^a-z0-9]+/).filter((term) => term.length > 1))];
+    const phrase = normalise(query).trim();
+    if (terms.length === 0)
+        return [];
+    const fields = [
+        ['title', 8], ['slug', 7], ['description', 6], ['inputs', 4], ['outputs', 4],
+        ['formulas', 3], ['assumptions', 2], ['kind', 1],
+    ];
+    return labs
+        .map((lab) => {
+        const matchedFields = new Set();
+        const matchedTerms = new Set();
+        let score = 0;
+        for (const [field, weight] of fields) {
+            const raw = lab[field];
+            const value = normalise(Array.isArray(raw) ? raw.join(' ') : String(raw ?? ''));
+            for (const term of terms) {
+                if (!value.includes(term))
+                    continue;
+                score += weight;
+                matchedFields.add(field);
+                matchedTerms.add(term);
+            }
+            if (phrase.length > 2 && value.includes(phrase))
+                score += weight * 2;
+        }
+        return { ...lab, score, matchedFields: [...matchedFields], matchedTerms: [...matchedTerms] };
+    })
+        .filter((lab) => lab.score > 0)
+        .sort((a, b) => b.score - a.score || b.updated.localeCompare(a.updated) || a.slug.localeCompare(b.slug))
+        .slice(0, limit);
+}
+export async function executeLabCalculator(slug, inputs) {
+    const response = await fetch(`${LABS_SERVICE_ORIGIN}/api/calculate/${slug}`, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'User-Agent': 'santismm-knowledge-mcp/0.4.0',
+        },
+        body: JSON.stringify(inputs),
+        signal: AbortSignal.timeout(8_000),
+        cache: 'no-store',
+    });
+    const raw = await response.json();
+    if (!response.ok) {
+        const message = typeof raw.error === 'string' ? raw.error : `HTTP ${response.status}`;
+        throw new Error(`Labs calculator ${slug} failed: ${message}`);
+    }
+    if (raw.slug !== slug ||
+        typeof raw.version !== 'string' ||
+        typeof raw.canonical_url !== 'string' ||
+        typeof raw.api_url !== 'string' ||
+        typeof raw.inputs !== 'object' ||
+        typeof raw.results !== 'object' ||
+        !Array.isArray(raw.assumptions) ||
+        !Array.isArray(raw.warnings)) {
+        throw new Error(`Labs calculator ${slug} returned an invalid result contract`);
+    }
+    return raw;
+}

package/dist/shape.js

@@ -184,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,
@@ -231,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(" ")),
@@ -448,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),
@@ -479,6 +550,49 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                 license_url: LICENSE_INFO.url,
                 total: domains.reduce((n, d) => n + d.count, 0),
                 domains,
+                extensions: [
+                    {
+                        surface: "articles",
+                        description: "Federated first-party long-form essays, read from their canonical Articles API at call time.",
+                        tools: ["list_articles", "get_article", "search_articles"],
+                        source: "https://articles.santismm.com/api/articles.json",
+                        lookup: "article slug",
+                        citation: "Each result carries canonical_url.",
+                    },
+                    {
+                        surface: "homeric_atlas",
+                        description: "Places, episodes and rival route reconstructions using the atlas identification vocabulary and 0–12 rubric.",
+                        tools: [
+                            "list_homeric_places", "get_homeric_place",
+                            "list_homeric_episodes", "get_homeric_episode",
+                            "list_homeric_routes", "get_homeric_route",
+                        ],
+                        source: `${SITE_URL}/api/homeric-atlas.json`,
+                        lookup: "place, episode or route slug",
+                        citation: "Each content result carries canonical_url and api_url.",
+                    },
+                    {
+                        surface: "claims",
+                        description: "The corpus's load-bearing claims with epistemic type, confidence, basis, limitations and falsification criteria.",
+                        tools: ["list_claims", "get_claim"],
+                        source: "bundled claim registry",
+                        lookup: "claim id (for example HE-CLAIM-001) or slug",
+                        citation: "Claims have no public page; cite their stable id and the MCP endpoint.",
+                    },
+                    {
+                        surface: "labs",
+                        description: "Interactive calculators, converters, experiments and educational games; three calculators execute deterministic, versioned formulas through the canonical Labs API.",
+                        tools: [
+                            "list_labs", "get_lab",
+                            "calculate_agent_economics",
+                            "calculate_evaluation_sample_size",
+                            "calculate_human_supervision_capacity",
+                        ],
+                        source: "https://labs.santismm.com/api/labs",
+                        lookup: "Lab slug; executable tools take typed numeric assumptions",
+                        citation: "Definitions and calculation results carry canonical_url, api_url, version, assumptions and warnings.",
+                    },
+                ],
                 corpus: {
                     newest_unit: newestUpdated([
                         ...DOMAINS.flatMap((d) => loadAll(d)),
@@ -488,15 +602,23 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                         "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; " +
+                next: "search_all(query, locale) when a question may need core knowledge, an essay, a Lab calculation or a claim audit; " +
+                    "search(query, locale) to search only the five-domain core; " +
                     "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. " +
-                    "Every result carries canonical_url and api_url, so cite the canonical_url.",
+                    "Use the tools named in extensions for Articles, the Homeric Atlas and claims. " +
+                    "Citable content results carry canonical_url; claim records use their stable id.",
                 // For agents that would rather ingest the corpus than walk it.
                 bulk: {
                     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",
                 },
             };
         },
@@ -538,11 +660,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),
                     });
                 }
@@ -553,6 +677,7 @@ export function makeContent(loadAll, loadHandbook, loadHomeric) {
                 for (const e of loadHandbook()) {
                     docs.push({
                         fields: handbookFields(e),
+                        slug: e.slug,
                         card: () => summarizeHandbook(e, locale),
                     });
                 }
@@ -571,12 +696,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 [];