feat: return empty array for resources/list, add asset TTL configuration and cleanup logic to manage ephemeral assets

Author: Justineo

packages/mcp-server/README.md

@@ -26,13 +26,18 @@ Supported tools/resources:
 - `get_screenshot`: PNG capture with a downloadable asset link.
 - `tempad-assets` resource template (`asset://tempad/{hash}`) for binaries referenced by tool responses.
 
+Notes:
+
+- Assets are ephemeral and tool-linked; `resources/list` is intentionally empty to avoid cross-session/design-file pollution. Use `resource_link` blocks from tool results and `resources/read` (or the HTTP fallback URL) to fetch bytes.
+
 ## Configuration
 
 Optional environment variables:
 
 - `TEMPAD_MCP_TOOL_TIMEOUT`: Tool call timeout in milliseconds (default `15000`).
 - `TEMPAD_MCP_AUTO_ACTIVATE_GRACE`: Delay before auto-activating the sole connected extension (default `1500`).
 - `TEMPAD_MCP_MAX_ASSET_BYTES`: Maximum upload size for captured assets/screenshots in bytes (default `8388608`).
+- `TEMPAD_MCP_ASSET_TTL_MS`: Asset cleanup TTL in milliseconds based on last access; set `0` to disable (default `2592000000`).
 - `TEMPAD_MCP_RUNTIME_DIR`: Override runtime directory (defaults to system temp under `tempad-dev/run`).
 - `TEMPAD_MCP_LOG_DIR`: Override log directory (defaults to system temp under `tempad-dev/log`).
 - `TEMPAD_MCP_ASSET_DIR`: Override asset storage directory (defaults to system temp under `tempad-dev/assets`).

packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempad-dev/mcp",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "MCP server for TemPad Dev.",
   "bin": "dist/cli.mjs",
   "files": [

packages/mcp-server/src/config.ts

@@ -1,5 +1,6 @@
 import {
   MCP_AUTO_ACTIVATE_GRACE_MS,
+  MCP_ASSET_TTL_MS,
   MCP_MAX_ASSET_BYTES,
   MCP_MAX_PAYLOAD_BYTES,
   MCP_PORT_CANDIDATES,
@@ -11,6 +12,11 @@ function parsePositiveInt(envValue: string | undefined, fallback: number): numbe
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
 }
 
+function parseNonNegativeInt(envValue: string | undefined, fallback: number): number {
+  const parsed = envValue ? Number.parseInt(envValue, 10) : Number.NaN
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback
+}
+
 function resolveToolTimeoutMs(): number {
   return parsePositiveInt(process.env.TEMPAD_MCP_TOOL_TIMEOUT, MCP_TOOL_TIMEOUT_MS)
 }
@@ -23,12 +29,17 @@ function resolveMaxAssetSizeBytes(): number {
   return parsePositiveInt(process.env.TEMPAD_MCP_MAX_ASSET_BYTES, MCP_MAX_ASSET_BYTES)
 }
 
+function resolveAssetTtlMs(): number {
+  return parseNonNegativeInt(process.env.TEMPAD_MCP_ASSET_TTL_MS, MCP_ASSET_TTL_MS)
+}
+
 export function getMcpServerConfig() {
   return {
     wsPortCandidates: [...MCP_PORT_CANDIDATES],
     toolTimeoutMs: resolveToolTimeoutMs(),
     maxPayloadBytes: MCP_MAX_PAYLOAD_BYTES,
     autoActivateGraceMs: resolveAutoActivateGraceMs(),
-    maxAssetSizeBytes: resolveMaxAssetSizeBytes()
+    maxAssetSizeBytes: resolveMaxAssetSizeBytes(),
+    assetTtlMs: resolveAssetTtlMs()
   }
 }

packages/mcp-server/src/hub.ts

@@ -38,7 +38,7 @@ import { PACKAGE_VERSION, log, RUNTIME_DIR, SOCK_PATH, ensureDir } from './share
 import { TOOL_DEFS, coercePayloadToToolResponse, createToolErrorResponse } from './tools'
 
 const SHUTDOWN_TIMEOUT = 2000
-const { wsPortCandidates, toolTimeoutMs, maxPayloadBytes, autoActivateGraceMs } =
+const { wsPortCandidates, toolTimeoutMs, maxPayloadBytes, autoActivateGraceMs, assetTtlMs } =
   getMcpServerConfig()
 
 log.info({ version: PACKAGE_VERSION }, 'TemPad MCP Hub starting...')
@@ -113,27 +113,24 @@ const assetStore = createAssetStore()
 const assetHttpServer = createAssetHttpServer(assetStore)
 await assetHttpServer.start()
 registerAssetResources()
+scheduleAssetCleanup()
 
 function registerAssetResources(): void {
   const template = new ResourceTemplate(MCP_ASSET_URI_TEMPLATE, {
     list: async () => ({
-      resources: assetStore
-        .list()
-        .filter((record) => existsSync(record.filePath))
-        .map((record) => ({
-          uri: buildAssetResourceUri(record.hash),
-          name: formatAssetResourceName(record.hash),
-          description: `${record.mimeType} (${formatBytes(record.size)})`,
-          mimeType: record.mimeType
-        }))
+      // Intentionally keep resources/list empty: assets are ephemeral, tool-linked blobs.
+      // Resource discovery would leak across sessions/design files and add UI noise.
+      // Hosts should use resource_link from tool responses to access assets on demand.
+      resources: []
     })
   })
 
   mcp.registerResource(
     MCP_ASSET_RESOURCE_NAME,
     template,
     {
-      description: 'Binary assets captured by the TemPad Dev hub.'
+      description:
+        'Exported PNG/SVG assets which can serve as screenshots or be referenced in code output.'
     },
     async (_uri, variables) => {
       const hash = typeof variables.hash === 'string' ? variables.hash : ''
@@ -142,6 +139,39 @@ function registerAssetResources(): void {
   )
 }
 
+function scheduleAssetCleanup(): void {
+  if (assetTtlMs <= 0) {
+    log.info('Asset TTL cleanup disabled (TEMPAD_MCP_ASSET_TTL_MS=0).')
+    return
+  }
+  pruneExpiredAssets(assetTtlMs)
+  const intervalMs = Math.min(assetTtlMs, 24 * 60 * 60 * 1000)
+  const timer = setInterval(() => {
+    pruneExpiredAssets(assetTtlMs)
+  }, intervalMs)
+  unrefTimer(timer)
+  log.info(
+    { ttlMs: assetTtlMs, intervalMs },
+    'Asset TTL cleanup enabled (list remains empty; assets are tool-linked).'
+  )
+}
+
+function pruneExpiredAssets(ttlMs: number): void {
+  const now = Date.now()
+  let removed = 0
+  let checked = 0
+  for (const record of assetStore.list()) {
+    checked += 1
+    const lastAccess = Number.isFinite(record.lastAccess) ? record.lastAccess : record.uploadedAt
+    if (!lastAccess) continue
+    if (now - lastAccess > ttlMs) {
+      assetStore.remove(record.hash)
+      removed += 1
+    }
+  }
+  log.info({ checked, removed, ttlMs }, 'Asset TTL sweep completed.')
+}
+
 async function readAssetResource(hash: string) {
   if (!hash) {
     throw new Error('Missing asset hash in resource URI.')

packages/mcp-shared/src/constants.ts

@@ -11,6 +11,8 @@ export const MCP_AUTO_ACTIVATE_GRACE_MS = 1500
 
 // Maximum allowed size for uploaded assets (bytes).
 export const MCP_MAX_ASSET_BYTES = 8 * 1024 * 1024
+// Default asset TTL before cleanup (ms). Set to 0 to disable.
+export const MCP_ASSET_TTL_MS = 30 * 24 * 60 * 60 * 1000
 
 export const MCP_ASSET_RESOURCE_NAME = 'tempad-assets'
 export const MCP_ASSET_URI_PREFIX = 'asset://tempad/'