santismm-knowledge-mcp 0.2.2 → 0.4.0

package/dist/tools.js

@@ -1,17 +1,21 @@
 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.2.2" };
+export const SERVER_INFO = { name: "santismm-knowledge", version: "0.4.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 +28,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 +128,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 +231,9 @@ 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" },
+    { domain: "labs", listTool: "list_labs", getTool: "get_lab" },
 ];
 /** Every identifier a card answers to: its id (handbook chapters) and its slug. */
 function identificadores(cards) {
@@ -240,8 +251,14 @@ function identificadores(cards) {
 }
 /** The cards of one space, whichever loader serves it. */
 function cardsDe(content, domain, locale) {
+    // 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);
+    if (domain === "claims")
+        return content.listClaims(undefined, locale);
     if (domain.startsWith("homeric/")) {
         return content.listHomeric(domain.slice("homeric/".length), locale);
     }
@@ -416,12 +433,242 @@ 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()),
+    })),
+};
+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",
+        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,
+    };
+}
+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(),
@@ -441,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)."),
@@ -451,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",
@@ -571,6 +931,167 @@ 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);
+        }
+    });
+    // ── 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",
@@ -655,6 +1176,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,8 +1,8 @@
 {
   "name": "santismm-knowledge-mcp",
-  "version": "0.2.2",
+  "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"