@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/logger.js

@@ -6,6 +6,107 @@
  *
  * Set FRIHET_MCP_DEBUG=1 to enable debug-level logs.
  */
+const OPERATION_MESSAGES = {
+    startup: "MCP startup event",
+    session_init: "MCP session event",
+    tool_call: "MCP tool call completed",
+    tool_error: "MCP tool error",
+    api_call: "MCP API call completed",
+    api_retry: "MCP API retry scheduled",
+    http_request: "MCP HTTP request completed",
+    oauth_authorize: "MCP OAuth authorization event",
+    oauth_callback: "MCP OAuth callback event",
+    shutdown_metrics: "MCP shutdown event",
+    langfuse_send: "MCP telemetry delivery event",
+    langfuse_trace: "MCP telemetry trace event",
+};
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/u;
+const PACKAGE_VERSION = /^\d{1,3}\.\d{1,3}\.\d{1,3}$/u;
+const SAFE_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const SAFE_TRANSPORTS = new Set(["stdio", "remote"]);
+const SAFE_MCP_VERSIONS = new Set(["mcp/1.0"]);
+const LOCAL_ERROR_CODES = new Set([
+    "tool_error",
+    "telemetry_http_error",
+    "telemetry_error",
+    "startup_error",
+    "unknown_error",
+]);
+function toolNameToken(value) {
+    return typeof value === "string" && TOOL_NAME.test(value) ? value : undefined;
+}
+function operationalErrorCode(value, statusCode) {
+    if (statusCode === 401)
+        return "unauthorized";
+    if (statusCode === 403)
+        return "forbidden";
+    if (statusCode === 404)
+        return "not_found";
+    if (statusCode === 408)
+        return "request_timeout";
+    if (statusCode === 429)
+        return "rate_limited";
+    if (statusCode !== undefined && statusCode >= 400 && statusCode < 500)
+        return "client_error";
+    if (statusCode !== undefined && statusCode >= 500)
+        return "backend_error";
+    return typeof value === "string" && LOCAL_ERROR_CODES.has(value) ? value : "unknown_error";
+}
+function safeInteger(value, min, max) {
+    return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max
+        ? value
+        : undefined;
+}
+/**
+ * Central operational metadata allowlist.
+ *
+ * Callers may pass arbitrary objects for backwards compatibility, but only
+ * bounded protocol/runtime facts can cross the logging boundary. Dynamic
+ * paths, identifiers, user agents, emails, provider bodies, and nested objects
+ * are intentionally discarded.
+ */
+function sanitizeMetadata(metadata) {
+    if (!metadata)
+        return undefined;
+    const safe = {};
+    const version = typeof metadata.version === "string" && PACKAGE_VERSION.test(metadata.version)
+        ? metadata.version
+        : undefined;
+    const transport = typeof metadata.transport === "string" && SAFE_TRANSPORTS.has(metadata.transport)
+        ? metadata.transport
+        : undefined;
+    const mcpVersion = typeof metadata.mcpVersion === "string" && SAFE_MCP_VERSIONS.has(metadata.mcpVersion)
+        ? metadata.mcpVersion
+        : undefined;
+    const method = typeof metadata.method === "string" && SAFE_METHODS.has(metadata.method)
+        ? metadata.method
+        : undefined;
+    const statusCode = safeInteger(metadata.statusCode, 0, 599);
+    const retryCount = safeInteger(metadata.retryCount, 0, 100);
+    const delayMs = safeInteger(metadata.delayMs, 0, 86_400_000);
+    const uptime = safeInteger(metadata.uptime, 0, Number.MAX_SAFE_INTEGER);
+    if (version)
+        safe.version = version;
+    if (transport)
+        safe.transport = transport;
+    if (mcpVersion)
+        safe.mcpVersion = mcpVersion;
+    if (method)
+        safe.method = method;
+    if (statusCode !== undefined)
+        safe.statusCode = statusCode;
+    if (retryCount !== undefined)
+        safe.retryCount = retryCount;
+    if (delayMs !== undefined)
+        safe.delayMs = delayMs;
+    if (uptime !== undefined)
+        safe.uptime = uptime;
+    if (typeof metadata.success === "boolean")
+        safe.success = metadata.success;
+    if (typeof metadata.stub === "boolean")
+        safe.stub = metadata.stub;
+    return Object.keys(safe).length > 0 ? safe : undefined;
+}
 /**
  * Returns true if debug logging is enabled.
  * Checks env var in Node.js; always false in Workers unless overridden.
@@ -25,10 +126,41 @@ export function log(entry) {
     if (entry.level === "debug" && !isDebugEnabled()) {
         return;
     }
+    const operation = typeof entry.operation === "string" && Object.hasOwn(OPERATION_MESSAGES, entry.operation)
+        ? entry.operation
+        : undefined;
+    const tool = toolNameToken(entry.tool);
+    const durationMs = typeof entry.durationMs === "number"
+        && Number.isFinite(entry.durationMs)
+        && entry.durationMs >= 0
+        && entry.durationMs <= 86_400_000
+        ? Math.round(entry.durationMs)
+        : undefined;
+    const errorStatus = safeInteger(entry.error?.statusCode, 0, 599);
+    const errorCode = operationalErrorCode(entry.error?.code, errorStatus);
+    const metadata = sanitizeMetadata(entry.metadata);
     const full = {
-        ...entry,
+        level: entry.level,
+        message: operation === "tool_call" && entry.level === "error"
+            ? "MCP tool call failed"
+            : operation
+                ? (OPERATION_MESSAGES[operation] ?? "MCP operational event")
+                : "MCP operational event",
         service: "frihet-mcp",
         timestamp: new Date().toISOString(),
+        ...(tool ? { tool } : {}),
+        ...(operation ? { operation } : {}),
+        ...(durationMs !== undefined ? { durationMs } : {}),
+        ...(entry.error
+            ? {
+                error: {
+                    message: "MCP operation failed",
+                    code: errorCode,
+                    ...(errorStatus !== undefined ? { statusCode: errorStatus } : {}),
+                },
+            }
+            : {}),
+        ...(metadata ? { metadata } : {}),
     };
     // Remove undefined fields for cleaner output
     const cleaned = JSON.stringify(full, (_key, value) => value === undefined ? undefined : value);
@@ -47,7 +179,7 @@ export function logToolCall(tool, startTime, success, error) {
             operation: "tool_call",
             durationMs,
             error: {
-                message: error.message,
+                message: "MCP operation failed",
                 code: error.errorCode ?? error.name,
                 statusCode: error.statusCode,
             },
@@ -66,25 +198,25 @@ export function logToolCall(tool, startTime, success, error) {
 /**
  * Log an outbound API call with timing.
  */
-export function logApiCall(method, path, statusCode, durationMs) {
+export function logApiCall(method, _path, statusCode, durationMs) {
     const level = statusCode >= 500 ? "error" : statusCode >= 400 ? "warn" : "info";
     log({
         level,
-        message: `${method} ${path} ${statusCode} ${durationMs}ms`,
+        message: "MCP API call completed",
         operation: "api_call",
         durationMs,
-        metadata: { method, path, statusCode },
+        metadata: { method, statusCode },
     });
 }
 /**
  * Log a rate-limit retry.
  */
-export function logRetry(method, path, retryCount, delayMs) {
+export function logRetry(method, _path, retryCount, delayMs, delaySource) {
     log({
         level: "warn",
-        message: `Rate limited, retrying ${method} ${path} (attempt ${retryCount + 1}, delay ${delayMs}ms)`,
+        message: "MCP API retry scheduled",
         operation: "api_retry",
-        metadata: { method, path, retryCount: retryCount + 1, delayMs },
+        metadata: { method, retryCount: retryCount + 1, delayMs, delaySource },
     });
 }
 //# sourceMappingURL=logger.js.map

package/dist/muse-profile.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Meta Muse Profile for the Frihet MCP Server.
+ *
+ * Implements the curated 18-tool financial management surface submitted
+ * for the Meta Muse Business Application catalog.
+ *
+ * Requirements:
+ * - Curated catalogue: 18 high-value small business & freelancer tools.
+ * - Human-in-the-loop: Invoices and financial documents are created strictly in draft status.
+ * - Zero unconfirmed destructive actions (no direct AEAT / VeriFactu fiscal submissions).
+ * - Standard output redaction for sensitive fields.
+ */
+export declare const MUSE_CANDIDATE_TOOLS: ReadonlySet<string>;
+export declare const MUSE_CANDIDATE_TOOL_COUNT: number;
+export declare const MUSE_INSTRUCTIONS = "Frihet ERP \u2014 natural-language business and financial management for Meta Muse.\nUse get_business_context for complete company health and plan limits.\nQuery and review invoices, expenses, quotes, clients, and products with pagination.\nAll created invoices are drafts. Confirm parameters with the user before creating records.";
+export declare function museToolResult(result: unknown): unknown;
+export declare const MUSE_FORCED_INPUT_VALUES: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+export declare function applyMuseProfile(server: any): void;
+//# sourceMappingURL=muse-profile.d.ts.map

package/dist/muse-profile.js

@@ -0,0 +1,122 @@
+/**
+ * Meta Muse Profile for the Frihet MCP Server.
+ *
+ * Implements the curated 18-tool financial management surface submitted
+ * for the Meta Muse Business Application catalog.
+ *
+ * Requirements:
+ * - Curated catalogue: 18 high-value small business & freelancer tools.
+ * - Human-in-the-loop: Invoices and financial documents are created strictly in draft status.
+ * - Zero unconfirmed destructive actions (no direct AEAT / VeriFactu fiscal submissions).
+ * - Standard output redaction for sensitive fields.
+ */
+import { deepRedact, redactText } from "./redaction.js";
+export const MUSE_CANDIDATE_TOOLS = new Set([
+    "get_business_context",
+    "get_monthly_summary",
+    "get_quarterly_taxes",
+    "list_invoices",
+    "get_invoice",
+    "search_invoices",
+    "list_expenses",
+    "get_expense",
+    "create_expense",
+    "list_clients",
+    "get_client",
+    "create_client",
+    "list_products",
+    "get_product",
+    "list_quotes",
+    "get_quote",
+    "create_quote",
+    "create_invoice",
+]);
+export const MUSE_CANDIDATE_TOOL_COUNT = MUSE_CANDIDATE_TOOLS.size; // 18
+export const MUSE_INSTRUCTIONS = `Frihet ERP — natural-language business and financial management for Meta Muse.
+Use get_business_context for complete company health and plan limits.
+Query and review invoices, expenses, quotes, clients, and products with pagination.
+All created invoices are drafts. Confirm parameters with the user before creating records.`;
+export function museToolResult(result) {
+    if (result === null || typeof result !== "object")
+        return result;
+    const res = result;
+    // Deep-redact structured output if present (in-place deletion of sensitive fields)
+    if (res.structuredContent && typeof res.structuredContent === "object") {
+        deepRedact(res.structuredContent);
+    }
+    // Redact text content items
+    if (Array.isArray(res.content)) {
+        res.content = res.content.map((item) => {
+            if (item && typeof item === "object" && "text" in item && typeof item.text === "string") {
+                return {
+                    ...item,
+                    text: redactText(item.text),
+                };
+            }
+            return item;
+        });
+    }
+    return res;
+}
+export const MUSE_FORCED_INPUT_VALUES = {
+    create_invoice: { status: "draft" },
+    create_quote: { status: "draft" },
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyMuseProfile(server) {
+    const registerTool = server.registerTool.bind(server);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    server.registerTool = (name, config, handler) => {
+        if (!MUSE_CANDIDATE_TOOLS.has(name))
+            return undefined;
+        let description = config.description ?? "";
+        let inputSchema = config.inputSchema;
+        if (name === "create_invoice") {
+            description = `${description} [Meta Muse: Generates an invoice strictly in 'draft' status for human review. No irreversible fiscal submission occurs.]`;
+            if (inputSchema && typeof inputSchema === "object" && "status" in inputSchema) {
+                const { status: _omittedStatus, ...rest } = inputSchema;
+                inputSchema = rest;
+            }
+        }
+        else if (name === "create_quote") {
+            description = `${description} [Meta Muse: Generates a quote strictly in 'draft' status for human review.]`;
+            if (inputSchema && typeof inputSchema === "object" && "status" in inputSchema) {
+                const { status: _omittedStatus, ...rest } = inputSchema;
+                inputSchema = rest;
+            }
+        }
+        return registerTool(name, {
+            ...config,
+            description,
+            inputSchema,
+            annotations: {
+                ...config.annotations,
+                ...(config.annotations?.readOnlyHint !== true ? { destructiveHint: true } : {}),
+            },
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (...args) => {
+            try {
+                let input = args[0];
+                if (input && typeof input === "object") {
+                    const forced = MUSE_FORCED_INPUT_VALUES[name];
+                    if (forced) {
+                        input = { ...input, ...forced };
+                    }
+                }
+                const res = await handler(input, ...args.slice(1));
+                return museToolResult(res);
+            }
+            catch {
+                return museToolResult({
+                    isError: true,
+                    _meta: { "io.frihet/operationOutcomeUnknown": true },
+                });
+            }
+        });
+    };
+    // Meta Muse profile intentionally registers 0 raw prompts or dynamic resources
+    server.registerResource = () => undefined;
+    server.registerPrompt = () => undefined;
+}
+//# sourceMappingURL=muse-profile.js.map

package/dist/observability.d.ts

@@ -6,8 +6,9 @@
  *
  * Design:
  *   - Fail-open: any Langfuse error logs a warning and lets the tool proceed.
- *   - PII: tool input content is passed as-is (business data is fine to trace).
- *     userId / apiKey metadata are hashed with a simple SHA-256 fingerprint.
+ *   - Data minimization: only bounded operational facts cross the telemetry
+ *     boundary. Tool input/output, arbitrary error text, and user/workspace
+ *     identity are never serialized.
  *   - Fire-and-forget: traces are sent via waitUntil (Workers) or unref'd promise
  *     (Node.js) so they never block tool responses.
  *
@@ -18,6 +19,12 @@
  *
  * Docs: https://langfuse.com/docs/api/reference/overview
  */
+/**
+ * Langfuse receives a Basic Authorization header, so its authority is exact.
+ * The current product contract documents one hosted origin; arbitrary Frihet
+ * subdomains and self-hosted overrides are intentionally not trusted here.
+ */
+export declare function normalizeLangfuseBaseUrl(value: string): string;
 /**
  * Called once from FrihetMCP.init() in the Worker to inject env vars.
  * Not needed in Node.js stdio mode (reads from process.env directly).
@@ -33,8 +40,6 @@ interface LangfuseSpanBody {
     name: string;
     startTime: string;
     endTime: string;
-    input?: unknown;
-    output?: unknown;
     metadata?: Record<string, unknown>;
     level?: "DEFAULT" | "DEBUG" | "WARNING" | "ERROR";
     statusMessage?: string;
@@ -43,11 +48,8 @@ interface LangfuseTraceBody {
     id: string;
     name: string;
     timestamp: string;
-    input?: unknown;
-    output?: unknown;
     metadata?: Record<string, unknown>;
     tags?: string[];
-    userId?: string;
 }
 interface IngestionBatch {
     batch: Array<{
@@ -58,8 +60,7 @@ interface IngestionBatch {
     }>;
 }
 interface StubMarker {
-    plannedEndpoint?: string;
-    note?: string;
+    stub: true;
 }
 /**
  * Inspect a resolved tool output for stub / not-implemented / unavailable
@@ -79,33 +80,24 @@ interface StubMarker {
  */
 export declare function inspectStubMarker(output: unknown): StubMarker | null;
 interface TraceContext {
-    /** User-Agent from MCP client or other client identifier */
-    clientName?: string;
     /** MCP protocol version */
     mcpVersion?: string;
-    /** Frihet workspace/user ID — will be hashed */
-    userId?: string;
 }
 /**
- * Set session-level context (client identity, MCP version).
+ * Set session-level protocol context. Client identity is intentionally absent.
  * Call once from server init; applies to all subsequent traces.
  */
 export declare function setTraceContext(ctx: TraceContext): void;
 interface TracePayloadParams {
     toolName: string;
-    /** Raw tool input args (redacted before serialization). */
-    input: unknown;
-    /** Raw tool output (redacted before serialization); ignored when isError. */
-    output: unknown;
     isError: boolean;
-    errorMessage?: string;
+    errorClass?: string;
+    errorCode?: string;
+    statusCode?: number;
     startTime: Date;
     endTime: Date;
     traceId: string;
     spanId: string;
-    /** Already-hashed user id, or undefined. */
-    userIdHashed?: string;
-    clientName?: string;
     mcpVersion?: string;
     /** Fabricated-stub marker, or null on a genuine result. */
     stub: StubMarker | null;
@@ -113,12 +105,9 @@ interface TracePayloadParams {
 /**
  * Builds the Langfuse trace+span ingestion batch for a single tool call.
  *
- * CRITICAL (Trust): `input` and `output` are passed through {@link redactClone}
- * before they enter the payload, so government IDs (taxId/NIF/CIF), banking
- * identifiers (IBAN), webhook signing secrets, and auth tokens NEVER reach the
- * external Langfuse service — in ANY profile mode. The tool-call output handed
- * to the user is redacted later (OpenAI mode only); this redacts the trace copy
- * unconditionally. Exported so a test can assert no sensitive value survives.
+ * CRITICAL (Trust): this builder is an allowlist. It has no input/output or
+ * identity fields and ignores any extra runtime properties a caller supplies.
+ * Exported so tests can assert the exact operational shape.
  */
 export declare function buildTracePayload(p: TracePayloadParams): IngestionBatch;
 /**
@@ -132,6 +121,6 @@ export declare function buildTracePayload(p: TracePayloadParams): IngestionBatch
  * @param fn        Async tool handler to wrap
  * @returns         Result of fn
  */
-export declare function traceMCPTool<T>(toolName: string, input: unknown, fn: () => Promise<T>): Promise<T>;
+export declare function traceMCPTool<T>(toolName: string, _input: unknown, fn: () => Promise<T>): Promise<T>;
 export {};
 //# sourceMappingURL=observability.d.ts.map