Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(mcp-host): separate GFS transfer and visual limits

Alfredo Lopez7aff03a001a6
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 6dff9be3d..e27c32cf6 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index df246a7d9..566043608 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.478",
+ "version": "0.1.479",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/internalTools/gfsFilePolicy.test.ts b/mcp-host/src/internalTools/gfsFilePolicy.test.ts
new file mode 100644
index 000000000..1e196c6d0
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsFilePolicy.test.ts
@@ -0,0 +1,92 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { VISUAL_INPUT_LIMITS } from '../visualInput/policy'
+import { configuredGfsInteger } from './gfsFilePolicy'
+
+afterEach(() => {
+ vi.unstubAllEnvs()
+ vi.resetModules()
+})
+
+describe('GFS file policy', () => {
+ it('uses independent defaults for source transfer, text, retention and quotas', async () => {
+ for (const name of [
+ 'MCP_HOST_GFS_MAX_FILE_BYTES',
+ 'MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES',
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES',
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES',
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_CONCURRENCY',
+ 'MCP_HOST_GFS_DOWNLOAD_TTL_HOURS',
+ ]) {
+ vi.stubEnv(name, undefined)
+ }
+ vi.resetModules()
+
+ const { GFS_FILE_LIMITS } = await import('./gfsFilePolicy')
+
+ expect(GFS_FILE_LIMITS).toEqual({
+ maxFileBytes: 16 * 1024 * 1024,
+ inlineTextBytes: 8192,
+ metadataBytes: 64 * 1024,
+ errorBytes: 8 * 1024,
+ storageBytes: 1024 * 1024 * 1024,
+ callerStorageBytes: 256 * 1024 * 1024,
+ callerRetainedFiles: 8,
+ callerActiveDownloads: 1,
+ retentionMs: 7 * 24 * 60 * 60 * 1000,
+ })
+ expect(VISUAL_INPUT_LIMITS.fileBytes).toBe(3 * 1024 * 1024)
+ })
+
+ it('accepts an explicitly configured larger source only below the protocol ceiling', async () => {
+ vi.stubEnv('MCP_HOST_GFS_MAX_FILE_BYTES', String(200 * 1024 * 1024))
+ vi.resetModules()
+
+ const { GFS_FILE_LIMITS } = await import('./gfsFilePolicy')
+
+ expect(GFS_FILE_LIMITS.maxFileBytes).toBe(200 * 1024 * 1024)
+ })
+
+ it.each([
+ '',
+ '0',
+ '-1',
+ '1.5',
+ '1e6',
+ 'NaN',
+ 'Infinity',
+ ' 16777216 ',
+ '+16777216',
+ '016777216',
+ '16777216bytes',
+ ])('rejects non-canonical integer %s', raw => {
+ expect(() => configuredGfsInteger('limit', raw, 16, 200)).toThrow()
+ })
+
+ it('enforces source, caller, aggregate and concurrency relationships', async () => {
+ expect(configuredGfsInteger('limit', '200', 16, 200)).toBe(200)
+ expect(() => configuredGfsInteger('limit', '201', 16, 200)).toThrow()
+
+ vi.stubEnv('MCP_HOST_GFS_MAX_FILE_BYTES', String(17 * 1024 * 1024))
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES', String(16 * 1024 * 1024))
+ vi.resetModules()
+ await expect(import('./gfsFilePolicy')).rejects.toThrow(
+ 'must fit within the caller retained-storage budget'
+ )
+
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES', String(1024 * 1024 * 1024 + 1))
+ vi.resetModules()
+ await expect(import('./gfsFilePolicy')).rejects.toThrow(
+ 'must not exceed the Host aggregate retained-storage budget'
+ )
+
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES', undefined)
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES', '65')
+ vi.resetModules()
+ await expect(import('./gfsFilePolicy')).rejects.toThrow('must be no greater than 64')
+
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES', undefined)
+ vi.stubEnv('MCP_HOST_GFS_CALLER_DOWNLOAD_CONCURRENCY', '3')
+ vi.resetModules()
+ await expect(import('./gfsFilePolicy')).rejects.toThrow('must be no greater than 2')
+ })
+})
diff --git a/mcp-host/src/internalTools/gfsFilePolicy.ts b/mcp-host/src/internalTools/gfsFilePolicy.ts
new file mode 100644
index 000000000..3846512e6
--- /dev/null
+++ b/mcp-host/src/internalTools/gfsFilePolicy.ts
@@ -0,0 +1,75 @@
+const MIB = 1024 * 1024
+
+export const GFS_HOST_RETAINED_FILES = 64
+export const GFS_HOST_ACTIVE_DOWNLOADS = 2
+
+export function configuredGfsInteger(
+ name: string,
+ raw: string | undefined,
+ fallback: number,
+ maximum: number
+): number {
+ if (raw === undefined) return fallback
+ if (!/^[1-9][0-9]*$/.test(raw)) throw new Error(`${name} must be a positive decimal integer`)
+ const value = Number(raw)
+ if (!Number.isSafeInteger(value) || value > maximum)
+ throw new Error(`${name} must be no greater than ${maximum}`)
+ return value
+}
+
+function requiredGfsInteger(name: string, raw: string | undefined, fallback: number): number {
+ return configuredGfsInteger(name, raw, fallback, Number.MAX_SAFE_INTEGER)
+}
+
+/** Generic GFS transfer policy, independent of visual model delivery. */
+export const GFS_FILE_LIMITS = Object.freeze({
+ maxFileBytes: configuredGfsInteger(
+ 'MCP_HOST_GFS_MAX_FILE_BYTES',
+ process.env.MCP_HOST_GFS_MAX_FILE_BYTES,
+ 16 * MIB,
+ 200 * MIB
+ ),
+ inlineTextBytes: 8 * 1024,
+ metadataBytes: 64 * 1024,
+ errorBytes: 8 * 1024,
+ storageBytes: requiredGfsInteger(
+ 'MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES',
+ process.env.MCP_HOST_GFS_DOWNLOAD_STORAGE_BYTES,
+ 1024 * MIB
+ ),
+ callerStorageBytes: requiredGfsInteger(
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES',
+ process.env.MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES,
+ 256 * MIB
+ ),
+ callerRetainedFiles: configuredGfsInteger(
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES',
+ process.env.MCP_HOST_GFS_CALLER_DOWNLOAD_MAX_FILES,
+ 8,
+ GFS_HOST_RETAINED_FILES
+ ),
+ callerActiveDownloads: configuredGfsInteger(
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_CONCURRENCY',
+ process.env.MCP_HOST_GFS_CALLER_DOWNLOAD_CONCURRENCY,
+ 1,
+ GFS_HOST_ACTIVE_DOWNLOADS
+ ),
+ retentionMs:
+ configuredGfsInteger(
+ 'MCP_HOST_GFS_DOWNLOAD_TTL_HOURS',
+ process.env.MCP_HOST_GFS_DOWNLOAD_TTL_HOURS,
+ 168,
+ 8760
+ ) *
+ 60 *
+ 60 *
+ 1000,
+})
+
+if (GFS_FILE_LIMITS.maxFileBytes > GFS_FILE_LIMITS.callerStorageBytes)
+ throw new Error('MCP_HOST_GFS_MAX_FILE_BYTES must fit within the caller retained-storage budget')
+
+if (GFS_FILE_LIMITS.callerStorageBytes > GFS_FILE_LIMITS.storageBytes)
+ throw new Error(
+ 'MCP_HOST_GFS_CALLER_DOWNLOAD_STORAGE_BYTES must not exceed the Host aggregate retained-storage budget'
+ )
diff --git a/mcp-host/src/visualInput/deliveryLimits.test.ts b/mcp-host/src/visualInput/deliveryLimits.test.ts
new file mode 100644
index 000000000..1f914973b
--- /dev/null
+++ b/mcp-host/src/visualInput/deliveryLimits.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { resolveVisualDeliveryLimits } from './deliveryLimits'
+
+describe('effective visual delivery limits', () => {
+ it('reuses the Codex contract as the explicit subscription profile', () => {
+ expect(resolveVisualDeliveryLimits('codex-subscription')).toEqual({
+ maxImageBytes: 16 * 1024 * 1024,
+ maxTotalImageBytes: 16 * 1024 * 1024,
+ maxImages: 20,
+ maxVisualRequestBytes: 24 * 1024 * 1024,
+ maxDimension: 2048,
+ maxPixels: 4_194_304,
+ })
+ })
+
+ it('does not invent profiles for other providers or wire families', () => {
+ expect(resolveVisualDeliveryLimits('openai')).toBeNull()
+ expect(resolveVisualDeliveryLimits('grok-subscription')).toBeNull()
+ expect(resolveVisualDeliveryLimits('unknown')).toBeNull()
+ })
+})
diff --git a/mcp-host/src/visualInput/deliveryLimits.ts b/mcp-host/src/visualInput/deliveryLimits.ts
new file mode 100644
index 000000000..4201aa936
--- /dev/null
+++ b/mcp-host/src/visualInput/deliveryLimits.ts
@@ -0,0 +1,31 @@
+import {
+ LIMITS as CODEX_LIMITS,
+ VISUAL_LIMITS as CODEX_VISUAL_LIMITS,
+} from '@clerum/llm-provider-attempt-contract'
+
+export interface VisualDeliveryLimits {
+ maxImageBytes: number
+ maxTotalImageBytes: number
+ maxImages: number
+ maxVisualRequestBytes: number
+ maxNonImageRequestBytes?: number
+ maxDimension?: number
+ maxPixels?: number
+}
+
+/**
+ * Effective visual limits are supplied by the physical provider contract. They
+ * are deliberately not source-transfer limits and must not be copied into GFS
+ * metadata admission.
+ */
+export function resolveVisualDeliveryLimits(providerType: string): VisualDeliveryLimits | null {
+ if (providerType !== 'codex-subscription') return null
+ return {
+ maxImageBytes: CODEX_VISUAL_LIMITS.maxImageBytes,
+ maxTotalImageBytes: CODEX_VISUAL_LIMITS.maxTotalImageBytes,
+ maxImages: CODEX_VISUAL_LIMITS.maxImages,
+ maxVisualRequestBytes: CODEX_LIMITS.maxVisualRequestBodyBytes,
+ maxDimension: CODEX_VISUAL_LIMITS.maxImageDimension,
+ maxPixels: CODEX_VISUAL_LIMITS.maxImagePixels,
+ }
+}