From 1187883c6bdaa85e9d1432cc9f1101c0a5d53533 Mon Sep 17 00:00:00 2001
From: jubnl <jgunther021@gmail.com>
Date: Fri, 10 Apr 2026 02:44:45 +0200
Subject: [PATCH] feat(mcp): always register list_trips & get_trip_summary;
 inject deprecation notice into tool results
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Navigation tools:
- list_trips and get_trip_summary are now always registered for any
  OAuth session regardless of granted scopes — they are required for
  trip ID discovery before any scoped tool can be used
- get_trip_summary filters optional sections (budget, packing, collab,
  reservations) by the client's OAuth scopes when called without trips:read

Deprecation notice:
- Inject static token deprecation warning into the first tool result
  (list_trips or get_trip_summary) via a per-session closure so Claude
  is forced to surface it — the instructions field alone is only
  background context and is not proactively shown to the user

UI:
- OAuth client creation modal: add hint explaining the always-available
  tools, remove the "must select at least one scope" submit guard
- OAuth consent screen: add "Always included" section showing list_trips
  and get_trip_summary; handles zero-scope clients gracefully (empty
  permissions section is hidden)
---
 .../components/Settings/IntegrationsTab.tsx   |  5 +-
 client/src/i18n/translations/en.ts            |  1 +
 client/src/pages/OAuthAuthorizePage.tsx       | 71 +++++++++++++------
 server/src/mcp/index.ts                       | 12 +++-
 server/src/mcp/tools.ts                       |  4 +-
 server/src/mcp/tools/trips.ts                 | 45 ++++++++----
 6 files changed, 97 insertions(+), 41 deletions(-)

diff --git a/client/src/components/Settings/IntegrationsTab.tsx b/client/src/components/Settings/IntegrationsTab.tsx
index afd2c40c..4bbc3413 100644
--- a/client/src/components/Settings/IntegrationsTab.tsx
+++ b/client/src/components/Settings/IntegrationsTab.tsx
@@ -552,7 +552,7 @@ export default function IntegrationsTab(): React.ReactElement {
                 </div>
 
                 <div>
-                  <div className="flex items-center justify-between mb-2">
+                  <div className="flex items-center justify-between mb-1">
                     <label className="text-sm font-medium" style={{ color: 'var(--text-secondary)' }}>{t('settings.oauth.modal.scopes')}</label>
                     <button type="button"
                       onClick={() => {
@@ -567,6 +567,7 @@ export default function IntegrationsTab(): React.ReactElement {
                         : t('settings.oauth.modal.selectAll')}
                     </button>
                   </div>
+                  <p className="text-xs mb-2" style={{ color: 'var(--text-tertiary)' }}>{t('settings.oauth.modal.scopesHint')}</p>
                   <div className="space-y-1 max-h-56 overflow-y-auto pr-1">
                     {Object.entries(scopesByGroup).map(([group, groupScopes]) => {
                       const groupScopeKeys = groupScopes.map(s => s.scope)
@@ -625,7 +626,7 @@ export default function IntegrationsTab(): React.ReactElement {
                     {t('common.cancel')}
                   </button>
                   <button onClick={handleCreateOAuthClient}
-                    disabled={!oauthNewName.trim() || !oauthNewUris.trim() || oauthNewScopes.length === 0 || oauthCreating}
+                    disabled={!oauthNewName.trim() || !oauthNewUris.trim() || oauthCreating}
                     className="px-4 py-2 rounded-lg text-sm font-medium text-white disabled:opacity-50"
                     style={{ background: 'var(--accent-primary, #4f46e5)' }}>
                     {oauthCreating ? t('settings.oauth.modal.creating') : t('settings.oauth.modal.create')}
diff --git a/client/src/i18n/translations/en.ts b/client/src/i18n/translations/en.ts
index 386e6ef8..1bdaeeef 100644
--- a/client/src/i18n/translations/en.ts
+++ b/client/src/i18n/translations/en.ts
@@ -299,6 +299,7 @@ const en: Record<string, string | { name: string; category: string }[]> = {
   'settings.oauth.modal.redirectUrisPlaceholder': 'https://your-app.com/callback\nhttps://your-app.com/auth',
   'settings.oauth.modal.redirectUrisHint': 'One URI per line. HTTPS required (localhost exempt). Exact match enforced.',
   'settings.oauth.modal.scopes': 'Allowed Scopes',
+  'settings.oauth.modal.scopesHint': 'list_trips and get_trip_summary are always available — no scope required. They let the AI discover trip IDs needed to use any other tool.',
   'settings.oauth.modal.selectAll': 'Select all',
   'settings.oauth.modal.deselectAll': 'Deselect all',
   'settings.oauth.modal.creating': 'Registering…',
diff --git a/client/src/pages/OAuthAuthorizePage.tsx b/client/src/pages/OAuthAuthorizePage.tsx
index 24bd10fd..6320bb84 100644
--- a/client/src/pages/OAuthAuthorizePage.tsx
+++ b/client/src/pages/OAuthAuthorizePage.tsx
@@ -215,31 +215,58 @@ export default function OAuthAuthorizePage(): React.ReactElement {
 
         {/* Right panel — scopes */}
         <div className="flex-1 px-6 py-8 overflow-y-auto max-h-[80vh] sm:max-h-[600px]">
-          <p className="text-xs font-medium uppercase tracking-wide mb-4" style={{ color: 'var(--text-tertiary)' }}>
-            Permissions requested
-          </p>
-          <div className="space-y-5">
-            {Object.entries(scopesByGroup).map(([group, groupScopes]) => (
-              <div key={group}>
-                <p className="text-xs font-semibold mb-2" style={{ color: 'var(--text-secondary)' }}>{group}</p>
-                <div className="space-y-1.5">
-                  {groupScopes.map(s => {
-                    const info = SCOPE_GROUPS[s]
-                    return (
-                      <div key={s} className="flex items-start gap-2.5 px-3 py-2 rounded-lg" style={{ background: 'var(--bg-secondary)' }}>
-                        <span className="mt-0.5 text-base leading-none flex-shrink-0">
-                          {s.endsWith(':delete') ? '🗑️' : s.endsWith(':write') ? '✏️' : '👁️'}
-                        </span>
-                        <div className="min-w-0">
-                          <p className="text-sm font-medium" style={{ color: 'var(--text-primary)' }}>{info?.label || s}</p>
-                          <p className="text-xs mt-0.5" style={{ color: 'var(--text-tertiary)' }}>{info?.description || ''}</p>
-                        </div>
+          <div className="space-y-6">
+            {Object.keys(scopesByGroup).length > 0 && (
+              <div>
+                <p className="text-xs font-medium uppercase tracking-wide mb-4" style={{ color: 'var(--text-tertiary)' }}>
+                  Permissions requested
+                </p>
+                <div className="space-y-5">
+                  {Object.entries(scopesByGroup).map(([group, groupScopes]) => (
+                    <div key={group}>
+                      <p className="text-xs font-semibold mb-2" style={{ color: 'var(--text-secondary)' }}>{group}</p>
+                      <div className="space-y-1.5">
+                        {groupScopes.map(s => {
+                          const info = SCOPE_GROUPS[s]
+                          return (
+                            <div key={s} className="flex items-start gap-2.5 px-3 py-2 rounded-lg" style={{ background: 'var(--bg-secondary)' }}>
+                              <span className="mt-0.5 text-base leading-none flex-shrink-0">
+                                {s.endsWith(':delete') ? '🗑️' : s.endsWith(':write') ? '✏️' : '👁️'}
+                              </span>
+                              <div className="min-w-0">
+                                <p className="text-sm font-medium" style={{ color: 'var(--text-primary)' }}>{info?.label || s}</p>
+                                <p className="text-xs mt-0.5" style={{ color: 'var(--text-tertiary)' }}>{info?.description || ''}</p>
+                              </div>
+                            </div>
+                          )
+                        })}
                       </div>
-                    )
-                  })}
+                    </div>
+                  ))}
                 </div>
               </div>
-            ))}
+            )}
+
+            {/* Always-available tools — granted regardless of scopes */}
+            <div>
+              <p className="text-xs font-medium uppercase tracking-wide mb-3" style={{ color: 'var(--text-tertiary)' }}>
+                Always included
+              </p>
+              <div className="space-y-1.5">
+                {[
+                  { name: 'list_trips',       desc: 'List your trips so the AI can discover trip IDs' },
+                  { name: 'get_trip_summary', desc: 'Read a trip overview needed to use any other tool' },
+                ].map(({ name, desc }) => (
+                  <div key={name} className="flex items-start gap-2.5 px-3 py-2 rounded-lg" style={{ background: 'var(--bg-secondary)' }}>
+                    <span className="mt-0.5 text-base leading-none flex-shrink-0">👁️</span>
+                    <div className="min-w-0">
+                      <p className="text-sm font-medium font-mono" style={{ color: 'var(--text-primary)' }}>{name}</p>
+                      <p className="text-xs mt-0.5" style={{ color: 'var(--text-tertiary)' }}>{desc}</p>
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
           </div>
         </div>
 
diff --git a/server/src/mcp/index.ts b/server/src/mcp/index.ts
index 7fc74f90..fc58abac 100644
--- a/server/src/mcp/index.ts
+++ b/server/src/mcp/index.ts
@@ -253,8 +253,18 @@ export async function mcpHandler(req: Request, res: Response): Promise<void> {
       instructions: BASE_MCP_INSTRUCTIONS + (isStaticToken ? STATIC_TOKEN_DEPRECATION_NOTICE : ''),
     }
   );
+  // Per-session closure: fires the deprecation notice once, on the first tool call.
+  // Tool results are the only mechanism Claude reliably surfaces to the user;
+  // the instructions field is only background context and won't trigger a proactive warning.
+  let _noticeEmitted = false;
+  const getDeprecationNotice = (): string | null => {
+    if (!isStaticToken || _noticeEmitted) return null;
+    _noticeEmitted = true;
+    return STATIC_TOKEN_DEPRECATION_NOTICE;
+  };
+
   registerResources(server, user.id, scopes);
-  registerTools(server, user.id, scopes, isStaticToken);
+  registerTools(server, user.id, scopes, isStaticToken, getDeprecationNotice);
 
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: () => randomUUID(),
diff --git a/server/src/mcp/tools.ts b/server/src/mcp/tools.ts
index 21931d9a..14c9613a 100644
--- a/server/src/mcp/tools.ts
+++ b/server/src/mcp/tools.ts
@@ -15,8 +15,8 @@ import { registerTripTools } from './tools/trips';
 import { registerVacayTools } from './tools/vacay';
 import { registerMcpPrompts } from './tools/prompts';
 
-export function registerTools(server: McpServer, userId: number, scopes: string[] | null, isStaticToken = false): void {
-  registerTripTools(server, userId, scopes);
+export function registerTools(server: McpServer, userId: number, scopes: string[] | null, isStaticToken = false, getDeprecationNotice: () => string | null = () => null): void {
+  registerTripTools(server, userId, scopes, getDeprecationNotice);
 
   registerPlaceTools(server, userId, scopes);
 
diff --git a/server/src/mcp/tools/trips.ts b/server/src/mcp/tools/trips.ts
index f03f142c..806a8afd 100644
--- a/server/src/mcp/tools/trips.ts
+++ b/server/src/mcp/tools/trips.ts
@@ -24,9 +24,9 @@ import {
   TOOL_ANNOTATIONS_DELETE, TOOL_ANNOTATIONS_NON_IDEMPOTENT,
   demoDenied, noAccess, ok,
 } from './_shared';
-import { canReadTrips, canWrite, canDeleteTrips, canShareTrips } from '../scopes';
+import { canRead, canReadTrips, canWrite, canDeleteTrips, canShareTrips } from '../scopes';
 
-export function registerTripTools(server: McpServer, userId: number, scopes: string[] | null): void {
+export function registerTripTools(server: McpServer, userId: number, scopes: string[] | null, getDeprecationNotice: () => string | null = () => null): void {
   const R = canReadTrips(scopes);
   const W = canWrite(scopes, 'trips');
   const D = canDeleteTrips(scopes);
@@ -117,7 +117,9 @@ export function registerTripTools(server: McpServer, userId: number, scopes: str
     }
   );
 
-  if (R) server.registerTool(
+  // list_trips and get_trip_summary are always registered regardless of OAuth scopes —
+  // they are navigation tools that any MCP client needs to discover trip IDs.
+  server.registerTool(
     'list_trips',
     {
       description: 'List all trips the current user owns or is a member of. Use this for trip discovery before calling get_trip_summary.',
@@ -127,14 +129,17 @@ export function registerTripTools(server: McpServer, userId: number, scopes: str
       annotations: TOOL_ANNOTATIONS_READONLY,
     },
     async ({ include_archived }) => {
+      const notice = getDeprecationNotice();
       const trips = listTrips(userId, include_archived ? null : 0);
-      return ok({ trips });
+      const result = ok({ trips });
+      if (notice) return { content: [{ type: 'text' as const, text: notice }, ...result.content] };
+      return result;
     }
   );
 
   // --- TRIP SUMMARY ---
 
-  if (R) server.registerTool(
+  server.registerTool(
     'get_trip_summary',
     {
       description: 'Get a full denormalized summary of a trip in a single call: metadata, members, days with assignments and notes, accommodations, budget line items (when enabled), packing list (when enabled), reservations, collab notes and poll/message counts (when enabled), and to-do items (when enabled). Use this as a context loader before planning or modifying a trip.',
@@ -147,25 +152,37 @@ export function registerTripTools(server: McpServer, userId: number, scopes: str
       if (!canAccessTrip(tripId, userId)) return noAccess();
       const summary = getTripSummary(tripId);
       if (!summary) return noAccess();
+      // Addon availability gates
       const packingEnabled = isAddonEnabled(ADDON_IDS.PACKING);
-      const budgetEnabled = isAddonEnabled(ADDON_IDS.BUDGET);
-      const collabEnabled = isAddonEnabled(ADDON_IDS.COLLAB);
-      const todos = packingEnabled ? listTodoItems(tripId) : [];
+      const budgetEnabled  = isAddonEnabled(ADDON_IDS.BUDGET);
+      const collabEnabled  = isAddonEnabled(ADDON_IDS.COLLAB);
+      // Scope gates — sections not covered by the client's OAuth scopes are omitted.
+      // Core trip data (metadata, days, members, accommodations) is always included
+      // because this tool is always registered and needed for navigation.
+      const canReadBudget  = budgetEnabled  && canRead(scopes, 'budget');
+      const canReadPacking = packingEnabled && canRead(scopes, 'packing');
+      const canReadCollab  = collabEnabled  && canRead(scopes, 'collab');
+      const canReadRes     = canRead(scopes, 'reservations');
+      const todos = canReadPacking ? listTodoItems(tripId) : [];
       let pollCount = 0;
       let messageCount = 0;
-      if (collabEnabled) {
-        pollCount = listPolls(tripId).length;
+      if (canReadCollab) {
+        pollCount    = listPolls(tripId).length;
         messageCount = countMessages(tripId);
       }
-      return ok({
+      const notice = getDeprecationNotice();
+      const result = ok({
         ...summary,
-        packing: packingEnabled ? summary.packing : undefined,
-        budget: budgetEnabled ? summary.budget : undefined,
-        collab_notes: collabEnabled ? summary.collab_notes : [],
+        reservations:  canReadRes     ? summary.reservations  : undefined,
+        packing:       canReadPacking ? summary.packing        : undefined,
+        budget:        canReadBudget  ? summary.budget         : undefined,
+        collab_notes:  canReadCollab  ? summary.collab_notes   : undefined,
         todos,
         pollCount,
         messageCount,
       });
+      if (notice) return { content: [{ type: 'text' as const, text: notice }, ...result.content] };
+      return result;
     }
   );