Set up session caps for free MCP usage

pimterry · pimterry · commit 4e6711da8d56 · 2026-04-21T21:23:13.000+02:00
diff --git a/src/services/ui-api/api-registry.ts b/src/services/ui-api/api-registry.ts
@@ -40,19 +40,26 @@ export class OperationRegistry {
                 return true;
             })
             .map(op => {
-                if (tier === 'pro') return op.definition;
+                // Strip internal-only fields from output before sending to
+                // external clients — they're only used here for augmentation.
+                const { freeTierNote, sessionLimit, ...definition } = op.definition;
+
+                if (tier === 'pro') return definition;
 
                 // Augment descriptions for free users so AI agents understand limits
-                let description = op.definition.description;
-                const { tiers, sessionLimit } = op.definition;
+                let description = definition.description;
 
                 if (sessionLimit) {
                     description += `\n\n[Free tier] Limited to ${sessionLimit} calls per session. ` +
                         'Use account.upgrade to subscribe to Pro for unlimited access.';
                 }
 
-                if (description === op.definition.description) return op.definition;
-                return { ...op.definition, description };
+                if (freeTierNote) {
+                    description += `\n\n[Free tier] ${freeTierNote}`;
+                }
+
+                if (description === definition.description) return definition;
+                return { ...definition, description };
             });
     }
 
diff --git a/src/services/ui-api/api-types.ts b/src/services/ui-api/api-types.ts
@@ -8,6 +8,10 @@ export interface OperationDefinition {
     category: string;
     tiers: Array<'free' | 'pro'>;
     sessionLimit?: number;
+    // Appended to the description for free users only — explains a free-tier
+    // limitation that the operation enforces in its handler (e.g. body size
+    // caps), so agents understand why responses look the way they do.
+    freeTierNote?: string;
     annotations?: {
         readOnlyHint?: boolean;
         destructiveHint?: boolean;
diff --git a/src/services/ui-api/operations/event-operations.ts b/src/services/ui-api/operations/event-operations.ts
@@ -6,15 +6,20 @@ import { matchFilters } from '../../../model/filters/filter-matching';
 import { SelectableSearchFilterClasses } from '../../../model/filters/search-filters';
 import { EventsStore } from '../../../model/events/events-store';
 
+// Free-tier body exports are capped to support exploration but not
+// arbitrary export (paid feature).
+const FREE_TIER_MAX_BODY_CHARS = 100_000;
+
 export function registerEventOperations(
     registry: OperationRegistry,
     eventsStore: EventsStore,
-    getEvents: () => ReadonlyArray<CollectedEvent>
+    getEvents: () => ReadonlyArray<CollectedEvent>,
+    isPaidUser: () => boolean
 ): void {
     registry.register(eventsListOperation(getEvents));
     registry.register(eventsGetOutlineOperation(getEvents));
-    registry.register(eventsGetRequestBodyOperation(getEvents));
-    registry.register(eventsGetResponseBodyOperation(getEvents));
+    registry.register(eventsGetRequestBodyOperation(getEvents, isPaidUser));
+    registry.register(eventsGetResponseBodyOperation(getEvents, isPaidUser));
     registry.register(eventsClearOperation(eventsStore));
 }
 
@@ -171,6 +176,10 @@ function eventsGetOutlineOperation(
                 'Use events.get-request-body or events.get-response-body to retrieve bodies.',
             category: 'events',
             tiers: ['free', 'pro'],
+            sessionLimit: 500,
+            freeTierNote: 'This operation is limited to 500 calls per session for free users, so ' +
+                'ensure only the necessary events are queried. Upgrade to Pro (account.upgrade) ' +
+                'for unlimited access to all features.',
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: 'object',
@@ -218,8 +227,15 @@ function eventsGetOutlineOperation(
     };
 }
 
+function effectiveMaxLength(requested: number | undefined, isPaid: boolean): number | undefined {
+    if (isPaid) return requested;
+    if (requested === undefined) return FREE_TIER_MAX_BODY_CHARS;
+    return Math.min(requested, FREE_TIER_MAX_BODY_CHARS);
+}
+
 function eventsGetRequestBodyOperation(
-    getEvents: () => ReadonlyArray<CollectedEvent>
+    getEvents: () => ReadonlyArray<CollectedEvent>,
+    isPaidUser: () => boolean
 ): Operation {
     return {
         definition: {
@@ -228,7 +244,10 @@ function eventsGetRequestBodyOperation(
                 'Use offset and maxLength to retrieve specific ranges of large bodies.',
             category: 'events',
             tiers: ['free', 'pro'],
-            sessionLimit: 50,
+            sessionLimit: 100,
+            freeTierNote: `Response bodies are capped at ${FREE_TIER_MAX_BODY_CHARS} ` +
+                'characters per call. Page through larger bodies with offset, or upgrade ' +
+                'to Pro (account.upgrade) for full bodies.',
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: 'object',
@@ -243,15 +262,16 @@ function eventsGetRequestBodyOperation(
 
             const body = await serializeBody(lookup.exchange, 'request', {
                 offset: params.offset as number | undefined,
-                maxLength: params.maxLength as number | undefined
+                maxLength: effectiveMaxLength(params.maxLength as number | undefined, isPaidUser())
             });
             return { success: true, data: body };
         }
     };
 }
 
 function eventsGetResponseBodyOperation(
-    getEvents: () => ReadonlyArray<CollectedEvent>
+    getEvents: () => ReadonlyArray<CollectedEvent>,
+    isPaidUser: () => boolean
 ): Operation {
     return {
         definition: {
@@ -260,7 +280,10 @@ function eventsGetResponseBodyOperation(
                 'Use offset and maxLength to retrieve specific ranges of large bodies.',
             category: 'events',
             tiers: ['free', 'pro'],
-            sessionLimit: 50,
+            sessionLimit: 100,
+            freeTierNote: `Response bodies are capped at ${FREE_TIER_MAX_BODY_CHARS} ` +
+                'characters per call. Page through larger bodies with offset, or upgrade ' +
+                'to Pro (account.upgrade) for full bodies.',
             annotations: { readOnlyHint: true },
             inputSchema: {
                 type: 'object',
@@ -275,7 +298,7 @@ function eventsGetResponseBodyOperation(
 
             const body = await serializeBody(lookup.exchange, 'response', {
                 offset: params.offset as number | undefined,
-                maxLength: params.maxLength as number | undefined
+                maxLength: effectiveMaxLength(params.maxLength as number | undefined, isPaidUser())
             });
             return { success: true, data: body };
         }
diff --git a/src/services/ui-api/operations/index.ts b/src/services/ui-api/operations/index.ts
@@ -19,7 +19,8 @@ export function registerAllOperations(
     },
     getEvents: () => ReadonlyArray<CollectedEvent>
 ): void {
-    registerEventOperations(registry, stores.eventsStore, getEvents);
+    const isPaidUser = () => stores.accountStore.user.isPaidUser();
+    registerEventOperations(registry, stores.eventsStore, getEvents, isPaidUser);
     registerProxyOperations(registry, stores.proxyStore);
     registerInterceptorOperations(registry, stores.interceptorStore);
     registerAccountOperations(registry, stores.accountStore);
diff --git a/test/unit/services/api/api-registry.spec.ts b/test/unit/services/api/api-registry.spec.ts
@@ -74,13 +74,33 @@ describe('OperationRegistry', () => {
             expect(defs[0].description).to.include('Limited to 10 calls per session');
         });
 
-        it('should not augment descriptions for free users when there is no session limit', () => {
+        it('should not augment descriptions for free users when there is no session limit or note', () => {
             const registry = new OperationRegistry(() => false);
             registry.register(makeOperation('test.op'));
 
             const defs = registry.getDefinitions();
             expect(defs[0].description).to.equal('Test operation test.op');
         });
+
+        it('should append freeTierNote to descriptions for free users', () => {
+            const registry = new OperationRegistry(() => false);
+            registry.register(makeOperation('test.op', {
+                freeTierNote: 'Bodies are capped at 100 chars per call.'
+            }));
+
+            const defs = registry.getDefinitions();
+            expect(defs[0].description).to.include('[Free tier] Bodies are capped at 100 chars per call.');
+        });
+
+        it('should not append freeTierNote for pro users', () => {
+            const registry = new OperationRegistry(() => true);
+            registry.register(makeOperation('test.op', {
+                freeTierNote: 'Bodies are capped at 100 chars per call.'
+            }));
+
+            const defs = registry.getDefinitions();
+            expect(defs[0].description).to.equal('Test operation test.op');
+        });
     });
 
     describe('execute()', () => {
diff --git a/test/unit/services/api/event-operations.spec.ts b/test/unit/services/api/event-operations.spec.ts
@@ -14,7 +14,7 @@ describe('Event operations', () => {
         events = [];
         registry = new OperationRegistry(() => true);
         const mockEventsStore = { clearInterceptedData: () => {} } as any;
-        registerEventOperations(registry, mockEventsStore, () => events);
+        registerEventOperations(registry, mockEventsStore, () => events, () => true);
     });
 
     describe('events.list', () => {
