santismm-knowledge-mcp 0.3.0 → 0.4.0

package/README.md

@@ -2,8 +2,8 @@
 
 [![santismm-knowledge-mcp MCP server](https://glama.ai/mcp/servers/santismm/santismm-knowledge-mcp/badges/card.svg)](https://glama.ai/mcp/servers/santismm/santismm-knowledge-mcp)
 
-> MCP server for the Santismm Knowledge Platform — harness engineering, agentic
-> AI patterns, reference architectures, AI governance and the agent taxonomy.
+> MCP server for the Santismm Knowledge Platform — five core knowledge domains,
+> first-party essays, Homeric Atlas datasets and epistemic claims.
 
 **This repository is generated** from the platform at [santismm.com](https://santismm.com).
 Do not edit it by hand; changes are overwritten on the next sync. Corrections go
@@ -68,7 +68,7 @@ is not a software licence and MIT is not a content licence.
 
 ## What it exposes
 
-24 read-only tools over knowledge, patterns, architectures, governance, the
+30 read-only tools over knowledge, patterns, architectures, governance, the
 Harness Engineering Handbook and first-party Articles, each declaring an
 `outputSchema` and returning validated `structuredContent`. Every tool is
 annotated `readOnlyHint: true`, `destructiveHint: false` and

package/dist/articles.js

@@ -30,7 +30,7 @@ function validArticle(value) {
 }
 async function fetchCorpus() {
     const response = await fetch(ARTICLES_API_URL, {
-        headers: { Accept: "application/json", "User-Agent": "santismm-knowledge-mcp/0.3.0" },
+        headers: { Accept: "application/json", "User-Agent": "santismm-knowledge-mcp/0.4.0" },
         signal: AbortSignal.timeout(8_000),
         cache: "no-store",
     });

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

@@ -550,6 +550,49 @@ export function makeContent(loadAll, loadHandbook, loadHomeric, loadClaims) {
                 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)),
@@ -559,10 +602,12 @@ export function makeContent(loadAll, loadHandbook, loadHomeric, loadClaims) {
                         "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`,

package/dist/tools.js

@@ -1,14 +1,16 @@
 import { z } from "zod";
 import { ARTICLES_API_URL, articleCard, articlesForLocale, loadArticles, searchArticleCorpus, } from "./articles.js";
+import { LABS_API_URL, executeLabCalculator, loadLabs, searchLabCorpus, } from "./labs.js";
 /**
  * Single, framework-agnostic definition of the Santismm Knowledge MCP server:
  * its identity and the tool registry. Both transports — the stdio CLI
  * (`mcp/src/index.ts`) and the HTTP endpoint (`app/mcp/route.ts`) — call
  * `registerTools(server, content)`, so the exposed tools can never drift
- * between them. The data source is injected as `content` (an `McpContent`
- * provider); both providers read the same `content/{domain}/*.json` files.
+ * between them. The local data source is injected as `content` (an
+ * `McpContent` provider); both providers read the same canonical repository
+ * data, while Article tools deliberately read the first-party Articles API.
  */
-export const SERVER_INFO = { name: "santismm-knowledge", version: "0.3.0" };
+export const SERVER_INFO = { name: "santismm-knowledge", version: "0.4.0" };
 /**
  * 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
@@ -231,6 +233,7 @@ const ESPACIOS = [
     { 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" },
+    { domain: "labs", listTool: "list_labs", getTool: "get_lab" },
 ];
 /** Every identifier a card answers to: its id (handbook chapters) and its slug. */
 function identificadores(cards) {
@@ -248,9 +251,9 @@ 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")
+    // Federated Articles and Labs are asynchronous and have their own recovery
+    // payloads; keep them out of the synchronous cross-space lookup for locals.
+    if (domain === "articles" || domain === "labs")
         return [];
     if (domain === "handbook")
         return content.listHandbook(locale);
@@ -473,6 +476,94 @@ const articleSearchOutput = {
         matchedTerms: z.array(z.string()),
     })),
 };
+const relatedContentSchema = z.object({
+    title: z.string(),
+    url: z.string(),
+    relationship: z.string(),
+});
+const labCardSchema = z.object({
+    slug: z.string(),
+    kind: z.enum(["calculator", "converter", "experiment", "educational-game"]),
+    label: z.string(),
+    title: z.string(),
+    description: z.string(),
+    inputs: z.array(z.string()),
+    outputs: z.array(z.string()),
+    formulas: z.array(z.string()).optional(),
+    assumptions: z.array(z.string()),
+    version: z.string(),
+    updated: z.string(),
+    canonical_url: z.string().describe("Cite this URL."),
+    api_url: z.string(),
+    calculation_url: z.string().optional(),
+    related_content: z.array(relatedContentSchema).optional(),
+});
+const labListOutput = { count: z.number(), results: z.array(labCardSchema) };
+const calculationBaseSchema = z.object({
+    schema_version: z.string(),
+    source: z.string(),
+    language: z.string(),
+    slug: z.string(),
+    version: z.string(),
+    updated: z.string(),
+    canonical_url: z.string().describe("Cite this URL."),
+    api_url: z.string(),
+    methodology_url: z.string(),
+    inputs: z.record(z.string(), z.number()),
+    units: z.record(z.string(), z.string()),
+    interpretation: z.string(),
+    assumptions: z.array(z.string()),
+    formulas: z.array(z.string()),
+    warnings: z.array(z.string()),
+    license: z.object({ name: z.string(), spdx: z.string(), url: z.string() }),
+});
+const agentEconomicsOutput = calculationBaseSchema.extend({
+    results: z.object({
+        attempts: z.number(), executionCost: z.number(), reviewCost: z.number(), failedCases: z.number(),
+        reworkCost: z.number(), operatingCost: z.number(), manualCost: z.number(), savings: z.number(),
+        roi: z.number(), successfulOutcomes: z.number(), costPerSuccess: z.number(), costPerResolved: z.number(),
+        breakEvenSuccess: z.number(),
+        verdict: z.object({ tone: z.enum(["positive", "watch", "negative"]), title: z.string(), body: z.string() }),
+    }),
+});
+const evaluationSampleOutput = calculationBaseSchema.extend({
+    results: z.object({ detect: z.number(), estimate: z.number(), expected: z.number(), zero: z.number() }),
+});
+const humanSupervisionOutput = calculationBaseSchema.extend({
+    results: z.object({
+        routine: z.number(), escalations: z.number(), workload: z.number(), productivePerFte: z.number(),
+        requiredFte: z.number(), headroom: z.number(), cost: z.number(), backlogDays: z.number(),
+        sustainableVolume: z.number(),
+    }),
+});
+const globalSearchCard = z.object({
+    surface: z.enum(["core", "articles", "labs", "claims"]),
+    score: z.number(),
+    source_score: z.number(),
+    rank_within_surface: z.number(),
+    id: z.string().optional(),
+    slug: z.string(),
+    domain: z.string().optional(),
+    kind: z.string().optional(),
+    title: z.string(),
+    summary: z.string().optional(),
+    canonical_url: z.string().optional(),
+    api_url: z.string().optional(),
+    calculation_url: z.string().optional(),
+    suggested_tool: z.string(),
+    matchedFields: z.array(z.string()),
+    matchedTerms: z.array(z.string()),
+}).passthrough();
+const globalSearchOutput = {
+    query: z.string(),
+    count: z.number(),
+    results: z.array(globalSearchCard),
+    unavailable_surfaces: z.array(z.object({
+        surface: z.enum(["articles", "labs"]),
+        error: z.string(),
+        retry_tool: z.string(),
+    })),
+};
 function articleFailure(error) {
     const body = {
         error: "articles_unavailable",
@@ -501,12 +592,83 @@ function articleNotFound(articles, slug) {
         isError: true,
     };
 }
+function labsFailure(error) {
+    const body = {
+        error: "labs_unavailable",
+        source: LABS_API_URL,
+        hint: "The first-party Labs API could not be read. Retry later or bind directly to its OpenAPI document.",
+        detail: error instanceof Error ? error.message : String(error),
+    };
+    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], isError: true };
+}
+function globalSearchFailure(error) {
+    const body = {
+        error: "federated_search_unavailable",
+        hint: "One federated source could not be read. Retry search_all with a restricted surfaces array, or use search for the local core corpus.",
+        detail: error instanceof Error ? error.message : String(error),
+    };
+    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], isError: true };
+}
+function labNotFound(labs, slug) {
+    const available = labs.map((lab) => lab.slug).sort();
+    const body = {
+        error: "not_found",
+        domain: "labs",
+        slug,
+        available_count: available.length,
+        available,
+        list_tool: "list_labs",
+        hint: "Call list_labs for every valid slug. Only Labs with calculation_url can be executed.",
+    };
+    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }], isError: true };
+}
+function termsFor(query) {
+    return [...new Set(query.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 1))];
+}
+function claimSearch(content, query, locale, limit) {
+    const terms = termsFor(query);
+    return content.listClaims(undefined, locale)
+        .map((claim) => {
+        const fields = [["statement", 7], ["slug", 6], ["id", 5], ["claim_type", 4]];
+        let score = 0;
+        const matchedFields = new Set();
+        const matchedTerms = new Set();
+        for (const [field, weight] of fields) {
+            const value = String(claim[field] ?? "").normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase();
+            for (const term of terms) {
+                if (!value.includes(term))
+                    continue;
+                score += weight;
+                matchedFields.add(field);
+                matchedTerms.add(term);
+            }
+        }
+        return { claim, score, matchedFields: [...matchedFields], matchedTerms: [...matchedTerms] };
+    })
+        .filter((hit) => hit.score > 0)
+        .sort((a, b) => b.score - a.score || String(a.claim.id).localeCompare(String(b.claim.id)))
+        .slice(0, limit);
+}
+const GET_TOOL_FOR_DOMAIN = {
+    knowledge: "get_knowledge", patterns: "get_pattern", architectures: "get_architecture",
+    governance: "get_governance", handbook: "get_handbook",
+};
+function intentBoost(query, surface) {
+    const normal = termsFor(query).join(" ");
+    if (surface === "labs" && /\b(calcul\w*|how many|cuant\w*|sample|muestra|roi|cost\w*|coste\w*|supervis\w*|fte|capacity|capacidad|break even|token\w*|pages|paginas)\b/.test(normal))
+        return 30;
+    if (surface === "claims" && /\b(claim|claims|evidence|fact|thesis|tesis|hypothesis|hipotesis|falsif|refut)\b/.test(normal))
+        return 25;
+    if (surface === "articles" && /\b(article|articles|essay|essays|articulo|artículo|ensayo|recent|latest|nuevo|reciente)\b/.test(normal))
+        return 20;
+    return 0;
+}
 export function registerTools(server, content) {
     // ── Orientation ────────────────────────────────────────────────────────────
     server.registerTool("get_overview", {
         title: "Corpus Overview — Start Here",
         annotations: READ_ONLY,
-        description: "Get the corpus map — start here. Returns every domain (knowledge, patterns, architectures, governance and the Harness Engineering Handbook) with what it holds, the categories inside it, which tool retrieves a unit and what identifier that tool expects, plus the languages, licence and bulk-ingest URLs. One call is enough to know exactly where to go next.",
+        description: "Get the complete MCP map — start here. Returns the five-domain core plus the separate Article, Labs, Homeric Atlas and claim-registry surfaces, with their tools, identifiers, citation rules, languages, licence and bulk-ingest URLs.",
         inputSchema: z.object({}),
         outputSchema: z.object({
             source: z.string(),
@@ -526,6 +688,14 @@ export function registerTools(server, content) {
                 url: z.string(),
                 api_url: z.string(),
             })),
+            extensions: z.array(z.object({
+                surface: z.string(),
+                description: z.string(),
+                tools: z.array(z.string()),
+                source: z.string(),
+                lookup: z.string(),
+                citation: z.string(),
+            })),
             corpus: z
                 .object({
                 newest_unit: z.string().nullable().describe("Newest unit date in THIS copy (YYYY-MM-DD)."),
@@ -536,6 +706,111 @@ export function registerTools(server, content) {
             bulk: z.record(z.string(), z.string()),
         }),
     }, async () => out({ ...content.overview() }));
+    server.registerTool("search_all", {
+        title: "Search every SANTISMM knowledge surface",
+        annotations: READ_ONLY_REMOTE,
+        description: "Search the core corpus, first-party essays, executable Labs and epistemic claims in one call. Use this first when a natural-language question might require a calculation, a long-form essay or a claim audit rather than only a core knowledge unit. Results name the next tool to call; calculator-shaped questions are routed toward Labs.",
+        inputSchema: z.object({
+            query: querySchema.describe("Question or topic, in English, Spanish or Portuguese."),
+            surfaces: z.array(z.enum(["core", "articles", "labs", "claims"])).min(1).optional()
+                .describe("Restrict the search. Omit to search all four surfaces."),
+            limit_per_surface: z.number().int().positive().max(10).optional().describe("Maximum hits from each surface. Default: 5."),
+            locale: localeSchema,
+        }),
+        outputSchema: z.object(globalSearchOutput),
+    }, async ({ query, surfaces, limit_per_surface, locale }) => {
+        try {
+            const selected = new Set(surfaces ?? ["core", "articles", "labs", "claims"]);
+            const limit = limit_per_surface ?? 5;
+            const lang = (locale ?? "en");
+            const [articleLoad, labLoad] = await Promise.allSettled([
+                selected.has("articles") ? loadArticles() : Promise.resolve([]),
+                selected.has("labs") ? loadLabs() : Promise.resolve([]),
+            ]);
+            const unavailableSurfaces = [];
+            const articles = articleLoad.status === "fulfilled" ? articleLoad.value : [];
+            const labs = labLoad.status === "fulfilled" ? labLoad.value : [];
+            if (selected.has("articles") && articleLoad.status === "rejected") {
+                unavailableSurfaces.push({
+                    surface: "articles",
+                    error: articleLoad.reason instanceof Error ? articleLoad.reason.message : String(articleLoad.reason),
+                    retry_tool: "search_articles",
+                });
+            }
+            if (selected.has("labs") && labLoad.status === "rejected") {
+                unavailableSurfaces.push({
+                    surface: "labs",
+                    error: labLoad.reason instanceof Error ? labLoad.reason.message : String(labLoad.reason),
+                    retry_tool: "list_labs",
+                });
+            }
+            const hits = [];
+            if (selected.has("core")) {
+                const boost = intentBoost(query, "core");
+                for (const [index, raw] of content.search(query, undefined, limit, lang).entries()) {
+                    const sourceScore = Number(raw.score ?? 0);
+                    hits.push({
+                        ...raw,
+                        surface: "core",
+                        score: sourceScore + boost,
+                        source_score: sourceScore,
+                        rank_within_surface: index + 1,
+                        title: String(raw.name ?? raw.slug ?? ""),
+                        suggested_tool: GET_TOOL_FOR_DOMAIN[String(raw.domain)] ?? "search",
+                        matchedFields: raw.matchedFields ?? [],
+                        matchedTerms: raw.matchedTerms ?? [],
+                    });
+                }
+            }
+            if (selected.has("articles")) {
+                const boost = intentBoost(query, "articles");
+                for (const [index, raw] of searchArticleCorpus(articles, query, limit).entries()) {
+                    hits.push({
+                        surface: "articles", score: raw.score + boost, source_score: raw.score,
+                        rank_within_surface: index + 1, slug: raw.slug, title: raw.title, summary: raw.summary,
+                        canonical_url: raw.canonical_url, api_url: raw.api_url, suggested_tool: "get_article",
+                        matchedFields: raw.matchedFields, matchedTerms: raw.matchedTerms,
+                    });
+                }
+            }
+            if (selected.has("labs")) {
+                const boost = intentBoost(query, "labs");
+                const calculatorTools = {
+                    "agent-economics": "calculate_agent_economics",
+                    "evaluation-sample-size": "calculate_evaluation_sample_size",
+                    "human-supervision-capacity": "calculate_human_supervision_capacity",
+                };
+                for (const [index, raw] of searchLabCorpus(labs, query, limit).entries()) {
+                    hits.push({
+                        surface: "labs", score: raw.score + boost, source_score: raw.score,
+                        rank_within_surface: index + 1, slug: raw.slug, kind: raw.kind, title: raw.title,
+                        summary: raw.description, canonical_url: raw.canonical_url, api_url: raw.api_url,
+                        calculation_url: raw.calculation_url,
+                        suggested_tool: calculatorTools[raw.slug] ?? "get_lab",
+                        matchedFields: raw.matchedFields, matchedTerms: raw.matchedTerms,
+                    });
+                }
+            }
+            if (selected.has("claims")) {
+                const boost = intentBoost(query, "claims");
+                for (const [index, raw] of claimSearch(content, query, lang, limit).entries()) {
+                    const claim = raw.claim;
+                    hits.push({
+                        surface: "claims", score: raw.score + boost, source_score: raw.score,
+                        rank_within_surface: index + 1, id: claim.id, slug: claim.slug,
+                        kind: claim.claim_type, title: String(claim.statement ?? claim.slug),
+                        summary: `Epistemic type: ${String(claim.claim_type)}; confidence: ${String(claim.confidence_level)}.`,
+                        suggested_tool: "get_claim", matchedFields: raw.matchedFields, matchedTerms: raw.matchedTerms,
+                    });
+                }
+            }
+            hits.sort((a, b) => Number(b.score) - Number(a.score) || Number(a.rank_within_surface) - Number(b.rank_within_surface));
+            return out({ query, count: hits.length, results: hits, unavailable_surfaces: unavailableSurfaces }, hits);
+        }
+        catch (error) {
+            return globalSearchFailure(error);
+        }
+    });
     // ── Knowledge base ─────────────────────────────────────────────────────────
     server.registerTool("list_knowledge", {
         title: "List Agentic AI Knowledge Units",
@@ -711,6 +986,112 @@ export function registerTools(server, content) {
             return articleFailure(error);
         }
     });
+    // ── SANTISMM Labs (federated metadata + deterministic execution) ─────────
+    server.registerTool("list_labs", {
+        title: "List calculators, converters, experiments and educational Labs",
+        annotations: READ_ONLY_REMOTE,
+        description: "List every SANTISMM Lab with its inputs, outputs, assumptions, formulas and citation URL. Use this to discover interactive and machine-readable tools; filter by kind when the user specifically asks for a calculator, converter, experiment or educational game.",
+        inputSchema: z.object({
+            kind: z.enum(["calculator", "converter", "experiment", "educational-game"]).optional(),
+        }),
+        outputSchema: z.object(labListOutput),
+    }, async ({ kind }) => {
+        try {
+            const labs = await loadLabs();
+            return outList(kind ? labs.filter((lab) => lab.kind === kind) : labs);
+        }
+        catch (error) {
+            return labsFailure(error);
+        }
+    });
+    server.registerTool("get_lab", {
+        title: "Get one SANTISMM Lab definition",
+        annotations: READ_ONLY_REMOTE,
+        description: "Get one Lab by slug, including formulas, assumptions, related SANTISMM content and its executable endpoint when one exists. Use this after list_labs or search_all; use the named calculate_* tool rather than reimplementing a published formula.",
+        inputSchema: z.object({ slug: slugSchema.describe("Lab slug, e.g. 'evaluation-sample-size'.") }),
+        outputSchema: labCardSchema,
+    }, async ({ slug }) => {
+        try {
+            const labs = await loadLabs();
+            const lab = labs.find((candidate) => candidate.slug === slug);
+            return lab ? out(lab) : labNotFound(labs, slug);
+        }
+        catch (error) {
+            return labsFailure(error);
+        }
+    });
+    server.registerTool("calculate_agent_economics", {
+        title: "Calculate the operational economics of an AI agent",
+        annotations: READ_ONLY_REMOTE,
+        description: "Calculate monthly operating cost, cost per verified outcome, manual baseline, savings, ROI and break-even success rate from explicit assumptions. Use this for an agent business case or scenario comparison; keep every monetary input in the same currency and cite the returned canonical_url.",
+        inputSchema: z.object({
+            monthlyVolume: z.number().min(0).max(1_000_000_000).describe("Cases attempted per month."),
+            manualMinutes: z.number().min(0).max(10_080).describe("Manual handling time per case."),
+            hourlyCost: z.number().min(0).max(1_000_000).describe("Fully loaded human hourly cost, in the chosen currency."),
+            inputTokens: z.number().min(0).max(100_000_000).describe("Input tokens per agent attempt."),
+            outputTokens: z.number().min(0).max(100_000_000).describe("Output tokens per agent attempt."),
+            inputPrice: z.number().min(0).max(1_000_000).describe("Model input price per million tokens, in the chosen currency."),
+            outputPrice: z.number().min(0).max(1_000_000).describe("Model output price per million tokens, in the chosen currency."),
+            toolCost: z.number().min(0).max(1_000_000).describe("External tool cost per attempt."),
+            retryRate: z.number().min(0).max(500).describe("Extra attempts as a percentage of initial volume."),
+            successRate: z.number().min(1).max(100).describe("Correctly verified outcomes as a percentage of cases."),
+            reviewRate: z.number().min(0).max(100).describe("Share of cases reviewed by a person."),
+            reviewMinutes: z.number().min(0).max(10_080).describe("Human review minutes per reviewed case."),
+            reworkMinutes: z.number().min(0).max(10_080).describe("Human rework minutes per failed case."),
+        }),
+        outputSchema: agentEconomicsOutput,
+    }, async (inputs) => {
+        try {
+            return out(await executeLabCalculator("agent-economics", inputs));
+        }
+        catch (error) {
+            return labsFailure(error);
+        }
+    });
+    server.registerTool("calculate_evaluation_sample_size", {
+        title: "Calculate an agent evaluation sample size",
+        annotations: READ_ONLY_REMOTE,
+        description: "Calculate two different samples: how many independent evaluations are needed to detect at least one failure, and how many are needed to estimate its rate at a chosen margin. Use this when a user asks how many tests are enough; do not interpret zero observed failures as proof of zero risk.",
+        inputSchema: z.object({
+            failureRate: z.number().min(0.0001).max(99.9999).describe("Failure rate to detect, in percent."),
+            confidence: z.union([z.literal(90), z.literal(95), z.literal(99)]).describe("Confidence level, in percent."),
+            margin: z.number().min(0.1).max(50).describe("Margin for estimating the failure rate, in percentage points."),
+            population: z.number().min(1).max(1_000_000_000).describe("Number of distinct evaluable cases."),
+        }),
+        outputSchema: evaluationSampleOutput,
+    }, async (inputs) => {
+        try {
+            return out(await executeLabCalculator("evaluation-sample-size", inputs));
+        }
+        catch (error) {
+            return labsFailure(error);
+        }
+    });
+    server.registerTool("calculate_human_supervision_capacity", {
+        title: "Calculate human supervision capacity for an AI agent",
+        annotations: READ_ONLY_REMOTE,
+        description: "Calculate review and escalation workload, required FTE, available headroom or backlog, monthly labour cost and sustainable case volume. Use this before production rollout to test whether the stated human-oversight model is operationally credible; the result uses averages and is not a queueing simulation.",
+        inputSchema: z.object({
+            volume: z.number().min(0).max(1_000_000_000).describe("Agent cases per month."),
+            sample: z.number().min(0).max(100).describe("Share of all cases selected for routine review, in percent."),
+            reviewMinutes: z.number().min(0).max(10_080).describe("Minutes per routine review."),
+            escalationRate: z.number().min(0).max(100).describe("Share of cases escalated, in percent."),
+            escalationMinutes: z.number().min(0).max(10_080).describe("Minutes per escalation."),
+            workdays: z.number().min(1).max(31).describe("Working days per month."),
+            hoursDay: z.number().min(0.1).max(24).describe("Paid hours per working day."),
+            utilization: z.number().min(1).max(100).describe("Share of paid time available for review and escalation, in percent."),
+            reviewers: z.number().min(0.1).max(1_000_000).describe("Available reviewer FTE."),
+            hourlyCost: z.number().min(0).max(1_000_000).describe("Fully loaded reviewer hourly cost, in the chosen currency."),
+        }),
+        outputSchema: humanSupervisionOutput,
+    }, async (inputs) => {
+        try {
+            return out(await executeLabCalculator("human-supervision-capacity", inputs));
+        }
+        catch (error) {
+            return labsFailure(error);
+        }
+    });
     // ── Graph traversal ────────────────────────────────────────────────────────
     server.registerTool("get_related", {
         title: "Traverse the Knowledge Graph",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "santismm-knowledge-mcp",
-  "version": "0.3.0",
+  "version": "0.4.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.",
+  "description": "MCP server for the Santismm Knowledge Platform — core knowledge, first-party essays, Homeric Atlas datasets and epistemic claims. Ships the core corpus; the hosted endpoint at https://santismm.com/mcp is the always-fresh alternative.",
   "type": "module",
   "bin": {
     "santismm-knowledge-mcp": "dist/index.js"