Merge origin/main into feat/agentic-teams

Conflict in src/mcpd/src/main.ts: both sides touched the import block. Kept this branch's mapUrlToPermission plus main's bootstrapUngatedGlobal; dropped main's SET_OWN_PASSWORD_OPERATION import — this branch moved that usage into middleware/url-permission.ts, which imports it itself. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-10-09 15:32:03 +01:00
parent 70bc7f1598 5415060de6
commit 24f202cb79
50 changed files with 1621 additions and 63 deletions
--- a/src/mcplocal/src/discovery.ts
+++ b/src/mcplocal/src/discovery.ts
@@ -11,6 +11,12 @@ interface McpdServer {
  status?: string;
  /** Per-server tool-call deadline override, in seconds. Null = use the global. */
  toolCallTimeoutSeconds?: number | null;
+  /**
+   * True when the server comes from the `ungated-global` system project
+   * rather than this project's own attachments. mcplocal exempts such
+   * servers from the gate: their tools are listed and callable pre-begin_session.
+   */
+  ungatedGlobal?: boolean;
 }

 /**
@@ -28,12 +34,19 @@ export async function refreshUpstreams(router: McpRouter, mcpdClient: McpdClient
 *
 * @param authToken - Optional bearer token forwarded to mcpd for RBAC checks.
 */
+export interface ProjectUpstreams {
+  /** Names of all registered upstream servers. */
+  names: string[];
+  /** Subset that came from the ungated-global project (gate-exempt). */
+  ungatedServers: string[];
+}
+
 export async function refreshProjectUpstreams(
  router: McpRouter,
  mcpdClient: McpdClient,
  projectName: string,
  authToken?: string,
-): Promise<string[]> {
+): Promise<ProjectUpstreams> {
  const path = `/api/v1/projects/${encodeURIComponent(projectName)}/servers`;

  let servers: McpdServer[];
@@ -54,7 +67,11 @@ export async function refreshProjectUpstreams(
  // Bind a per-request client with the caller's bearer so each McpdUpstream
  // forwards the same identity that passed project discovery.
  const upstreamClient = authToken ? mcpdClient.withToken(authToken) : mcpdClient;
-  return syncUpstreams(router, upstreamClient, servers);
+  const names = await syncUpstreams(router, upstreamClient, servers);
+  return {
+    names,
+    ungatedServers: servers.filter((s) => s.ungatedGlobal === true).map((s) => s.name),
+  };
 }

 /**
@@ -167,12 +184,16 @@ function syncUpstreams(router: McpRouter, mcpdClient: McpdClient, servers: McpdS
    }
  }

-  // Add/update upstreams for each server
+  // Add/update upstreams for each server. Always rebuild, even when an
+  // upstream with this name already exists: McpdUpstream binds the caller's
+  // bearer token (and the server id) at construction, and a cached project
+  // router outlives both. Reusing the old object meant a token rotation left
+  // every pre-rotation server silently 401-ing on tools/list — attached,
+  // healthy, zero tools, no error — while servers attached after the rotation
+  // worked, because only THEY got an upstream carrying the fresh token.
  for (const server of servers) {
-    if (!currentNames.has(server.name)) {
-      const upstream = new McpdUpstream(server.id, server.name, toolClient, server.description, discoveryClient);
-      router.addUpstream(upstream);
-    }
+    const upstream = new McpdUpstream(server.id, server.name, toolClient, server.description, discoveryClient);
+    router.addUpstream(upstream);
    // Applied on every sync, not just on first registration: raising a
    // server's timeout should take effect at the next refresh rather than
    // requiring the upstream to be dropped and rebuilt.
--- a/src/mcplocal/src/http/project-mcp-endpoint.ts
+++ b/src/mcplocal/src/http/project-mcp-endpoint.ts
@@ -22,6 +22,8 @@ import type { TrafficCapture } from './traffic.js';
 import { LLMProviderAdapter } from '../proxymodel/llm-adapter.js';
 import { FileCache } from '../proxymodel/file-cache.js';
 import { createDefaultPlugin } from '../proxymodel/plugins/default.js';
+import { createAmbientContextPlugin } from '../proxymodel/plugins/ambient-context.js';
+import { ambientContextLine } from '@mcpctl/shared';
 import { createAgentsPlugin } from '../proxymodel/plugins/agents.js';
 import { createFavouriteIndexPlugin } from '../proxymodel/plugins/favourite-index.js';
 import { composePlugins } from '../proxymodel/plugins/compose.js';
@@ -92,7 +94,7 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp

    // Create new router or refresh existing one
    const router = existing?.router ?? new McpRouter();
-    await refreshProjectUpstreams(router, mcpdClient, projectName, authToken);
+    const { ungatedServers } = await refreshProjectUpstreams(router, mcpdClient, projectName, authToken);

    // Resolve project LLM model: local override → mcpd recommendation → global default
    const localOverride = loadProjectLlmOverride(projectName);
@@ -163,6 +165,9 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
      providerRegistry: effectiveRegistry,
    };
    if (resolvedModel) pluginConfig.modelOverride = resolvedModel;
+    // Servers from the ungated-global project bypass the gate: listed and
+    // callable before begin_session, in every project.
+    if (ungatedServers.length > 0) pluginConfig.ungatedServers = ungatedServers;
    // Route gate prompt-selection through a server Llm (mcpd inference proxy)
    // so cloud/server keys stay at the k8s level; the local personal-token
    // provider is the fallback. See credential-tiering. A dedicated fast
@@ -190,6 +195,11 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
    // project show up as virtual MCP servers in tools/list, regardless of
    // which proxymodel the project is using.
    chain.push(createAgentsPlugin());
+    // Ambient context LAST: its onToolsList must see the gate's finished
+    // catalog (append get_current_time only when ungated), and its
+    // date/project instruction line belongs at the end of the merged
+    // instructions. Always on for every project.
+    chain.push(createAmbientContextPlugin());
    router.setPlugin(composePlugins(chain));

    // Fetch project instructions and set on router. Must ride the CALLER's
@@ -247,6 +257,24 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
    return response;
  }

+  /**
+   * Append the ambient "now" line to every tools/call result as a SEPARATE
+   * trailing content item — never mutate existing items, so clients that
+   * JSON.parse a single text item keep working. Endpoint-level on purpose:
+   * this is the only chokepoint that also covers virtual tools (which bypass
+   * plugin onToolCallAfter), gate intercepts, drill-down pages, and
+   * failureResponse results. Initialize instructions carry the same line but
+   * freeze at session start; this trailer is what keeps a days-old chat
+   * session's model on today's date.
+   */
+  function appendAmbientTrailer(response: unknown, method?: string): unknown {
+    if (method !== 'tools/call') return response;
+    const r = response as { result?: { content?: unknown } };
+    if (!r.result || !Array.isArray(r.result.content)) return response;
+    r.result.content.push({ type: 'text', text: ambientContextLine() });
+    return response;
+  }
+
  /**
   * Turn a deadline or an unexpected throw into something the client can read.
   *
@@ -523,7 +551,10 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp

        try {
          await transport.send(
-            maybeAnnotateRecreation(response, sid, method) as unknown as JSONRPCMessage,
+            appendAmbientTrailer(
+              maybeAnnotateRecreation(response, sid, method),
+              method,
+            ) as unknown as JSONRPCMessage,
          );
        } catch (sendErr) {
          console.error(
--- a/src/mcplocal/src/proxymodel/plugin-context.ts
+++ b/src/mcplocal/src/proxymodel/plugin-context.ts
@@ -19,6 +19,7 @@ export interface PluginContextDeps {
  cache: CacheProvider;
  log: StageLogger;
  discoverTools: () => Promise<ToolDefinition[]>;
+  getToolDiscoveryFailures?: () => Array<{ server: string; message: string }>;
  routeToUpstream: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
  fetchPromptIndex: () => Promise<PromptIndexEntry[]>;
  getSystemPrompt: (name: string, fallback: string) => Promise<string>;
@@ -96,6 +97,10 @@ export class PluginContextImpl implements PluginSessionContext {
    return this.deps.discoverTools();
  }

+  getToolDiscoveryFailures(): Array<{ server: string; message: string }> {
+    return this.deps.getToolDiscoveryFailures?.() ?? [];
+  }
+
  routeToUpstream(request: JsonRpcRequest): Promise<JsonRpcResponse> {
    return this.deps.routeToUpstream(request);
  }
--- a/src/mcplocal/src/proxymodel/plugin.ts
+++ b/src/mcplocal/src/proxymodel/plugin.ts
@@ -36,6 +36,8 @@ export interface PluginSessionContext {

  // Upstream access
  discoverTools(): Promise<ToolDefinition[]>;
+  /** Servers that contributed no tools on the last discoverTools run, with the error. */
+  getToolDiscoveryFailures(): Array<{ server: string; message: string }>;
  routeToUpstream(request: JsonRpcRequest): Promise<JsonRpcResponse>;

  // Prompt access
--- a/src/mcplocal/src/proxymodel/plugins/ambient-context.ts
+++ b/src/mcplocal/src/proxymodel/plugins/ambient-context.ts
@@ -0,0 +1,56 @@
+/**
+ * Ambient Context plugin — gives every project's model a clock.
+ *
+ * Always on, composed LAST in the project plugin chain so that:
+ *  - onToolsList sees the gate's (and favourite-index's) finished list and
+ *    only appends get_current_time to UNGATED catalogs;
+ *  - its onInitialize line lands at the end of the merged instructions.
+ *
+ * The per-result "[context] now: …" trailer deliberately does NOT live here:
+ * virtual tools bypass plugin onToolCallAfter entirely (router dispatches
+ * them first), so the only chokepoint covering every tools/call result is
+ * endpoint-level — see appendAmbientTrailer in http/project-mcp-endpoint.ts.
+ */
+import { ambientContextLine, formatCurrentTimeResult } from '@mcpctl/shared';
+import type { ProxyModelPlugin } from '../plugin.js';
+import type { ToolDefinition } from '../types.js';
+
+export const GET_CURRENT_TIME_TOOL_NAME = 'get_current_time';
+
+function getCurrentTimeTool(): ToolDefinition {
+  return {
+    name: GET_CURRENT_TIME_TOOL_NAME,
+    description:
+      'Current date and time, in UTC and the configured local timezone. '
+      + 'Call this whenever a task depends on today\'s date or the current time.',
+    inputSchema: { type: 'object', properties: {} },
+  };
+}
+
+export function createAmbientContextPlugin(): ProxyModelPlugin {
+  return {
+    name: 'ambient-context',
+
+    async onSessionCreate(ctx) {
+      // Registered unconditionally: virtual dispatch precedes the gate
+      // intercept, so the tool is callable even while gated (same as
+      // read_prompts today). Visibility is controlled in onToolsList.
+      ctx.registerTool(getCurrentTimeTool(), async () => ({
+        content: [{ type: 'text', text: formatCurrentTimeResult() }],
+      }));
+    },
+
+    async onInitialize(_request, ctx) {
+      return { instructions: `${ambientContextLine()} — project: ${ctx.projectName}` };
+    },
+
+    async onToolsList(tools) {
+      // A gated catalog is [begin_session, ...gate-exempt ungated-global
+      // tools] (gate.ts onToolsList); begin_session never appears in an
+      // ungated list, so its presence remains the gated marker.
+      if (tools.some((t) => t.name === 'begin_session')) return tools;
+      if (tools.some((t) => t.name === GET_CURRENT_TIME_TOOL_NAME)) return tools;
+      return [...tools, getCurrentTimeTool()];
+    },
+  };
+}
--- a/src/mcplocal/src/proxymodel/plugins/gate.ts
+++ b/src/mcplocal/src/proxymodel/plugins/gate.ts
@@ -7,6 +7,7 @@
 *
 * This plugin replaces the hardcoded gate logic in router.ts.
 */
+import { ambientContextLine } from '@mcpctl/shared';
 import type { JsonRpcRequest, JsonRpcResponse } from '../../types.js';
 import type { ToolDefinition } from '../types.js';
 import type { ProxyModelPlugin, PluginSessionContext } from '../plugin.js';
@@ -54,6 +55,12 @@ export interface GatePluginConfig {
   * personal-token provider registry. See credential-tiering principle.
   */
  llmProvider?: string;
+  /**
+   * Server names (canonical, as in `server/tool`) exempt from the gate —
+   * typically servers of the ungated-global project. Their tools are listed
+   * and callable while the session is still gated.
+   */
+  ungatedServers?: string[];
 }

 const MAX_RESPONSE_CHARS = 24_000;
@@ -72,6 +79,13 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
  // Per-session state tracking (plugin-scoped, not global SessionGate)
  const sessionGate = new SessionGate();

+  // Gate-exempt servers (ungated-global project): tools pass the gate untouched.
+  const ungatedSet = new Set(config.ungatedServers ?? []);
+  const isGateExempt = (toolName: string): boolean => {
+    const slash = toolName.indexOf('/');
+    return slash > 0 && ungatedSet.has(toolName.slice(0, slash));
+  };
+
  return {
    name: 'gate',
    description: 'Gated session flow: begin_session → prompt selection → ungate.',
@@ -121,12 +135,21 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
      // canonical `server/tool` would name functions the model cannot call.
      try {
        const tools = await ctx.discoverTools();
-        if (tools.length > 0) {
-          parts.push('\nAvailable MCP server tools (accessible after begin_session):');
-          for (const t of tools) {
+        const exempt = tools.filter((t) => isGateExempt(t.name));
+        const gatedTools = tools.filter((t) => !isGateExempt(t.name));
+        if (exempt.length > 0) {
+          parts.push('\nAvailable immediately (no begin_session required):');
+          for (const t of exempt) {
            parts.push(`  ${sanitizeWireName(t.name)}`);
          }
        }
+        if (gatedTools.length > 0) {
+          parts.push('\nAvailable MCP server tools (accessible after begin_session):');
+          for (const t of gatedTools) {
+            parts.push(`  ${sanitizeWireName(t.name)}`);
+          }
+        }
+        parts.push(...formatDiscoveryFailures(ctx.getToolDiscoveryFailures()));
      } catch {
        // Tool discovery is optional
      }
@@ -158,9 +181,9 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
    },

    async onToolsList(tools, ctx) {
-      // When gated, only show begin_session
+      // When gated, show begin_session plus any gate-exempt (ungated-global) tools
      if (sessionGate.isGated(ctx.sessionId)) {
-        return [getBeginSessionTool(llmSelector)];
+        return [getBeginSessionTool(llmSelector), ...tools.filter((t) => isGateExempt(t.name))];
      }

      // When ungated, show upstream tools + read_prompts + propose_prompt (no begin_session)
@@ -168,8 +191,9 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
    },

    async onToolCallBefore(toolName, args, request, ctx) {
-      // If gated and trying to call a real tool, auto-ungate via keyword extraction
-      if (sessionGate.isGated(ctx.sessionId)) {
+      // If gated and trying to call a real tool, auto-ungate via keyword extraction.
+      // Gate-exempt (ungated-global) tools pass straight through without ungating.
+      if (sessionGate.isGated(ctx.sessionId) && !isGateExempt(toolName)) {
        return handleGatedIntercept(request, ctx, toolName, args, sessionGate, tagMatcher);
      }
      return null;
@@ -177,6 +201,22 @@ export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugi
  };
 }

+/**
+ * A partial catalog must never look like a healthy one. When attached servers
+ * contributed no tools, say so in-band — the client has no other channel to
+ * learn that six servers silently vanished from its tool list.
+ */
+function formatDiscoveryFailures(failures: Array<{ server: string; message: string }>): string[] {
+  if (failures.length === 0) return [];
+  const parts: string[] = [];
+  parts.push(`\n⚠ WARNING: ${failures.length} attached server(s) contributed NO tools to this catalog:`);
+  for (const f of failures) {
+    parts.push(`  - ${f.server}: ${f.message}`);
+  }
+  parts.push('The tool list above is INCOMPLETE. Report this to the user instead of treating a missing tool as nonexistent.');
+  return parts;
+}
+
 // ── begin_session tool definition ──

 function getBeginSessionTool(llmSelector: LlmPromptSelector | null): ToolDefinition {
@@ -396,6 +436,10 @@ async function handleBeginSession(
  // Build response
  const responseParts: string[] = [];

+  // The model starting this session has no clock; the briefing anchors it.
+  // (The endpoint's per-result trailer keeps later turns current.)
+  responseParts.push(`${ambientContextLine()}\n`);
+
  if (degradedReason !== null) {
    responseParts.push(
      `⚠ Smart prompt-selection unavailable (${degradedReason}). `
@@ -442,6 +486,7 @@ async function handleBeginSession(
        responseParts.push(`  ${sanitizeWireName(t.name)}`);
      }
    }
+    responseParts.push(...formatDiscoveryFailures(ctx.getToolDiscoveryFailures()));
  } catch {
    // Tool discovery is optional
  }
--- a/src/mcplocal/src/router.ts
+++ b/src/mcplocal/src/router.ts
@@ -75,6 +75,8 @@ export class McpRouter {
  // `tools/list` from re-hitting slow/dead upstreams and absorbs negative results so one
  // dead server only stalls the first POST, not every subsequent one.
  private listCache = new Map<string, ListCacheEntry>();
+  /** Per-server failures from the most recent discoverTools run. */
+  private toolDiscoveryFailures: Array<{ server: string; message: string }> = [];
  private readonly LIST_CACHE_POSITIVE_TTL_MS = 30_000;
  private readonly LIST_CACHE_NEGATIVE_TTL_MS = 30_000;

@@ -176,6 +178,7 @@ export class McpRouter {
        error: (msg: string) => console.error(`[plugin:${sessionId.slice(0, 8)}] ${msg}`),
      },
      discoverTools: () => this.discoverTools(),
+      getToolDiscoveryFailures: () => this.getToolDiscoveryFailures(),
      routeToUpstream: (request) => this.routeNamespacedCall(request, 'name', this.toolToServer),
      fetchPromptIndex: () => this.fetchPromptIndex(),
      getSystemPrompt: (name, fallback) => this.getSystemPrompt(name, fallback),
@@ -329,7 +332,7 @@ export class McpRouter {
    const started = Date.now();
    let cachedCount = 0;
    let freshCount = 0;
-    const failed: string[] = [];
+    const failed: Array<{ server: string; message: string }> = [];

    // Discover tools from all servers in parallel so one slow server doesn't block the rest
    const entries = [...this.upstreams.entries()];
@@ -369,7 +372,7 @@ export class McpRouter {
        const cached = result.value.cached;
        if (cached.kind === 'err') {
          cachedCount++;
-          failed.push(serverName);
+          failed.push({ server: serverName, message: cached.message });
          continue;
        }
        response = { jsonrpc: '2.0', id: `cached-${serverName}`, result: cached.result };
@@ -381,7 +384,7 @@ export class McpRouter {
          const message = (response.error as { message?: string }).message ?? 'unknown error';
          this.setListCacheEntry(serverName, 'tools/list', { kind: 'err', message, fetchedAt: Date.now() });
          console.warn(`[discoverTools] ${serverName}: ${message}`);
-          failed.push(serverName);
+          failed.push({ server: serverName, message });
          continue;
        }
        if (response.result !== undefined) {
@@ -410,16 +413,27 @@ export class McpRouter {
      }
    }

+    this.toolDiscoveryFailures = failed;
+
    if (entries.length > 0) {
      const elapsed = Date.now() - started;
      const project = this.projectName ? ` project=${this.projectName}` : '';
-      const failedStr = failed.length > 0 ? ` failed=[${failed.join(',')}]` : '';
+      const failedStr = failed.length > 0 ? ` failed=[${failed.map((f) => f.server).join(',')}]` : '';
      console.info(`[discoverTools]${project} fresh=${freshCount} cached=${cachedCount}${failedStr} elapsed=${elapsed}ms`);
    }

    return allTools;
  }

+  /**
+   * Servers that contributed no tools on the most recent `discoverTools` run,
+   * with the error that silenced them. A partial catalog must never look like
+   * a healthy one: the gate reads this to warn the client in-band.
+   */
+  getToolDiscoveryFailures(): Array<{ server: string; message: string }> {
+    return this.toolDiscoveryFailures;
+  }
+
  /**
   * Discover resources from all upstreams by calling resources/list on each.
   * Shares the per-server list cache with `discoverTools`.
--- a/src/mcplocal/tests/ambient-time.test.ts
+++ b/src/mcplocal/tests/ambient-time.test.ts
@@ -0,0 +1,75 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+  AMBIENT_TZ_ENV,
+  ambientTz,
+  formatAmbientNow,
+  ambientContextLine,
+  formatCurrentTimeResult,
+} from '@mcpctl/shared';
+
+const SUMMER = new Date('2026-07-01T09:30:00Z'); // London = BST, +01:00
+const WINTER = new Date('2026-01-15T09:30:00Z'); // London = GMT, +00:00
+
+afterEach(() => {
+  delete process.env[AMBIENT_TZ_ENV];
+});
+
+describe('ambientTz', () => {
+  it('returns undefined when unset', () => {
+    delete process.env[AMBIENT_TZ_ENV];
+    expect(ambientTz()).toBeUndefined();
+  });
+
+  it('returns a valid IANA name', () => {
+    process.env[AMBIENT_TZ_ENV] = 'Europe/London';
+    expect(ambientTz()).toBe('Europe/London');
+  });
+
+  it('falls back to undefined on an invalid name without throwing', () => {
+    process.env[AMBIENT_TZ_ENV] = 'Not/AZone';
+    expect(ambientTz()).toBeUndefined();
+  });
+});
+
+describe('formatAmbientNow', () => {
+  it('renders UTC-only when no tz', () => {
+    expect(formatAmbientNow(SUMMER, undefined)).toBe('Wed 2026-07-01 09:30 UTC');
+  });
+
+  it('renders local + UTC in summer (BST +01:00)', () => {
+    expect(formatAmbientNow(SUMMER, 'Europe/London'))
+      .toBe('Wed 2026-07-01 10:30 +01:00 Europe/London (09:30 UTC)');
+  });
+
+  it('renders local + UTC in winter (GMT +00:00)', () => {
+    expect(formatAmbientNow(WINTER, 'Europe/London'))
+      .toBe('Thu 2026-01-15 09:30 +00:00 Europe/London (09:30 UTC)');
+  });
+
+  it('stays short (~15 tokens)', () => {
+    expect(formatAmbientNow(SUMMER, 'Europe/London').length).toBeLessThan(70);
+  });
+});
+
+describe('ambientContextLine', () => {
+  it('prefixes with [context] now:', () => {
+    delete process.env[AMBIENT_TZ_ENV];
+    expect(ambientContextLine(SUMMER)).toBe('[context] now: Wed 2026-07-01 09:30 UTC');
+  });
+});
+
+describe('formatCurrentTimeResult', () => {
+  it('includes UTC ISO and epoch, no local line when tz unset', () => {
+    delete process.env[AMBIENT_TZ_ENV];
+    const text = formatCurrentTimeResult(SUMMER);
+    expect(text).toContain('UTC: 2026-07-01T09:30:00.000Z');
+    expect(text).toContain(`Unix epoch seconds: ${Math.floor(SUMMER.getTime() / 1000)}`);
+    expect(text).not.toContain('Europe/London');
+  });
+
+  it('includes the local rendering when tz set', () => {
+    process.env[AMBIENT_TZ_ENV] = 'Europe/London';
+    const text = formatCurrentTimeResult(SUMMER);
+    expect(text).toContain('Europe/London: Wed 2026-07-01 10:30 +01:00 Europe/London (09:30 UTC)');
+  });
+});
--- a/src/mcplocal/tests/discovery.test.ts
+++ b/src/mcplocal/tests/discovery.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { refreshUpstreams } from '../src/discovery.js';
+import { refreshUpstreams, refreshProjectUpstreams } from '../src/discovery.js';
 import { McpRouter } from '../src/router.js';

 function mockMcpdClient(servers: Array<{ id: string; name: string; transport: string }>) {
@@ -69,3 +69,61 @@ describe('refreshUpstreams', () => {
    expect(router.getUpstreamNames()).toHaveLength(0);
  });
 });
+
+describe('refreshProjectUpstreams', () => {
+  /**
+   * Regression: a cached project router outlives the caller's bearer token.
+   * Upstreams used to be created only for NEW server names, so after a token
+   * rotation every pre-existing upstream kept posting the old token — six
+   * healthy servers 401'd on tools/list forever while newly attached ones
+   * worked. Every refresh must rebind existing upstreams to the fresh token.
+   */
+  it('rebinds existing upstreams to the current auth token on every refresh', async () => {
+    const router = new McpRouter();
+    const servers = [{ id: 'srv-1', name: 'gitea', transport: 'stdio' }];
+
+    // Base client: withToken(t) mints a child client whose posts we can count.
+    const children = new Map<string, ReturnType<typeof mockMcpdClient>>();
+    const base = mockMcpdClient(servers);
+    (base as any).forward = vi.fn(async () => ({ status: 200, body: servers }));
+    (base as any).withToken = vi.fn((t: string) => {
+      if (!children.has(t)) {
+        const child = mockMcpdClient(servers);
+        child.post = vi.fn(async () => ({ result: { tools: [{ name: 'merge_pull_request' }] } }));
+        children.set(t, child);
+      }
+      return children.get(t);
+    });
+
+    await refreshProjectUpstreams(router, base as any, 'sre', 'old-token');
+    await refreshProjectUpstreams(router, base as any, 'sre', 'new-token');
+
+    const tools = await router.discoverTools();
+    expect(tools.map((t) => t.name)).toEqual(['gitea/merge_pull_request']);
+    // The proxy call must ride the NEW token's client, not the stale one.
+    expect(children.get('new-token')!.post).toHaveBeenCalledWith('/api/v1/mcp/proxy', expect.anything());
+    expect(children.get('old-token')!.post).not.toHaveBeenCalled();
+  });
+
+  it('updates the server id when a server was recreated under the same name', async () => {
+    const router = new McpRouter();
+    const base = mockMcpdClient([]);
+    const posts: unknown[] = [];
+    const child = mockMcpdClient([]);
+    child.post = vi.fn(async (_path: string, body: unknown) => {
+      posts.push(body);
+      return { result: { tools: [] } };
+    });
+    (base as any).withToken = vi.fn(() => child);
+    (base as any).forward = vi.fn()
+      .mockResolvedValueOnce({ status: 200, body: [{ id: 'srv-old', name: 'gitea', transport: 'stdio' }] })
+      .mockResolvedValueOnce({ status: 200, body: [{ id: 'srv-new', name: 'gitea', transport: 'stdio' }] });
+
+    await refreshProjectUpstreams(router, base as any, 'sre', 't');
+    await refreshProjectUpstreams(router, base as any, 'sre', 't');
+
+    await router.discoverTools();
+    expect(posts).toHaveLength(1);
+    expect((posts[0] as { serverId: string }).serverId).toBe('srv-new');
+  });
+});
--- a/src/mcplocal/tests/plugin-ambient-context.test.ts
+++ b/src/mcplocal/tests/plugin-ambient-context.test.ts
@@ -0,0 +1,117 @@
+/**
+ * ambient-context plugin tests — get_current_time visibility (gated vs
+ * ungated, no double-append), callable result, and the initialize
+ * instruction line. Driven through a real McpRouter with the gate composed
+ * first, mirroring project-mcp-endpoint wiring (ambient-context LAST).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { McpRouter } from '../src/router.js';
+import type { UpstreamConnection, JsonRpcRequest, JsonRpcResponse } from '../src/types.js';
+import type { McpdClient } from '../src/http/mcpd-client.js';
+import { createGatePlugin } from '../src/proxymodel/plugins/gate.js';
+import { composePlugins } from '../src/proxymodel/plugins/compose.js';
+import {
+  createAmbientContextPlugin,
+  GET_CURRENT_TIME_TOOL_NAME,
+} from '../src/proxymodel/plugins/ambient-context.js';
+import type { LLMProviderAdapter } from '../src/proxymodel/llm-adapter.js';
+import { MemoryCache } from '../src/proxymodel/cache.js';
+
+function mockUpstream(name: string, tools: Array<{ name: string }>): UpstreamConnection {
+  return {
+    name,
+    isAlive: vi.fn(() => true),
+    close: vi.fn(async () => {}),
+    onNotification: vi.fn(),
+    send: vi.fn(async (req: JsonRpcRequest): Promise<JsonRpcResponse> => {
+      if (req.method === 'tools/list') return { jsonrpc: '2.0', id: req.id, result: { tools } };
+      if (req.method === 'resources/list') return { jsonrpc: '2.0', id: req.id, result: { resources: [] } };
+      if (req.method === 'prompts/list') return { jsonrpc: '2.0', id: req.id, result: { prompts: [] } };
+      return { jsonrpc: '2.0', id: req.id, error: { code: -32601, message: 'Not found' } };
+    }),
+  } as UpstreamConnection;
+}
+
+function mockMcpdClient(): McpdClient {
+  return {
+    get: vi.fn(async () => []),
+    post: vi.fn(async () => ({})),
+    put: vi.fn(async () => ({})),
+    delete: vi.fn(async () => {}),
+    forward: vi.fn(async () => ({ status: 200, body: {} })),
+    withHeaders: vi.fn(function (this: McpdClient) { return this; }),
+  } as unknown as McpdClient;
+}
+
+function setup(opts: { gated?: boolean } = {}) {
+  const router = new McpRouter();
+  router.setPromptConfig(mockMcpdClient(), 'test-project');
+  router.setPlugin(composePlugins([
+    createGatePlugin({ gated: opts.gated ?? false, providerRegistry: null }),
+    createAmbientContextPlugin(),
+  ]));
+  router.setProxyModel('default', { complete: async () => '', available: () => false } as unknown as LLMProviderAdapter, new MemoryCache());
+  router.addUpstream(mockUpstream('k8s', [{ name: 'get_pods' }]));
+  return router;
+}
+
+async function listTools(router: McpRouter, sessionId = 's1'): Promise<string[]> {
+  const res = await router.route({ jsonrpc: '2.0', id: 2, method: 'tools/list' }, { sessionId });
+  return (res.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+}
+
+describe('ambient-context plugin', () => {
+  it('appends get_current_time to an ungated catalog, once', async () => {
+    const router = setup();
+    await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+    const names = await listTools(router);
+    expect(names).toContain('k8s/get_pods');
+    expect(names.filter((n) => n === GET_CURRENT_TIME_TOOL_NAME)).toHaveLength(1);
+
+    // Second list: still exactly one.
+    const again = await listTools(router);
+    expect(again.filter((n) => n === GET_CURRENT_TIME_TOOL_NAME)).toHaveLength(1);
+  });
+
+  it('does not leak get_current_time into a gated catalog', async () => {
+    const router = setup({ gated: true });
+    await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+    const names = await listTools(router);
+    expect(names).toEqual(['begin_session']);
+  });
+
+  it('lists get_current_time after begin_session ungates the session', async () => {
+    const router = setup({ gated: true });
+    await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+    await router.route(
+      { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'begin_session', arguments: { description: 'testing ambient context' } } },
+      { sessionId: 's1' },
+    );
+
+    const names = await listTools(router);
+    expect(names).toContain(GET_CURRENT_TIME_TOOL_NAME);
+  });
+
+  it('get_current_time returns the UTC time', async () => {
+    const router = setup();
+    await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+    const res = await router.route(
+      { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: GET_CURRENT_TIME_TOOL_NAME, arguments: {} } },
+      { sessionId: 's1' },
+    );
+    const text = (res.result as { content: Array<{ text: string }> }).content[0]!.text;
+    expect(text).toMatch(/^UTC: \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/m);
+    expect(text).toContain('Unix epoch seconds:');
+  });
+
+  it('adds the context line and project name to initialize instructions', async () => {
+    const router = setup();
+    const res = await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+    const instructions = (res.result as { instructions?: string }).instructions ?? '';
+    expect(instructions).toContain('[context] now:');
+    expect(instructions).toContain('project: test-project');
+  });
+});
--- a/src/mcplocal/tests/plugin-gate.test.ts
+++ b/src/mcplocal/tests/plugin-gate.test.ts
@@ -74,6 +74,8 @@ function setupPluginRouter(opts: {
  /** When set, the heavy provider's complete() rejects — exercises the loud fallback. */
  llmError?: boolean;
  byteBudget?: number;
+  /** Gate-exempt server names (ungated-global project). */
+  ungatedServers?: string[];
 } = {}): { router: McpRouter; mcpdClient: McpdClient } {
  const router = new McpRouter();
  const prompts = opts.prompts ?? samplePrompts;
@@ -105,6 +107,7 @@ function setupPluginRouter(opts: {
    gated: opts.gated !== false,
    providerRegistry,
    byteBudget: opts.byteBudget,
+    ...(opts.ungatedServers ? { ungatedServers: opts.ungatedServers } : {}),
  });
  router.setPlugin(gatePlugin);

@@ -160,6 +163,63 @@ describe('Gate Plugin via setPlugin()', () => {
    });
  });

+  describe('gate-exempt (ungated-global) servers', () => {
+    it('lists exempt server tools alongside begin_session while gated', async () => {
+      const { router } = setupPluginRouter({ ungatedServers: ['calcmcp'] });
+      router.addUpstream(mockUpstream('calcmcp', { tools: [{ name: 'symbolic_tool' }] }));
+      router.addUpstream(mockUpstream('ha', { tools: [{ name: 'get_entities' }] }));
+      await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+      const res = await router.route(
+        { jsonrpc: '2.0', id: 2, method: 'tools/list' },
+        { sessionId: 's1' },
+      );
+      const names = (res.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+      expect(names).toContain('begin_session');
+      expect(names).toContain('calcmcp/symbolic_tool');
+      expect(names).not.toContain('ha/get_entities');
+    });
+
+    it('calls an exempt tool while gated without intercept and stays gated', async () => {
+      const { router } = setupPluginRouter({ ungatedServers: ['calcmcp'] });
+      router.addUpstream(mockUpstream('calcmcp', { tools: [{ name: 'symbolic_tool' }] }));
+      await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+      const callRes = await router.route(
+        { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'calcmcp/symbolic_tool', arguments: { operation: 'simplify', expression: '1+1' } } },
+        { sessionId: 's1' },
+      );
+      const content = (callRes.result as { content: Array<{ text: string }> }).content;
+      // Real upstream result, not a gate intercept briefing (the router
+      // strips the server prefix when forwarding to the upstream)
+      expect(content[0]!.text).toBe('Called symbolic_tool');
+
+      // Session must STILL be gated: non-exempt catalog stays hidden
+      const toolsRes = await router.route(
+        { jsonrpc: '2.0', id: 3, method: 'tools/list' },
+        { sessionId: 's1' },
+      );
+      const names = (toolsRes.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+      expect(names).toContain('begin_session');
+    });
+
+    it('lists exempt tools under "Available immediately" in initialize instructions', async () => {
+      const { router } = setupPluginRouter({ ungatedServers: ['calcmcp'] });
+      router.addUpstream(mockUpstream('calcmcp', { tools: [{ name: 'symbolic_tool' }] }));
+      router.addUpstream(mockUpstream('ha', { tools: [{ name: 'get_entities' }] }));
+
+      const res = await router.route(
+        { jsonrpc: '2.0', id: 1, method: 'initialize' },
+        { sessionId: 's1' },
+      );
+      const instructions = (res.result as { instructions?: string }).instructions ?? '';
+      expect(instructions).toContain('Available immediately (no begin_session required):');
+      expect(instructions).toContain('calcmcp_symbolic_tool');
+      expect(instructions).toContain('Available MCP server tools (accessible after begin_session):');
+      expect(instructions).toContain('ha_get_entities');
+    });
+  });
+
  describe('tools/list gating', () => {
    it('shows only begin_session when session is gated', async () => {
      const { router } = setupPluginRouter();
@@ -199,6 +259,19 @@ describe('Gate Plugin via setPlugin()', () => {
  });

  describe('begin_session', () => {
+    it('opens the briefing with the ambient context line (the model has no clock)', async () => {
+      const { router } = setupPluginRouter();
+      await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+      const res = await router.route(
+        { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'begin_session', arguments: { tags: ['zigbee'] } } },
+        { sessionId: 's1' },
+      );
+
+      const text = ((res.result as { content: Array<{ text: string }> }).content[0]!.text);
+      expect(text).toMatch(/^\[context\] now: /);
+    });
+
    it('falls back with a visible warning when the LLM selector errors (no silent degrade)', async () => {
      const { router } = setupPluginRouter({ withLlm: true, llmError: true });
      await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
--- a/src/mcplocal/tests/project-discovery.test.ts
+++ b/src/mcplocal/tests/project-discovery.test.ts
@@ -27,9 +27,22 @@ describe('refreshProjectUpstreams', () => {
    ]);

    const registered = await refreshProjectUpstreams(router, client as any, 'smart-home');
-    expect(registered).toEqual(['grafana', 'ha']);
+    expect(registered.names).toEqual(['grafana', 'ha']);
+    expect(registered.ungatedServers).toEqual([]);
+  });
+
+  it('reports servers flagged ungatedGlobal as gate-exempt', async () => {
+    const router = new McpRouter();
+    const client = mockMcpdClient([
+      { id: 'srv-1', name: 'grafana', transport: 'stdio' },
+      { id: 'srv-2', name: 'calcmcp', transport: 'stdio', ungatedGlobal: true },
+    ]);
+
+    const registered = await refreshProjectUpstreams(router, client as any, 'smart-home');
+    expect(registered.names).toEqual(['grafana', 'calcmcp']);
+    expect(registered.ungatedServers).toEqual(['calcmcp']);
    expect(router.getUpstreamNames()).toContain('grafana');
-    expect(router.getUpstreamNames()).toContain('ha');
+    expect(router.getUpstreamNames()).toContain('calcmcp');
    expect(client.get).toHaveBeenCalledWith('/api/v1/projects/smart-home/servers');
  });

@@ -85,7 +98,7 @@ describe('refreshProjectUpstreams', () => {
    const client = mockMcpdClient([]);

    const registered = await refreshProjectUpstreams(router, client as any, 'empty-project');
-    expect(registered).toEqual([]);
+    expect(registered.names).toEqual([]);
    expect(router.getUpstreamNames()).toHaveLength(0);
  });
 });
--- a/src/mcplocal/tests/project-mcp-endpoint-ambient.test.ts
+++ b/src/mcplocal/tests/project-mcp-endpoint-ambient.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect, vi } from 'vitest';
+import Fastify from 'fastify';
+import { registerProjectMcpEndpoint } from '../src/http/project-mcp-endpoint.js';
+import type { McpRouter } from '../src/router.js';
+import type { JsonRpcRequest, JsonRpcResponse } from '../src/types.js';
+
+/**
+ * Ambient-context E2E on /projects/:name/mcp: every tools/call result —
+ * upstream AND virtual — carries a trailing `[context] now:` content item,
+ * initialize instructions carry the same line, tools/list stays clean, and
+ * get_current_time is served on an ungated project.
+ */
+
+vi.mock('../src/discovery.js', () => ({
+  refreshProjectUpstreams: vi.fn(async (router: McpRouter) => {
+    router.addUpstream({
+      name: 'websearch',
+      send: async (req: JsonRpcRequest): Promise<JsonRpcResponse> => {
+        if (req.method === 'tools/list') {
+          return {
+            jsonrpc: '2.0',
+            id: req.id,
+            result: { tools: [{ name: 'fetch_content', description: 'fetch a page', inputSchema: { type: 'object' } }] },
+          };
+        }
+        if (req.method === 'tools/call') {
+          return { jsonrpc: '2.0', id: req.id, result: { content: [{ type: 'text', text: 'page body' }] } };
+        }
+        return { jsonrpc: '2.0', id: req.id, result: {} };
+      },
+      close: async () => {},
+      isAlive: () => true,
+    });
+    return { names: ['websearch'], ungatedServers: [] };
+  }),
+  // Ungated (content-pipeline style), like chat-web and personal-michal.
+  fetchProjectLlmConfig: vi.fn(async () => ({ gated: false, llmProvider: 'none' })),
+}));
+
+vi.mock('../src/http/config.js', async () => {
+  const actual = await vi.importActual<typeof import('../src/http/config.js')>('../src/http/config.js');
+  return { ...actual, loadProjectLlmOverride: vi.fn(() => undefined) };
+});
+
+function mockMcpdClient() {
+  const client: Record<string, unknown> = {
+    baseUrl: 'http://test:3100',
+    token: 'test-token',
+    get: vi.fn(async () => []),
+    post: vi.fn(async () => ({})),
+    put: vi.fn(),
+    delete: vi.fn(),
+    forward: vi.fn(async () => ({ status: 200, body: [] })),
+    withHeaders: vi.fn(),
+    withToken: vi.fn(),
+    withTimeout: vi.fn(),
+  };
+  (client.withHeaders as ReturnType<typeof vi.fn>).mockReturnValue(client);
+  (client.withToken as ReturnType<typeof vi.fn>).mockReturnValue(client);
+  (client.withTimeout as ReturnType<typeof vi.fn>).mockReturnValue(client);
+  return client;
+}
+
+function parseSse(body: string): JsonRpcResponse {
+  const dataLine = body.split('\n').find((l) => l.startsWith('data: '));
+  if (!dataLine) throw new Error(`no SSE data line in: ${body}`);
+  return JSON.parse(dataLine.slice('data: '.length)) as JsonRpcResponse;
+}
+
+const CONTEXT_PREFIX = '[context] now:';
+
+describe('registerProjectMcpEndpoint ambient context', () => {
+  it('stamps instructions, tool results (upstream and virtual), but not tools/list', async () => {
+    const app = Fastify();
+    registerProjectMcpEndpoint(app, mockMcpdClient() as never);
+    await app.ready();
+    try {
+      const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+      };
+
+      const init = await app.inject({
+        method: 'POST',
+        url: '/projects/chat-web/mcp',
+        headers,
+        payload: { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 't', version: '0' } } },
+      });
+      expect(init.statusCode).toBe(200);
+      const initResponse = parseSse(init.body);
+      const instructions = (initResponse.result as { instructions?: string }).instructions ?? '';
+      expect(instructions).toContain(CONTEXT_PREFIX);
+      expect(instructions).toContain('project: chat-web');
+      // The initialize RESPONSE itself is not trailed (no result.content).
+      expect(JSON.stringify((initResponse.result as { content?: unknown }).content ?? null)).not.toContain(CONTEXT_PREFIX);
+
+      const sessionId = init.headers['mcp-session-id'] as string;
+      const sessionHeaders = { ...headers, 'mcp-session-id': sessionId };
+
+      const list = await app.inject({
+        method: 'POST',
+        url: '/projects/chat-web/mcp',
+        headers: sessionHeaders,
+        payload: { jsonrpc: '2.0', id: 2, method: 'tools/list' },
+      });
+      const listResponse = parseSse(list.body);
+      const names = (listResponse.result as { tools: Array<{ name: string }> }).tools.map((t) => t.name);
+      expect(names).toContain('get_current_time');
+      // tools/list is never trailed.
+      expect(JSON.stringify(listResponse.result)).not.toContain(CONTEXT_PREFIX);
+
+      // Upstream tool call: original content intact, trailer appended LAST.
+      const call = await app.inject({
+        method: 'POST',
+        url: '/projects/chat-web/mcp',
+        headers: sessionHeaders,
+        payload: { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'websearch_fetch_content', arguments: { url: 'https://x' } } },
+      });
+      const callContent = (parseSse(call.body).result as { content: Array<{ type: string; text: string }> }).content;
+      expect(callContent.length).toBeGreaterThanOrEqual(2);
+      expect(callContent[0]?.text).toContain('page body');
+      expect(callContent[callContent.length - 1]?.text).toMatch(/^\[context\] now: /);
+
+      // Virtual tool call (bypasses plugin onToolCallAfter): still trailed.
+      const timeCall = await app.inject({
+        method: 'POST',
+        url: '/projects/chat-web/mcp',
+        headers: sessionHeaders,
+        payload: { jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'get_current_time', arguments: {} } },
+      });
+      const timeContent = (parseSse(timeCall.body).result as { content: Array<{ text: string }> }).content;
+      expect(timeContent[0]?.text).toContain('UTC:');
+      expect(timeContent[timeContent.length - 1]?.text).toMatch(/^\[context\] now: /);
+    } finally {
+      await app.close();
+    }
+  });
+});
--- a/src/mcplocal/tests/project-mcp-endpoint-wire-names.test.ts
+++ b/src/mcplocal/tests/project-mcp-endpoint-wire-names.test.ts
@@ -40,7 +40,7 @@ vi.mock('../src/discovery.js', () => ({
      close: async () => {},
      isAlive: () => true,
    });
-    return ['websearch'];
+    return { names: ['websearch'], ungatedServers: [] };
  }),
  // gated: false → no gate plugin, the full catalog is served at initialize
  // (the chat-web configuration).
--- a/src/mcplocal/tests/project-mcp-endpoint.test.ts
+++ b/src/mcplocal/tests/project-mcp-endpoint.test.ts
@@ -5,7 +5,7 @@ import { registerProjectMcpEndpoint } from '../src/http/project-mcp-endpoint.js'

 // Mock discovery module — we don't want real HTTP calls
 vi.mock('../src/discovery.js', () => ({
-  refreshProjectUpstreams: vi.fn(async () => ['mock-server']),
+  refreshProjectUpstreams: vi.fn(async () => ({ names: ['mock-server'], ungatedServers: [] })),
  fetchProjectLlmConfig: vi.fn(async () => ({})),
 }));

--- a/src/mcplocal/tests/toolcall-deadline-e2e.test.ts
+++ b/src/mcplocal/tests/toolcall-deadline-e2e.test.ts
@@ -30,7 +30,7 @@ vi.mock('../src/discovery.js', () => ({
      close: async () => { /* noop */ },
      isAlive: () => true,
    });
-    return ['blackhole'];
+    return { names: ['blackhole'], ungatedServers: [] };
  }),
  fetchProjectLlmConfig: vi.fn(async () => ({ gated: false, llmProvider: 'none' })),
 }));