@lerianstudio/matcher-mcp 1.0.0-beta.5

package/dist/config.js

@@ -0,0 +1,95 @@
+// Bootstrap configuration for the Matcher MCP server.
+//
+// Values are read from the environment once and frozen into a typed object.
+// Defaults are chosen to avoid collisions with matcher dev (matcher runs on
+// 4018; this server defaults to 4019). The matcher base URL is surfaced here
+// so the HTTP client (task 1.3.1) and the generic invoke / curated tools
+// consume a single source of truth instead of reading process.env directly.
+const DEFAULT_PORT = 4019;
+const DEFAULT_MATCHER_API_URL = 'http://localhost:4018';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BODY_BYTES = 1_048_576; // 1 MiB
+const DEFAULT_OTEL_SERVICE_NAME = 'matcher-mcp';
+/**
+ * Parse a port from a raw env string, falling back to the default when unset.
+ * An explicitly-set but invalid value is a misconfiguration and throws, rather
+ * than silently degrading to the default (fail-loud at boot).
+ */
+function parsePort(raw, fallback) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new Error(`invalid MCP_PORT: ${raw} (expected an integer in 1..65535)`);
+    }
+    return value;
+}
+/**
+ * Parse a positive timeout (ms) from a raw env string, falling back to the
+ * default when unset. An explicitly-set but invalid value is a misconfiguration
+ * and throws, rather than silently degrading to the default (fail-loud at boot).
+ */
+function parseTimeoutMs(raw, fallback) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`invalid MATCHER_TIMEOUT_MS: ${raw} (expected a positive integer of milliseconds)`);
+    }
+    return value;
+}
+/**
+ * Parse a positive byte count from a raw env string, falling back to the default
+ * when unset. An explicitly-set but invalid value is a misconfiguration and
+ * throws, rather than silently degrading to the default (fail-loud at boot).
+ */
+function parseMaxBodyBytes(raw, fallback) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`invalid MAX_BODY_BYTES: ${raw} (expected a positive integer of bytes)`);
+    }
+    return value;
+}
+/**
+ * Parse a boolean flag from a raw env string, falling back to the default when
+ * unset. Accepts `true`/`false` and `1`/`0` (case-insensitive). An explicitly-set
+ * but unrecognized value is a misconfiguration and throws, rather than silently
+ * coercing to a default (fail-loud at boot).
+ */
+function parseBool(raw, fallback, key) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === 'true' || normalized === '1') {
+        return true;
+    }
+    if (normalized === 'false' || normalized === '0') {
+        return false;
+    }
+    throw new Error(`invalid ${key}: ${raw} (expected one of true, false, 1, 0)`);
+}
+/**
+ * Build the config from a given environment map (defaults to process.env).
+ * Pure and side-effect-free so tests can drive it with a synthetic env.
+ */
+export function loadConfig(env = process.env) {
+    const matcherApiUrl = env.MATCHER_API_URL?.trim() || DEFAULT_MATCHER_API_URL;
+    const otelEndpoint = env.OTEL_EXPORTER_OTLP_ENDPOINT?.trim();
+    const otelServiceName = env.OTEL_RESOURCE_SERVICE_NAME?.trim() || DEFAULT_OTEL_SERVICE_NAME;
+    return Object.freeze({
+        port: parsePort(env.MCP_PORT, DEFAULT_PORT),
+        matcherApiUrl: matcherApiUrl.replace(/\/+$/, ''),
+        timeoutMs: parseTimeoutMs(env.MATCHER_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
+        maxBodyBytes: parseMaxBodyBytes(env.MAX_BODY_BYTES, DEFAULT_MAX_BODY_BYTES),
+        enableTelemetry: parseBool(env.ENABLE_TELEMETRY, false, 'ENABLE_TELEMETRY'),
+        otelExporterOtlpEndpoint: otelEndpoint || undefined,
+        otelServiceName,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/matcher/client.js

@@ -0,0 +1,168 @@
+// Matcher HTTP client contract — the single typed boundary every tool (generic
+// invoke + curated) uses to reach the matcher API.
+//
+// The contract (MatcherRequest / MatcherProblem / MatcherApiError / MatcherClient
+// / createMatcherClient) is fixed by the plan's Shared Contracts. This file
+// supplies the concrete `fetch`-based implementation (task 1.3.1) that both the
+// generic invoke (1.2.3) and every curated tool depend on.
+//
+// Security invariants (asserted by tests):
+//   - The bearer token is sent on the outbound `Authorization` header and is
+//     NEVER logged and NEVER placed in a thrown error message.
+//   - The caller always receives a `MatcherApiError` on any failure path (matcher
+//     status >= 400, malformed body, network failure, or timeout) — never a raw
+//     fetch/abort error — so error handling upstream is uniform.
+import { loadConfig } from '../config.js';
+import { injectTraceContext } from '../observability/otel.js';
+/** Thrown by `MatcherClient.request` on any matcher status >= 400 (or transport failure). */
+export class MatcherApiError extends Error {
+    /** HTTP status from matcher (synthetic, e.g. 504, for transport failures). */
+    status;
+    /** Best-effort parsed RFC 9457 problem document. */
+    problem;
+    constructor(message, status, problem = {}) {
+        super(message);
+        this.name = 'MatcherApiError';
+        this.status = status;
+        this.problem = problem;
+    }
+}
+/**
+ * Synthetic status used when a request never produced an HTTP response (network
+ * failure or client-enforced timeout). 504 (Gateway Timeout) reads correctly to
+ * an operator: the relay could not reach / hear back from matcher in time.
+ */
+const TRANSPORT_FAILURE_STATUS = 504;
+/** Build an absolute request URL from the base, path, and an optional query map. */
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+    if (query) {
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    return url.toString();
+}
+/**
+ * Best-effort parse a matcher error response into a `MatcherProblem`. Matcher
+ * returns RFC 9457 `application/problem+json` on errors; when the body is not
+ * usable problem+json (empty, non-JSON, or JSON of the wrong shape) we fall back
+ * to the HTTP status text so the problem always carries at least a `title`.
+ */
+async function parseProblem(res) {
+    const fallbackTitle = res.statusText || `HTTP ${res.status}`;
+    let raw;
+    try {
+        const text = await res.text();
+        if (!text.trim()) {
+            return { title: fallbackTitle };
+        }
+        raw = JSON.parse(text);
+    }
+    catch {
+        return { title: fallbackTitle };
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        return { title: fallbackTitle };
+    }
+    const obj = raw;
+    const str = (key) => typeof obj[key] === 'string' ? obj[key] : undefined;
+    return {
+        type: str('type'),
+        title: str('title') ?? fallbackTitle,
+        detail: str('detail'),
+        code: str('code'),
+        instance: str('instance'),
+        errors: obj.errors,
+    };
+}
+/**
+ * Parse a successful response body as JSON. A 204 or any empty body resolves to
+ * `undefined` (matcher returns no content for deletes / some updates).
+ */
+async function parseSuccess(res) {
+    if (res.status === 204) {
+        return undefined;
+    }
+    const text = await res.text();
+    if (!text.trim()) {
+        return undefined;
+    }
+    return JSON.parse(text);
+}
+/**
+ * Build a `MatcherClient` bound to a single caller's bearer token.
+ *
+ * NEVER call this with a global/default token — the token is always the inbound
+ * caller's, resolved request-scoped (see auth/request-token.ts).
+ *
+ * The per-request timeout comes from config (`MATCHER_TIMEOUT_MS`, default 30s);
+ * the Shared Contracts signature fixes the two parameters, so the client reads
+ * the timeout from config itself rather than taking a third argument.
+ */
+export function createMatcherClient(baseUrl, bearerToken) {
+    const timeoutMs = loadConfig().timeoutMs;
+    return {
+        async request(req) {
+            const url = buildUrl(baseUrl, req.path, req.query);
+            const headers = {
+                // The caller's token, forwarded verbatim. Never logged.
+                authorization: `Bearer ${bearerToken}`,
+                accept: 'application/json',
+            };
+            let serializedBody;
+            if (req.body !== undefined) {
+                headers['content-type'] = 'application/json';
+                serializedBody = JSON.stringify(req.body);
+            }
+            // Inject the W3C trace context so the matcher call is a child of the
+            // tool-call span (MCP → matcher correlation in the collector). This writes
+            // ONLY `traceparent`/`tracestate` — it never reads or overwrites the
+            // `authorization` header, so the verbatim token relay above is untouched.
+            // A no-op when telemetry is disabled.
+            injectTraceContext(headers);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: req.method,
+                    headers,
+                    body: serializedBody,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                // Network failure or timeout abort: normalize to MatcherApiError so
+                // callers always get the same type. The token is in `headers` above but
+                // is never referenced here — the message describes only method + path.
+                const title = controller.signal.aborted
+                    ? `matcher request timed out after ${timeoutMs}ms`
+                    : 'matcher request failed before a response was received';
+                const detail = err instanceof Error ? err.message : 'unknown transport error';
+                throw new MatcherApiError(`${title}: ${req.method} ${req.path}`, TRANSPORT_FAILURE_STATUS, { title, detail });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!res.ok) {
+                const problem = await parseProblem(res);
+                // Message carries status + problem title — never the token.
+                const summary = problem.title ?? res.statusText ?? `HTTP ${res.status}`;
+                throw new MatcherApiError(`matcher returned ${res.status}: ${summary}`, res.status, problem);
+            }
+            try {
+                return await parseSuccess(res);
+            }
+            catch (err) {
+                // A 2xx with an unparseable body is still a failure the caller must see
+                // as a MatcherApiError, not a raw JSON SyntaxError.
+                const detail = err instanceof Error ? err.message : 'unknown parse error';
+                throw new MatcherApiError(`matcher returned ${res.status} with an unparseable JSON body`, res.status, { title: 'invalid response body from matcher', detail });
+            }
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/matcher/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/matcher/client.ts"],"names":[],"mappings":"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"}

package/dist/observability/otel.js

@@ -0,0 +1,223 @@
+// OpenTelemetry telemetry for the Matcher MCP server.
+//
+// The relay is intended as a hosted, monitored service, so it is instrumented
+// like the rest of the stack: traces + metrics over OTLP HTTP, correlated with
+// matcher's own spans (the outbound matcher call carries a W3C `traceparent`,
+// injected via `injectTraceContext`). The env names mirror matcher's Go service
+// (`ENABLE_TELEMETRY` / `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_RESOURCE_SERVICE_NAME`)
+// so the MCP slots into the same collector config.
+//
+// Everything is gated on `config.enableTelemetry` (default OFF):
+//   - Disabled → `initTelemetry` is a COMPLETE no-op: no NodeSDK, no providers,
+//     no exporters, no network. `instrumentToolCall` just runs the function and
+//     `injectTraceContext` leaves the headers untouched. Dev/test and
+//     single-operator runs pay nothing.
+//   - Enabled → a NodeSDK is started with OTLP HTTP trace + metric exporters and
+//     a resource stamping `service.name` (default `matcher-mcp`) and the build
+//     version from package.json.
+//
+// Token-relay rule (NON-NEGOTIABLE): telemetry records ONLY the tool name, the
+// call outcome (ok / error), and — on a matcher API failure — the matcher HTTP
+// status. It NEVER records the caller's bearer token, raw arguments, or request
+// headers, in any span attribute, metric attribute, event, or log. No tenant
+// identifier is read or emitted anywhere.
+import { context, metrics, propagation, SpanStatusCode, trace, ValueType, } from '@opentelemetry/api';
+import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
+import {} from '../config.js';
+/** The instrumentation scope name for the relay's own tracer + meter. */
+const INSTRUMENTATION_SCOPE = 'matcher-mcp';
+/** Span/metric attribute keys. Deliberately a closed, token-free set. */
+const ATTR_TOOL_NAME = 'mcp.tool.name';
+const ATTR_OUTCOME = 'mcp.tool.outcome';
+const ATTR_MATCHER_STATUS = 'matcher.http.status';
+/** Outcome attribute values — the only two states a tool call reports. */
+const OUTCOME_OK = 'ok';
+const OUTCOME_ERROR = 'error';
+/**
+ * The running SDK, when telemetry is enabled. `undefined` means telemetry is
+ * off (or not yet initialized) — in that state every helper degrades to a
+ * zero-cost no-op. Module-local so `shutdownTelemetry` can stop exactly what
+ * `initTelemetry` started.
+ */
+let sdk;
+/**
+ * The version stamped on the telemetry resource, captured at init so
+ * `instrumentToolCall` does not need it threaded through. Only meaningful while
+ * telemetry is enabled.
+ */
+let serviceVersion = '0.0.0';
+/**
+ * Initialize OpenTelemetry from config. A COMPLETE no-op when
+ * `config.enableTelemetry` is false: no SDK, no providers, no exporters, no
+ * network — returns immediately. Idempotent: a second call while already
+ * initialized is ignored.
+ *
+ * When enabled, starts a NodeSDK exporting traces + metrics over OTLP HTTP to
+ * `config.otelExporterOtlpEndpoint` (or the SDK default when unset), with a
+ * resource carrying `service.name = config.otelServiceName` and the build
+ * version.
+ */
+export function initTelemetry(config, build = { version: serviceVersion }) {
+    if (!config.enableTelemetry) {
+        return;
+    }
+    if (sdk !== undefined) {
+        return;
+    }
+    serviceVersion = build.version;
+    const resource = resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: config.otelServiceName,
+        [ATTR_SERVICE_VERSION]: build.version,
+    });
+    // The exporters read OTEL_EXPORTER_OTLP_ENDPOINT from their options; an
+    // undefined `url` lets the exporter fall back to its own env/default handling.
+    const traceExporter = new OTLPTraceExporter(config.otelExporterOtlpEndpoint !== undefined
+        ? { url: config.otelExporterOtlpEndpoint }
+        : {});
+    const metricExporter = new OTLPMetricExporter(config.otelExporterOtlpEndpoint !== undefined
+        ? { url: config.otelExporterOtlpEndpoint }
+        : {});
+    sdk = new NodeSDK({
+        resource,
+        traceExporter,
+        metricReaders: [new PeriodicExportingMetricReader({ exporter: metricExporter })],
+    });
+    sdk.start();
+}
+/**
+ * Stop telemetry and flush any buffered traces/metrics. A no-op when telemetry
+ * was never started (disabled), so callers can invoke it unconditionally in a
+ * shutdown path. Clears the module state so a later `initTelemetry` can start
+ * fresh.
+ */
+export async function shutdownTelemetry() {
+    if (sdk === undefined) {
+        return;
+    }
+    const stopping = sdk;
+    sdk = undefined;
+    await stopping.shutdown();
+}
+/** Whether telemetry is currently active. Exposed for tests + the helpers. */
+export function isTelemetryEnabled() {
+    return sdk !== undefined;
+}
+/** The relay's tracer (no-op tracer when telemetry is disabled). */
+function getTracer() {
+    return trace.getTracer(INSTRUMENTATION_SCOPE, serviceVersion);
+}
+/** The relay's meter (no-op meter when telemetry is disabled). */
+function getMeter() {
+    return metrics.getMeter(INSTRUMENTATION_SCOPE, serviceVersion);
+}
+/**
+ * Lazily-created call counter + latency histogram, shared across all tool
+ * calls. Created on first use so a disabled run never touches the metrics API
+ * beyond a no-op meter. When telemetry is disabled the instruments are no-op
+ * (the API returns inert instruments), so recording is free.
+ */
+let toolCallCounter;
+let toolLatencyHistogram;
+function getToolCallCounter() {
+    toolCallCounter ??= getMeter().createCounter('mcp.tool.calls', {
+        description: 'Count of MCP tool invocations, labeled by tool name + outcome.',
+        valueType: ValueType.INT,
+    });
+    return toolCallCounter;
+}
+function getToolLatencyHistogram() {
+    toolLatencyHistogram ??= getMeter().createHistogram('mcp.tool.duration', {
+        description: 'Latency of MCP tool invocations in milliseconds.',
+        unit: 'ms',
+        valueType: ValueType.DOUBLE,
+    });
+    return toolLatencyHistogram;
+}
+/**
+ * The structural shape of a matcher API error — read without importing
+ * `MatcherApiError` to keep this module free of a dependency on the matcher
+ * client. Only the numeric `status` is read, and only to label the outcome; no
+ * other field is touched. This is the ONLY error data telemetry records.
+ */
+function matcherStatusOf(err) {
+    if (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        typeof err.status === 'number') {
+        return err.status;
+    }
+    return undefined;
+}
+/**
+ * Wrap a tool's execution in a span + metrics. Opens a span named
+ * `mcp.tool.<name>`, records the call counter and the latency histogram, and on
+ * a thrown error marks the span error + records the matcher HTTP status when the
+ * thrown value carries one.
+ *
+ * Records ONLY: the tool name, the outcome (ok/error), and — on a matcher
+ * failure — the matcher HTTP status. It NEVER records the caller's token, the
+ * raw arguments, request headers, or any tenant identifier. When telemetry is
+ * disabled this is effectively just `fn()` (no-op tracer + inert instruments),
+ * so it is always safe to wrap a handler with it.
+ */
+export async function instrumentToolCall(name, fn) {
+    const tracer = getTracer();
+    const counter = getToolCallCounter();
+    const histogram = getToolLatencyHistogram();
+    const startedAt = Date.now();
+    return tracer.startActiveSpan(`mcp.tool.${name}`, async (span) => {
+        span.setAttribute(ATTR_TOOL_NAME, name);
+        try {
+            const result = await fn();
+            span.setAttribute(ATTR_OUTCOME, OUTCOME_OK);
+            span.setStatus({ code: SpanStatusCode.OK });
+            counter.add(1, { [ATTR_TOOL_NAME]: name, [ATTR_OUTCOME]: OUTCOME_OK });
+            return result;
+        }
+        catch (err) {
+            const status = matcherStatusOf(err);
+            span.setAttribute(ATTR_OUTCOME, OUTCOME_ERROR);
+            if (status !== undefined) {
+                span.setAttribute(ATTR_MATCHER_STATUS, status);
+            }
+            // Record only that the call failed and (when present) the matcher status.
+            // The error message is NOT recorded — it could be operator-influenced and
+            // is never worth the leakage risk.
+            span.setStatus({ code: SpanStatusCode.ERROR });
+            const attrs = {
+                [ATTR_TOOL_NAME]: name,
+                [ATTR_OUTCOME]: OUTCOME_ERROR,
+            };
+            if (status !== undefined) {
+                attrs[ATTR_MATCHER_STATUS] = status;
+            }
+            counter.add(1, attrs);
+            throw err;
+        }
+        finally {
+            histogram.record(Date.now() - startedAt, { [ATTR_TOOL_NAME]: name });
+            span.end();
+        }
+    });
+}
+/**
+ * Inject the current W3C trace context into an outbound header object so the
+ * matcher call is a child of the tool-call span (MCP → matcher correlation in
+ * the collector). The header object is mutated in place and returned for
+ * convenience. A no-op when telemetry is disabled (the no-op propagator writes
+ * nothing), so the matcher client can call it unconditionally.
+ *
+ * It writes ONLY W3C trace headers (`traceparent` / `tracestate`); it never
+ * reads or writes an `authorization` header, so the verbatim token relay is
+ * untouched.
+ */
+export function injectTraceContext(headers) {
+    propagation.inject(context.active(), headers);
+    return headers;
+}
+//# sourceMappingURL=otel.js.map

package/dist/observability/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../../src/observability/otel.ts"],"names":[],"mappings":"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"}