@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/tool-exposure.d.ts

@@ -1,9 +1,9 @@
 /**
  * Tool-exposure profile for the Frihet MCP server — progressive disclosure.
  *
- * Activated by FRIHET_TOOL_MODE=grouped (env var or Worker binding).
- * Default (unset, or FRIHET_TOOL_MODE=full) leaves the server BYTE-IDENTICAL
- * to today: all 157 tools registered with their full descriptions/schemas.
+ * Activated by FRIHET_TOOL_MODE=grouped (env var or Worker binding). Default
+ * full mode keeps full descriptions/schemas and does not add discovery names;
+ * the outer public composition may still attach capability truth metadata.
  *
  * ── Why ──────────────────────────────────────────────────────────────────
  * Context rot is the 2026 problem: a flat list of 157 tool descriptions,
@@ -23,10 +23,10 @@
  *      the server.
  *   2. Still registers every tool so it stays INVOCABLE (nothing breaks; tool
  *      logic, names and behavior are untouched) — but COLLAPSES its registered
- *      description to a single terse "[group] summary — full schema via
- *      describe_tool('name')" line. That is the context saving.
+ *      description to a single terse "[group] summary — full description and
+ *      input fields via describe_tool('name')" line. That is the context saving.
  *   3. Adds three lightweight META-TOOLS as the entry point for discovery:
- *        • list_tool_groups()      — the 9-domain map with per-group counts
+ *        • list_tool_groups()      — the 11-domain map with per-group counts
  *        • search_tools(query)     — fuzzy match → matching tool summaries
  *        • describe_tool(name)     — full original description + input fields
  *
@@ -42,7 +42,7 @@
  */
 /** Stable domain identifiers used by the group router. */
 export type ToolGroupId = "invoicing" | "expenses" | "fiscal" | "banking" | "crm" | "hr" | "stay" | "pos" | "intelligence" | "catalog" | "platform";
-interface GroupMeta {
+export interface GroupMeta {
     /** Human label, bilingual. */
     label: string;
     /** One-line domain blurb shown in list_tool_groups. */
@@ -81,6 +81,10 @@ interface CatalogEntry {
     description: string;
     /** Whether the tool mutates state (from annotations.readOnlyHint). */
     readOnly: boolean;
+    /** Full MCP action annotations, exposed only on the full capability profile. */
+    annotations?: Record<string, boolean>;
+    /** Conservative runtime capability fact, exposed only on the full profile. */
+    capability?: Record<string, unknown>;
     /** Input field names, for quick schema shape without dumping zod. */
     inputFields: string[];
 }
@@ -118,25 +122,24 @@ export declare function resolveToolMode(env?: Record<string, string | undefined>
  * @param server  The McpServer (typed loosely to match the openai-profile shim).
  * @param options.allowlist  When provided, ONLY tools whose name is in this set
  *   are catalogued + collapsed; any other tool is passed through untouched.
- *   This is the OpenAI-composition path: it pins the grouped catalog (and the
- *   tools search_tools / describe_tool / list_tool_groups surface) to EXACTLY
- *   the reviewed allow-list, so progressive disclosure can never reveal or
- *   describe a tool outside the 53-tool ChatGPT-reviewed surface. Omit (default)
- *   for the open mcp.frihet.io surface, which catalogs every registered tool.
- *
- *   COMPOSITION ORDERING (openai-mcp): apply this profile FIRST so its
- *   originalRegisterTool is the REAL server.registerTool — the three meta-tools
- *   are then registered straight onto the real server and BYPASS the OpenAI
- *   allow-list gate entirely (so they always materialise without polluting the
- *   OpenAI includeTools set / its advertised 53-tool count). Apply
- *   applyOpenAIProfile() SECOND (outermost) so a business-tool registration is
- *   first redacted + annotated + openWorldHint-justified by OpenAI, and only
- *   THEN collapsed here — making the terse line the final description while the
- *   OpenAI redaction wrapper around the handler survives intact.
+ *   This supports a deliberately restricted grouped surface without allowing
+ *   discovery to reveal or describe tools outside that surface. Omit (default)
+ *   for mcp.frihet.io, which catalogs every registered tool. The reviewed
+ *   OpenAI host does not use grouped exposure: it publishes the exact 33-tool
+ *   allow-list with complete descriptions and no discovery meta-tools.
  * @returns a handle exposing the live catalog (useful for tests/logging).
  */
 export declare function applyToolExposureProfile(server: any, options?: {
     allowlist?: ReadonlySet<string>;
+    groupMetadata?: Partial<Record<ToolGroupId, GroupMeta>>;
+    capabilityTruth?: {
+        metaKey: string;
+        localDiscovery: (name: string) => object;
+    };
+    securitySchemes?: ReadonlyArray<{
+        type: "oauth2";
+        scopes: readonly string[];
+    }>;
 }): ToolExposureHandle;
 /** Number of meta-tools added in grouped mode (for logging). */
 export declare const GROUPED_META_TOOL_COUNT: number;

package/dist/tool-exposure.js

@@ -1,9 +1,9 @@
 /**
  * Tool-exposure profile for the Frihet MCP server — progressive disclosure.
  *
- * Activated by FRIHET_TOOL_MODE=grouped (env var or Worker binding).
- * Default (unset, or FRIHET_TOOL_MODE=full) leaves the server BYTE-IDENTICAL
- * to today: all 157 tools registered with their full descriptions/schemas.
+ * Activated by FRIHET_TOOL_MODE=grouped (env var or Worker binding). Default
+ * full mode keeps full descriptions/schemas and does not add discovery names;
+ * the outer public composition may still attach capability truth metadata.
  *
  * ── Why ──────────────────────────────────────────────────────────────────
  * Context rot is the 2026 problem: a flat list of 157 tool descriptions,
@@ -23,10 +23,10 @@
  *      the server.
  *   2. Still registers every tool so it stays INVOCABLE (nothing breaks; tool
  *      logic, names and behavior are untouched) — but COLLAPSES its registered
- *      description to a single terse "[group] summary — full schema via
- *      describe_tool('name')" line. That is the context saving.
+ *      description to a single terse "[group] summary — full description and
+ *      input fields via describe_tool('name')" line. That is the context saving.
  *   3. Adds three lightweight META-TOOLS as the entry point for discovery:
- *        • list_tool_groups()      — the 9-domain map with per-group counts
+ *        • list_tool_groups()      — the 11-domain map with per-group counts
  *        • search_tools(query)     — fuzzy match → matching tool summaries
  *        • describe_tool(name)     — full original description + input fields
  *
@@ -53,7 +53,11 @@ export const GROUPS = {
     },
     expenses: {
         label: "Expenses & vendors / Gastos y proveedores",
-        blurb: "Expenses (with OCR) and vendor/supplier records.",
+        // C38: this used to read "Expenses (with OCR)". No OCR tool exists — the
+        // expenses family is list/get/create/update/delete plus vendor CRUD, and
+        // create_expense takes no file, image or URL. Do NOT re-add a capability
+        // token here that search_tools cannot resolve to a real tool.
+        blurb: "Expenses and vendor/supplier records.",
     },
     fiscal: {
         label: "Fiscal & compliance / Fiscal y cumplimiento",
@@ -204,6 +208,43 @@ function firstSentence(desc) {
     // Hard cap so a runaway description can't reintroduce context bloat.
     return sentence.length > 160 ? sentence.slice(0, 157).trimEnd() + "…" : sentence;
 }
+function inputSchemaFieldNames(schema) {
+    if (schema instanceof z.ZodObject) {
+        return Object.keys(schema.shape);
+    }
+    if (schema !== null && typeof schema === "object" && !Array.isArray(schema)) {
+        return Object.keys(schema);
+    }
+    return [];
+}
+/**
+ * Does this tool declare `confirm` as a REQUIRED input?
+ *
+ * Handles both a raw registration shape and a strict ZodObject. The latter is
+ * used by create_expense; looking only at `schema["confirm"]` made its required
+ * confirmation disappear from the collapsed tools/list description.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────
+ * `firstSentence` keeps only the opening sentence, so a confirm requirement
+ * stated in sentence two vanished from every collapsed listing: all 12
+ * confirm-gated tools shipped a description that never mentioned the input the
+ * SDK rejects the call for. The agent then reads "Delete an invoice by its ID",
+ * calls `{id}`, and gets an input-validation error with no prose basis to
+ * recover. Deriving the marker here fixes every present AND future guarded tool
+ * at once — the alternative (editing 12 first sentences by hand) is the same
+ * enumerate-instead-of-derive mistake GAP-04 was raised for.
+ */
+function requiresConfirm(inputSchema) {
+    const shape = inputSchema instanceof z.ZodObject
+        ? inputSchema.shape
+        : inputSchema;
+    if (!shape || typeof shape !== "object")
+        return false;
+    const field = shape["confirm"];
+    if (typeof field?.safeParse !== "function")
+        return false;
+    return field.safeParse(undefined).success === false;
+}
 /**
  * Read process.env without referencing the `process` global type — keeps this
  * module compilable in environments without @types/node (e.g. the Cloudflare
@@ -242,21 +283,11 @@ export function resolveToolMode(env = defaultEnv()) {
  * @param server  The McpServer (typed loosely to match the openai-profile shim).
  * @param options.allowlist  When provided, ONLY tools whose name is in this set
  *   are catalogued + collapsed; any other tool is passed through untouched.
- *   This is the OpenAI-composition path: it pins the grouped catalog (and the
- *   tools search_tools / describe_tool / list_tool_groups surface) to EXACTLY
- *   the reviewed allow-list, so progressive disclosure can never reveal or
- *   describe a tool outside the 53-tool ChatGPT-reviewed surface. Omit (default)
- *   for the open mcp.frihet.io surface, which catalogs every registered tool.
- *
- *   COMPOSITION ORDERING (openai-mcp): apply this profile FIRST so its
- *   originalRegisterTool is the REAL server.registerTool — the three meta-tools
- *   are then registered straight onto the real server and BYPASS the OpenAI
- *   allow-list gate entirely (so they always materialise without polluting the
- *   OpenAI includeTools set / its advertised 53-tool count). Apply
- *   applyOpenAIProfile() SECOND (outermost) so a business-tool registration is
- *   first redacted + annotated + openWorldHint-justified by OpenAI, and only
- *   THEN collapsed here — making the terse line the final description while the
- *   OpenAI redaction wrapper around the handler survives intact.
+ *   This supports a deliberately restricted grouped surface without allowing
+ *   discovery to reveal or describe tools outside that surface. Omit (default)
+ *   for mcp.frihet.io, which catalogs every registered tool. The reviewed
+ *   OpenAI host does not use grouped exposure: it publishes the exact 33-tool
+ *   allow-list with complete descriptions and no discovery meta-tools.
  * @returns a handle exposing the live catalog (useful for tests/logging).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -267,6 +298,13 @@ server, options) {
     const groups = new Map();
     const handle = { catalog, groups };
     const allowlist = options?.allowlist;
+    const visibleGroupIds = allowlist
+        ? TOOL_GROUP_IDS.filter((group) => [...allowlist].some((name) => groupForTool(name) === group))
+        : [...TOOL_GROUP_IDS];
+    const groupMetadata = Object.fromEntries(TOOL_GROUP_IDS.map((id) => [
+        id,
+        options?.groupMetadata?.[id] ?? GROUPS[id],
+    ]));
     const originalRegisterTool = server.registerTool.bind(server);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     server.registerTool = (name, config, handler) => {
@@ -286,10 +324,12 @@ server, options) {
         }
         const group = groupForTool(name);
         const fullDescription = typeof config?.description === "string" ? config.description : "";
-        const inputFields = config?.inputSchema
-            ? Object.keys(config.inputSchema)
-            : [];
+        const inputFields = inputSchemaFieldNames(config?.inputSchema);
         const readOnly = config?.annotations?.readOnlyHint === true;
+        const annotations = config?.annotations;
+        const capability = options?.capabilityTruth
+            ? config?._meta?.[options.capabilityTruth.metaKey]
+            : undefined;
         const entry = {
             name,
             group,
@@ -297,6 +337,7 @@ server, options) {
             summary: firstSentence(fullDescription),
             description: fullDescription,
             readOnly,
+            ...(options?.capabilityTruth ? { annotations, capability } : {}),
             inputFields,
         };
         catalog.set(name, entry);
@@ -313,27 +354,41 @@ server, options) {
         // a per-tool open-world justification on EVERY reviewed tool). When composed
         // with the OpenAI profile, that profile runs first (outermost) and has
         // already set the correct annotations.openWorldHint (e.g. true for
-        // send_invoice / send_quote / create_webhook / update_webhook). We re-derive
+        // send_invoice). We re-derive
         // the one-line rationale here from the (now-correct) annotation so the terse
         // collapsed description carries it — instead of letting the OpenAI-injected
         // rationale be lost when we overwrite config.description. Only appended in
         // allow-list (composition) mode; the open mcp.frihet.io surface keeps its
         // pure terse line (no OpenAI review constraint there).
+        // A required `confirm` is the single most consequential thing an agent can
+        // miss: omit it and the call dies on schema validation with no prose basis
+        // to recover. firstSentence() keeps only the first English sentence, so a
+        // "Requires confirm=true." written into sentence 2 of a tool description is
+        // invisible on the surface the agent actually loads. Derive the marker from
+        // the SCHEMA instead of trusting prose — it then covers every confirm-gated
+        // tool, including ones added after this line was written.
+        //
+        // In OpenAI mode this is deliberately load-bearing: the reviewed schema
+        // keeps `confirm` visible and required, so the collapsed tools/list line
+        // tells the agent to obtain explicit authorization before invoking it.
         let collapsed = `[${group}] ${entry.summary} ` +
-            `— full schema via describe_tool('${name}').`;
+            (requiresConfirm(config?.inputSchema) ? "Requires confirm=true. " : "") +
+            `— full description and input fields via describe_tool('${name}').`;
         if (allowlist) {
             const ow = config?.annotations?.openWorldHint;
-            collapsed +=
-                ow === true
-                    ? " [openWorldHint: true — contacts an entity outside Frihet (an email recipient or an external webhook URL).]"
-                    : " [openWorldHint: false — operates only against the Frihet API (api.frihet.io); no third-party/external calls.]";
+            const explicitRationale = fullDescription.match(/\[openWorldHint:\s*(?:true|false)\s+—[^\]]+\]/u)?.[0];
+            collapsed += explicitRationale
+                ? ` ${explicitRationale}`
+                : ow === true
+                    ? " [openWorldHint: true — may interact with an external endpoint disclosed in describe_tool.]"
+                    : " [openWorldHint: false — has no user-directed external effect; it only reads or changes the authenticated Frihet workspace.]";
         }
         config.description = collapsed;
         return originalRegisterTool(name, config, handler);
     };
     // Register the meta-tools eagerly. Their handlers close over `catalog`/`groups`
     // which finish populating as the real tools register right after this call.
-    registerMetaTools(originalRegisterTool, handle);
+    registerMetaTools(originalRegisterTool, handle, visibleGroupIds, groupMetadata, options?.capabilityTruth, options?.securitySchemes);
     return handle;
 }
 /* ------------------------------------------------------------------ */
@@ -363,29 +418,111 @@ function textResult(payload) {
  */
 function registerMetaTools(
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-originalRegisterTool, handle) {
+originalRegisterTool, handle, visibleGroupIds, groupMetadata, capabilityTruth, securitySchemes) {
     const { catalog, groups } = handle;
+    const oauthConfig = securitySchemes
+        ? {
+            securitySchemes: securitySchemes.map((scheme) => ({
+                type: scheme.type,
+                scopes: [...scheme.scopes],
+            })),
+        }
+        : {};
+    const metaConfig = (name) => {
+        const metadata = {};
+        if (securitySchemes) {
+            metadata.securitySchemes = securitySchemes.map((scheme) => ({
+                type: scheme.type,
+                scopes: [...scheme.scopes],
+            }));
+        }
+        if (capabilityTruth) {
+            metadata[capabilityTruth.metaKey] = capabilityTruth.localDiscovery(name);
+        }
+        return Object.keys(metadata).length > 0 ? { _meta: metadata } : {};
+    };
+    const searchToolsInputShape = {
+        query: z
+            .string()
+            .optional()
+            .describe("Free-text query — matches tool name, title, summary and group. " +
+            "Omit to browse a whole group. / Texto libre; omitir para listar un grupo entero."),
+        group: z
+            .enum(visibleGroupIds)
+            .optional()
+            .describe("Restrict results to one tool domain / Filtrar por dominio."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Max results (default 25) / Máximo de resultados (por defecto 25)."),
+    };
+    const describeToolInputShape = {
+        name: z
+            .string()
+            .describe("Exact tool name as returned by search_tools (e.g. 'create_invoice') / " +
+            "Nombre exacto de la herramienta devuelto por search_tools."),
+    };
+    const listGroupsOutput = securitySchemes
+        ? z.object({
+            groups: z.array(z.object({
+                group: z.enum(visibleGroupIds),
+                label: z.string(),
+                blurb: z.string(),
+                toolCount: z.number().int().nonnegative(),
+            })),
+            totalGroups: z.number().int().nonnegative(),
+            totalTools: z.number().int().nonnegative(),
+            next: z.string(),
+        })
+        : z.object({}).passthrough();
+    const searchToolsOutput = securitySchemes
+        ? z.object({
+            query: z.string().nullable(),
+            group: z.enum(visibleGroupIds).nullable(),
+            count: z.number().int().nonnegative(),
+            tools: z.array(z.object({
+                name: z.string(),
+                group: z.enum(visibleGroupIds),
+                title: z.string(),
+                summary: z.string(),
+                readOnly: z.boolean(),
+                inputFields: z.array(z.string()),
+                score: z.number().int().nonnegative(),
+            })),
+            next: z.string(),
+        })
+        : z.object({}).passthrough();
+    const describeToolOutput = securitySchemes
+        ? z.object({
+            name: z.string(),
+            group: z.enum(visibleGroupIds),
+            title: z.string(),
+            readOnly: z.boolean(),
+            inputFields: z.array(z.string()),
+            description: z.string(),
+        })
+        : z.object({}).passthrough();
     // -- list_tool_groups --
     originalRegisterTool("list_tool_groups", {
         title: "List tool groups",
-        description: "List the Frihet ERP tool domains (invoicing, expenses, fiscal/compliance, banking, CRM, " +
-            "HR/payroll, stay/PMS, POS, intelligence, products, platform) with a one-line blurb and tool " +
+        ...oauthConfig,
+        ...metaConfig("list_tool_groups"),
+        description: `List the available Frihet tool domains (${visibleGroupIds.join(", ")}) with a one-line blurb and tool ` +
             "count for each. Start here, then use search_tools(query) to find tools and describe_tool(name) " +
-            "for a tool's full schema. Frihet serves deep ES/EU fiscal + native compliance on demand. " +
+            "for a tool's full description and input fields. Only domains present in this reviewed connector are listed. " +
             "[openWorldHint: false — reads the in-process tool catalog only.] " +
             "/ Lista los dominios de herramientas de Frihet ERP con descripción y recuento. Empieza aquí.",
         annotations: META_ANNOTATIONS,
-        inputSchema: {},
-        outputSchema: z
-            .object({})
-            .passthrough()
-            .describe("Tool domains with per-group blurb and tool count / Dominios de herramientas con descripción y recuento"),
+        inputSchema: securitySchemes ? z.object({}).strict() : {},
+        outputSchema: listGroupsOutput.describe("Tool domains with per-group blurb and tool count / Dominios de herramientas con descripción y recuento"),
     }, async () => {
-        const out = Object.keys(GROUPS)
+        const out = visibleGroupIds
             .map((id) => ({
             group: id,
-            label: GROUPS[id].label,
-            blurb: GROUPS[id].blurb,
+            label: groupMetadata[id].label,
+            blurb: groupMetadata[id].blurb,
             toolCount: groups.get(id)?.length ?? 0,
         }))
             .filter((g) => g.toolCount > 0);
@@ -393,12 +530,14 @@ originalRegisterTool, handle) {
             groups: out,
             totalGroups: out.length,
             totalTools: catalog.size,
-            next: "search_tools(query) to find tools; describe_tool(name) for full schema.",
+            next: "search_tools(query) to find tools; describe_tool(name) for full description and input fields.",
         });
     });
     // -- search_tools --
     originalRegisterTool("search_tools", {
         title: "Search tools",
+        ...oauthConfig,
+        ...metaConfig("search_tools"),
         description: "Find Frihet ERP tools by free-text query (matches tool name, title, summary and group). " +
             "Returns matching tools with their group, one-line summary, read-only flag and input field names — " +
             "progressive disclosure so you load only what you need. Optionally filter by group. " +
@@ -406,27 +545,10 @@ originalRegisterTool, handle) {
             "[openWorldHint: false — reads the in-process tool catalog only.] " +
             "/ Busca herramientas por texto libre. Devuelve coincidencias con grupo, resumen y campos.",
         annotations: META_ANNOTATIONS,
-        inputSchema: {
-            query: z
-                .string()
-                .optional()
-                .describe("Free-text query — matches tool name, title, summary and group. " +
-                "Omit to browse a whole group. / Texto libre; omitir para listar un grupo entero."),
-            group: z
-                .enum(TOOL_GROUP_IDS)
-                .optional()
-                .describe("Restrict results to one tool domain / Filtrar por dominio."),
-            limit: z
-                .number()
-                .int()
-                .positive()
-                .optional()
-                .describe("Max results (default 25) / Máximo de resultados (por defecto 25)."),
-        },
-        outputSchema: z
-            .object({})
-            .passthrough()
-            .describe("Matching tools with group, summary, read-only flag and input fields / Herramientas coincidentes con grupo, resumen y campos"),
+        inputSchema: securitySchemes
+            ? z.object(searchToolsInputShape).strict()
+            : searchToolsInputShape,
+        outputSchema: searchToolsOutput.describe("Matching tools with group, summary, read-only flag and input fields / Herramientas coincidentes con grupo, resumen y campos"),
     }, 
     // The SDK passes parsed args; we read defensively to stay schema-light.
     async (args = {}) => {
@@ -461,6 +583,8 @@ originalRegisterTool, handle) {
             title: e.title,
             summary: e.summary,
             readOnly: e.readOnly,
+            ...(e.annotations ? { annotations: e.annotations } : {}),
+            ...(e.capability ? { capability: e.capability } : {}),
             inputFields: e.inputFields,
             score,
         }));
@@ -469,28 +593,24 @@ originalRegisterTool, handle) {
             group: groupFilter ?? null,
             count: scored.length,
             tools: scored,
-            next: "describe_tool(name) for full schema, then call the tool by its real name.",
+            next: "describe_tool(name) for full description and input fields, then call the tool by its real name.",
         });
     });
     // -- describe_tool --
     originalRegisterTool("describe_tool", {
         title: "Describe tool",
+        ...oauthConfig,
+        ...metaConfig("describe_tool"),
         description: "Return the full original description, group, read-only flag and input field names for a specific " +
             "Frihet ERP tool by its exact name (as returned by search_tools). Use this to load a tool's full " +
             "depth on demand before calling it. " +
             "[openWorldHint: false — reads the in-process tool catalog only.] " +
             "/ Devuelve la descripción completa de una herramienta por su nombre exacto.",
         annotations: META_ANNOTATIONS,
-        inputSchema: {
-            name: z
-                .string()
-                .describe("Exact tool name as returned by search_tools (e.g. 'create_invoice') / " +
-                "Nombre exacto de la herramienta devuelto por search_tools."),
-        },
-        outputSchema: z
-            .object({})
-            .passthrough()
-            .describe("A tool's full description, group, read-only flag and input field names / Descripción completa de una herramienta"),
+        inputSchema: securitySchemes
+            ? z.object(describeToolInputShape).strict()
+            : describeToolInputShape,
+        outputSchema: describeToolOutput.describe("A tool's full description, group, read-only flag and input field names / Descripción completa de una herramienta"),
     }, async (args = {}) => {
         const name = typeof args.name === "string" ? args.name.trim() : "";
         const entry = catalog.get(name);
@@ -520,6 +640,8 @@ originalRegisterTool, handle) {
             group: entry.group,
             title: entry.title,
             readOnly: entry.readOnly,
+            ...(entry.annotations ? { annotations: entry.annotations } : {}),
+            ...(entry.capability ? { capability: entry.capability } : {}),
             inputFields: entry.inputFields,
             description: entry.description,
         });

package/dist/tools/accountingClose.d.ts

@@ -2,17 +2,26 @@
  * Period close tools for the Frihet MCP server — D4-B megasprint (3 tools).
  *
  * Tools:
- *   1. period_close_status — get the current accounting period state (open/closing/closed)
+ *   1. period_close_status — get the current or selected fiscal-year state
  *   2. period_close        — close a monthly or quarterly period (TRUST AREA)
  *   3. period_reopen       — reopen a closed period with required reason (TRUST AREA)
  *
  * REST surface: /v1/periods/current, /v1/periods/{id}, /v1/periods/close, /v1/periods/{id}/reopen
  *
- * Closing a period freezes invoices/expenses/journal entries. Reopening requires a
- * compliance reason logged for audit. These are TRUST AREA operations.
+ * STATE OF THE WORLD (verified against erp-main functions/src/publicApi/families/
+ * periods.ts): only the READ route is implemented. Both WRITE routes answer
+ * HTTP 501 NOT_IMPLEMENTED — "deferred to the upcoming fiscal-write wave (Trust,
+ * serialized). Use year-end closing in the app for now." Nothing is frozen, and
+ * there is no idempotent no-op to rely on, because there is no handler at all.
  *
- * NOTE: ERP backend endpoints land in parallel D4-A wave. 404s propagate as isError
- * until backend ships. TODO: confirm callable boundary vs REST shell for closePeriod.
+ * The descriptions below therefore state the 501 in the present tense. Do not
+ * restore aspirational prose about freezing or idempotency until a handler exists
+ * — GAP-13 was exactly that: an agent planning a year-end close read a mechanism
+ * the backend never had.
+ *
+ * `withBackendGuard` converts 404 only (backend-availability.ts isBackendNotFound),
+ * so a 501 surfaces through the generic error path as isError with the backend's
+ * own NOT_IMPLEMENTED message — an honest failure, not a fake success.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { IFrihetClient } from "../client-interface.js";