[logging] inspector: add deprecation guards, LOGGING.md, and ESLint enforcement (#1934)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Vu-John

mcpjam-inspector/eslint.config.js

@@ -0,0 +1,24 @@
+// @ts-check
+import tsParser from "@typescript-eslint/parser";
+
+export default [
+  {
+    files: ["server/routes/web/**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+    },
+    rules: {
+      "no-restricted-syntax": [
+        "warn",
+        {
+          selector:
+            "CallExpression[callee.type='MemberExpression'][callee.object.name='logger'][callee.property.name=/^(warn|error|info)$/]",
+          message:
+            "Use logger.event() for production diagnostics in server/routes/web/. " +
+            "Free-form logger.warn/error/info calls are not queryable in Axiom. " +
+            "See server/utils/LOGGING.md for the typed event catalog.",
+        },
+      ],
+    },
+  },
+];

mcpjam-inspector/package.json

@@ -191,6 +191,7 @@
     "@types/node": "^24",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "@typescript-eslint/parser": "^8.53.1",
     "@vitejs/plugin-react": "^4.3.4",
     "@vitest/coverage-v8": "^3.2.4",
     "autoprefixer": "^10.4.21",

mcpjam-inspector/server/routes/web/__tests__/helpers/test-app.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { vi } from "vitest";
 import webRoutes from "../../index.js";
+import { requestLogContextMiddleware } from "../../../../middleware/request-log-context.js";
 
 /**
  * Minimal mock for hosted-mode MCPClientManager.
@@ -15,6 +16,11 @@ export function createWebTestApp(options?: {
 }) {
   const app = new Hono();
 
+  // Mirror production wiring: requestLogContextMiddleware must run before any
+  // route that calls getRequestLogger (which throws when context is missing).
+  // Mounted at /api/* in production via server/app.ts.
+  app.use("/api/*", requestLogContextMiddleware);
+
   // Inject a no-op mcpClientManager (web routes create their own)
   app.use("*", async (c, next) => {
     (c as any).mcpClientManager = {};

mcpjam-inspector/server/utils/LOGGING.md

@@ -0,0 +1,81 @@
+# Server Logging Conventions
+
+## Quick rule
+
+- **New production diagnostics in `server/routes/`** → use `logger.event()` via `getRequestLogger`
+- **Ad-hoc debugging anywhere** → `logger.debug()` is fine
+- **Legacy code outside converted routes** → `logger.warn/error` remain; migrate opportunistically
+
+---
+
+## Why typed events?
+
+`logger.warn("something failed", { ... })` produces unstructured Axiom rows that are hard to query.
+`logger.event("tunnel.created", ...)` produces a row you can filter by `event`, `workspaceId`, `orgId`, `route`, etc. without grepping prose.
+
+---
+
+## How to emit a typed event from a route handler
+
+```ts
+import { getRequestLogger } from "../../utils/request-logger.js";
+import { classifyError } from "../../utils/error-classify.js";
+
+// inside a Hono handler that has `c: Context`
+getRequestLogger(c, "routes.web.tools").event("mcp.tool.execution.failed", {
+  toolName: body.toolName,
+  serverId: body.serverId,
+  errorCode: classifyError(error),
+});
+```
+
+The request context (`workspaceId`, `orgId`, `workspaceRole`, etc.) is automatically
+picked up from `c.var.requestLogContext`, which is populated by:
+1. `requestLogContextMiddleware` at request start (sets `requestId`, `route`, `method`)
+2. `authorizeServer` / `createAuthorizedManager` after Convex auth succeeds (sets workspace + user fields)
+
+---
+
+## Event catalog
+
+| Event | Emitted from | Key payload fields |
+|---|---|---|
+| `http.request.completed` | middleware | `statusCode` |
+| `http.request.failed` | middleware | `statusCode`, `errorCode` |
+| `mcp.oauth.proxy.failed` | `routes/mcp/oauth.ts`, `routes/web/oauth.ts` | `targetUrlHost`, `oauthPhase`, `errorCode`, `statusCode?` |
+| `mcp.tool.execution.failed` | `routes/web/tools.ts` | `toolName`, `serverId?`, `errorCode` |
+| `tunnel.created` | `routes/mcp/tunnels.ts` | `tunnelKind`, `tunnelDomain`, `existed`, `credentialIdPresent?` |
+| `tunnel.creation_failed` | `routes/mcp/tunnels.ts` | `tunnelKind`, `errorCode` |
+| `tunnel.record_failed` | `routes/mcp/tunnels.ts` | `tunnelKind`, `tunnelDomain?`, `errorCode` |
+| `chat.session.persist.failed` | `utils/chat-ingestion.ts` | `failureKind`, `statusCode?`, `sourceType?` |
+| `widget.resource.served` | `routes/apps/mcp-apps/index.ts` | `widgetType`, `resourceUri`, `cspMode`, `mimeTypeValid?` |
+| `widget.resource.failed` | `routes/apps/mcp-apps/index.ts` | `widgetType`, `resourceUri?`, `errorCode` |
+| `mcp.connection.closed_with_pending_requests` | `index.ts` (system event) | `errorCode` |
+
+All events live in `server/utils/log-events.ts`. Add new events there before emitting them.
+
+---
+
+## Adding a new event
+
+1. Add the event name and payload type to `RequestEventMap` (or `SystemEventMap`) in `log-events.ts`.
+2. Emit it with `getRequestLogger(c, "routes.your.component").event("your.event.name", payload)`.
+3. Add a row to the catalog table above.
+
+---
+
+## Scrubbing
+
+All payloads are scrubbed by `scrubLogPayload` before reaching Axiom. Forbidden key substrings
+(token, secret, email, authorization, cookie, apikey, stripe\*, pkce\*) are replaced with `"[redacted]"`.
+String values are scanned for Bearer tokens, JWTs, email addresses, and `sk-` keys.
+
+Never put raw error messages containing user input directly into event payloads without first
+verifying they don't carry secrets.
+
+---
+
+## ESLint enforcement
+
+`eslint.config.js` warns on new `logger.warn|error|info` calls in `server/routes/web/`.
+Run `npx eslint server/routes/web/` to check before committing route changes.

mcpjam-inspector/server/utils/__tests__/chat-ingestion.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { Context } from "hono";
 import { persistChatSessionToConvex } from "../chat-ingestion";
+import type { RequestLogContext } from "../log-events";
 
 const mockLogger = vi.hoisted(() => ({
   warn: vi.fn(),
@@ -11,6 +12,31 @@ vi.mock("../logger", () => ({
   logger: mockLogger,
 }));
 
+// Mirror the production envelope populated by requestLogContextMiddleware.
+// Without this, getRequestLogger throws — the strict-throw was added in the
+// typed-event foundation to surface wiring bugs, so test fixtures must reflect
+// real production wiring.
+function makeTestContext(): Context {
+  const baseContext: RequestLogContext = {
+    event: "http.request.completed",
+    timestamp: "2024-01-01T00:00:00.000Z",
+    environment: "test",
+    release: null,
+    component: "http",
+    requestId: "test-req",
+    route: "/api/web/test",
+    method: "POST",
+    authType: "unknown",
+  };
+  const vars: Record<string, unknown> = { requestLogContext: baseContext };
+  return {
+    var: new Proxy(vars, { get: (t, p) => t[p as string] }),
+    set: vi.fn((key: string, value: unknown) => {
+      vars[key] = value;
+    }),
+  } as unknown as Context;
+}
+
 describe("chat-ingestion", () => {
   const originalFetch = global.fetch;
 
@@ -211,7 +237,7 @@ describe("chat-ingestion", () => {
         headers: { "Content-Type": "application/json" },
       }),
     );
-    const c = { var: {}, set: vi.fn() } as unknown as Context;
+    const c = makeTestContext();
 
     await persistChatSessionToConvex(
       {
@@ -238,7 +264,7 @@ describe("chat-ingestion", () => {
     global.fetch = vi.fn().mockResolvedValue(
       new Response("Server Error", { status: 503 }),
     );
-    const c = { var: {}, set: vi.fn() } as unknown as Context;
+    const c = makeTestContext();
 
     await persistChatSessionToConvex(
       {
@@ -274,7 +300,7 @@ describe("chat-ingestion", () => {
           }
         }),
     ) as typeof fetch;
-    const c = { var: {}, set: vi.fn() } as unknown as Context;
+    const c = makeTestContext();
 
     const p = persistChatSessionToConvex(
       {
@@ -301,7 +327,7 @@ describe("chat-ingestion", () => {
 
   it("emits chat.session.persist.failed(exception) via typed event when c is provided", async () => {
     global.fetch = vi.fn().mockRejectedValue(new Error("network failure"));
-    const c = { var: {}, set: vi.fn() } as unknown as Context;
+    const c = makeTestContext();
 
     await persistChatSessionToConvex(
       {

mcpjam-inspector/server/utils/logger.ts

@@ -47,6 +47,10 @@ function ingestToAxiom(
 export const logger = {
   /**
    * Log an error. Always sends to Sentry and Axiom, only prints to console in dev/verbose mode.
+   *
+   * NOTE: For new production diagnostics in `server/routes/web/`, prefer `logger.event()` —
+   * free-form messages are not queryable in Axiom. Legacy callers (CLI, system code,
+   * non-route utilities) remain on this API. See `server/utils/LOGGING.md`.
    */
   error(message: string, error?: unknown, context?: Record<string, unknown>) {
     Sentry.captureException(error ?? new Error(message), {
@@ -65,6 +69,10 @@ export const logger = {
 
   /**
    * Log a warning. Always sends to Sentry and Axiom, only prints to console in dev/verbose mode.
+   *
+   * NOTE: For new production diagnostics in `server/routes/web/`, prefer `logger.event()` —
+   * free-form messages are not queryable in Axiom. Legacy callers (CLI, system code,
+   * non-route utilities) remain on this API. See `server/utils/LOGGING.md`.
    */
   warn(message: string, context?: Record<string, unknown>) {
     Sentry.captureMessage(message, { level: "warning", extra: context });
@@ -78,6 +86,10 @@ export const logger = {
 
   /**
    * Log info. Always sends to Axiom. Only prints to console in dev/verbose mode.
+   *
+   * NOTE: For new production diagnostics in `server/routes/web/`, prefer `logger.event()` —
+   * free-form messages are not queryable in Axiom. Legacy callers (CLI, system code,
+   * non-route utilities) remain on this API. See `server/utils/LOGGING.md`.
    */
   info(message: string, context?: Record<string, unknown>) {
     ingestToAxiom("info", message, context);