@frihet/mcp-server 1.16.5 → 1.17.0

package/dist/index.js

@@ -15,6 +15,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { FrihetClient } from "./client.js";
 import { DemoFrihetClient } from "./demo-client.js";
+import { normalizePublicApiBaseUrl } from "./api-origin.js";
 // Single source of truth for the server version: package.json (read at runtime
 // from dist/../package.json). Hardcoding it here caused repeated version drift
 // (server.json/index.ts/console out of sync → audit:mcp-refs gate failure).
@@ -28,11 +29,10 @@ const PKG_VERSION = (() => {
         return "0.0.0";
     }
 })();
-import { registerAllTools } from "./tools/register-all.js";
-import { registerAllResources } from "./resources/register-all.js";
-import { registerAllPrompts } from "./prompts/register-all.js";
-import { applyOpenAIProfile, OPENAI_ALLOWED_TOOL_COUNT, OPENAI_EXCLUDED_COUNT, OPENAI_EXCLUDED_RESOURCE_COUNT, OPENAI_REVIEWED_TOOL_ALLOWLIST } from "./openai-profile.js";
-import { resolveToolMode, applyToolExposureProfile, GROUPED_META_TOOL_COUNT } from "./tool-exposure.js";
+import { OPENAI_ALLOWED_TOOL_COUNT, OPENAI_EXCLUDED_COUNT, OPENAI_EXCLUDED_RESOURCE_COUNT } from "./openai-profile.js";
+import { resolveToolMode, GROUPED_META_TOOL_COUNT } from "./tool-exposure.js";
+import { localMcpSurfaceComposition, registerMcpSurface, } from "./server-composition.js";
+import { AGENT_SERVER_INSTRUCTIONS, API_KEY_LOCATION, } from "./agent-onboarding.js";
 import { log } from "./logger.js";
 import { registerShutdownHook } from "./metrics.js";
 import { setTraceContext } from "./observability.js";
@@ -44,33 +44,40 @@ function main() {
     const demoFlag = process.env.FRIHET_DEMO;
     const demoMode = demoFlag === "1" || demoFlag === "true";
     if (!demoMode && !apiKey) {
+        // Human-readable first, then one machine-readable line. An agent that only
+        // gets prose here has to guess; the JSON line gives it a code to branch on
+        // and the two recoveries that actually exist. /settings/api is the real,
+        // routable screen — there is no "Developers" section in the app.
         console.error("Error: FRIHET_API_KEY environment variable is required.\n\n" +
             "Get your API key:\n" +
             "  1. Create a free account at https://app.frihet.io\n" +
-            "  2. Go to Settings > Developers > API Keys\n" +
-            "  3. Create a key and add it to your MCP configuration\n\n" +
+            "  2. Open https://app.frihet.io/settings/api\n" +
+            "  3. Create a key (it starts with fri_) and add it to your MCP configuration\n\n" +
             "Or try it instantly with no key: set FRIHET_DEMO=1 for example data.\n\n" +
             "Documentation: https://docs.frihet.io/desarrolladores/mcp-server\n");
+        console.error(JSON.stringify({
+            error: {
+                code: "FRIHET_API_KEY_MISSING",
+                message: "FRIHET_API_KEY environment variable is required",
+                obtainAt: API_KEY_LOCATION,
+                recovery: [
+                    { action: "set_env", env: { FRIHET_API_KEY: "fri_<key>" } },
+                    { action: "run_without_credentials", env: { FRIHET_DEMO: "1" } },
+                ],
+                docs: "https://docs.frihet.io/desarrolladores/mcp-server",
+            },
+        }));
         process.exit(1);
     }
-    const baseUrl = process.env.FRIHET_API_URL;
-    if (!demoMode && baseUrl !== undefined) {
-        let parsed;
+    const baseUrlRaw = process.env.FRIHET_API_URL;
+    let baseUrl;
+    if (!demoMode && baseUrlRaw !== undefined) {
         try {
-            parsed = new URL(baseUrl);
+            baseUrl = normalizePublicApiBaseUrl(baseUrlRaw);
         }
-        catch {
-            console.error(`Error: FRIHET_API_URL is not a valid URL: "${baseUrl}"\n` +
-                "It must be a valid https:// URL with a frihet.io hostname.\n");
-            process.exit(1);
-        }
-        if (parsed.protocol !== "https:") {
-            console.error(`Error: FRIHET_API_URL must use https:// (got "${parsed.protocol}").\n`);
-            process.exit(1);
-        }
-        if (!parsed.hostname.endsWith("frihet.io")) {
-            console.error(`Error: FRIHET_API_URL hostname must be under frihet.io (got "${parsed.hostname}").\n` +
-                "This prevents redirection to untrusted servers.\n");
+        catch (error) {
+            console.error(`Error: ${error instanceof Error ? error.message : "FRIHET_API_URL is invalid"}.\n` +
+                "It must be a canonical https:// URL with a trusted frihet.io hostname.\n");
             process.exit(1);
         }
     }
@@ -80,69 +87,47 @@ function main() {
     if (demoMode) {
         console.error("[frihet-mcp] DEMO MODE — serving example fixtures, no real data, nothing persisted");
     }
-    // Set trace context for Langfuse (reads LANGFUSE_* from process.env automatically).
-    // clientName can be overridden via FRIHET_CLIENT_NAME env var by the MCP host.
+    // Set the fixed protocol fact for Langfuse (reads LANGFUSE_* from process.env automatically).
+    // Client identity is deliberately omitted from telemetry.
     setTraceContext({
         mcpVersion: "mcp/1.0",
-        clientName: process.env.FRIHET_CLIENT_NAME,
     });
     const server = new McpServer({
         name: "frihet-erp",
         version: PKG_VERSION,
         description: "AI-native MCP server for Frihet ERP — invoices, expenses, clients, products, quotes, webhooks, and deposits. " +
-            "Provides 157 tools (including business context, monthly summaries, quarterly taxes, invoice duplication, CRM subcollections, and deposit management), " +
-            "11 resources (7 static + 4 live), and 10 workflow prompts for business management " +
+            "Provides a catalogue of 157 canonical operations; fiscal aliases and optional grouped discovery names are reported separately. " +
+            "The local package serves 11 resources (7 static + 4 API-backed) and 10 workflow prompts " +
             "with full Spanish tax compliance (IVA, IGIC, IPSI).",
+    }, {
+        // Delivered by `initialize` to every MCP client, which hands it to the model
+        // before the first tool call. This is the only onboarding channel that costs
+        // the operator zero configuration. Source: src/agent-onboarding.ts.
+        instructions: AGENT_SERVER_INSTRUCTIONS,
     });
     const openaiMode = process.env.FRIHET_OPENAI_MODE === "true";
     const toolMode = resolveToolMode();
-    // PROFILE COMPOSITION ORDER (both interceptors wrap registerTool):
-    //   1. applyToolExposureProfile FIRST (innermost) — so the 3 discovery
-    //      meta-tools register against the REAL server.registerTool and bypass the
-    //      OpenAI allow-list gate. In allow-list mode it catalogs ONLY the reviewed
-    //      tools, keeping the progressive-disclosure surface == the reviewed 53.
-    //   2. applyOpenAIProfile SECOND (outermost) — a business-tool registration is
-    //      first gated/redacted/annotated/openWorldHint-justified by OpenAI, THEN
-    //      collapsed by the grouped interceptor, so the terse collapsed line is the
-    //      final description and OpenAI's handler redaction survives.
-    // Order only matters when BOTH are active (openai-mcp grouped); openai-only and
-    // grouped-only are unaffected by the swap.
-    // Apply grouped tool-exposure profile if enabled (progressive disclosure).
-    // FRIHET_TOOL_MODE=grouped collapses the full tool descriptions into terse
-    // one-liners + adds list_tool_groups / search_tools / describe_tool meta-tools,
-    // so agents load depth on demand instead of a flat 157-tool wall of context.
-    // Default (unset / "full") is byte-identical to current behavior. When OpenAI
-    // mode is also on, pass the reviewed allow-list so the catalog/meta-tools are
-    // pinned to exactly the 53 reviewed tools.
     if (toolMode === "grouped") {
-        applyToolExposureProfile(server, openaiMode ? { allowlist: OPENAI_REVIEWED_TOOL_ALLOWLIST } : undefined);
         log({
             level: "info",
             message: `Grouped tool-exposure active — tools collapsed to terse summaries, ${GROUPED_META_TOOL_COUNT} discovery meta-tools added (list_tool_groups, search_tools, describe_tool); full depth served on demand`,
             operation: "startup",
         });
     }
-    // Apply OpenAI-safe profile if enabled (strips sensitive fields, fixes annotations)
     if (openaiMode) {
-        applyOpenAIProfile(server);
         log({
             level: "info",
             message: `OpenAI safety profile active — ${OPENAI_ALLOWED_TOOL_COUNT} tools allowed, prompts hidden, ${OPENAI_EXCLUDED_COUNT} defense-in-depth exclusions, ${OPENAI_EXCLUDED_RESOURCE_COUNT} resources excluded, gov IDs + credentials redacted`,
             operation: "startup",
         });
     }
-    // Register tools (62 full / 60 in OpenAI mode)
-    registerAllTools(server, client);
-    // Register 11 resources (7 static + 4 dynamic via API)
-    registerAllResources(server, client);
-    // Register 10 workflow prompts
-    registerAllPrompts(server);
+    registerMcpSurface(server, client, localMcpSurfaceComposition(openaiMode, toolMode === "grouped"));
     // Register shutdown hook to log final metrics summary
     registerShutdownHook();
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     server.connect(transport).then(() => {
-        console.error(`[frihet-mcp] v${PKG_VERSION} | 157 tools | https://github.com/Frihet-io/frihet-mcp`);
+        console.error(`[frihet-mcp] v${PKG_VERSION} | capability truth enabled | https://github.com/Frihet-io/frihet-mcp`);
         log({
             level: "info",
             message: "Frihet MCP server running on stdio",

package/dist/logger.d.ts

@@ -37,10 +37,10 @@ export declare function logToolCall(tool: string, startTime: number, success: bo
 /**
  * Log an outbound API call with timing.
  */
-export declare function logApiCall(method: string, path: string, statusCode: number, durationMs: number): void;
+export declare function logApiCall(method: string, _path: string, statusCode: number, durationMs: number): void;
 /**
  * Log a rate-limit retry.
  */
-export declare function logRetry(method: string, path: string, retryCount: number, delayMs: number): void;
+export declare function logRetry(method: string, _path: string, retryCount: number, delayMs: number): void;
 export {};
 //# sourceMappingURL=logger.d.ts.map

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) {
     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 },
     });
 }
 //# sourceMappingURL=logger.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