cache_list

Instructions

Implementation Reference

• packages/mcp/src/index.ts:726-755 (registration)

  Tool 'cache_list' is registered using server.tool() with the name 'cache_list', description 'List all caches...', schema (instanceId optional), and handler.

  server.tool(
    'cache_list',
    'List all caches (semantic_cache and agent_cache) registered for the active instance, with hit rate and total ops.',
    {
      instanceId: z.string().regex(/^[a-zA-Z0-9_-]+$/).optional().describe('Connection ID; defaults to the active instance'),
    },
    async (params) => withTelemetry('cache_list', async () => {
      try {
        const id = resolveInstanceId(params.instanceId);
        const data = await apiFetch(`/mcp/instance/${id}/caches`) as {
          caches: Array<{ name: string; type: string; hit_rate: number; total_ops: number; status: string }>;
        };
        if (isLicenseError(data)) {
          return { content: [{ type: 'text' as const, text: licenseErrorResult(data) }] };
        }
        if (data.caches.length === 0) {
          return { content: [{ type: 'text' as const, text: 'No caches registered for this instance.' }] };
        }
        const lines = data.caches.map((c) =>
          `${c.name} (${c.type}, ${c.status}) — hit rate ${(c.hit_rate * 100).toFixed(1)}%, ops ${c.total_ops}`,
        );
        return { content: [{ type: 'text' as const, text: lines.join('\n') }] };
      } catch (err) {
        return {
          content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }],
          isError: true,
        };
      }
    }),
  );

• packages/mcp/src/index.ts:732-755 (handler)

  Handler for cache_list: resolves instanceId, calls GET /mcp/instance/{id}/caches, formats output as name/type/status/hit rate/ops.

    async (params) => withTelemetry('cache_list', async () => {
      try {
        const id = resolveInstanceId(params.instanceId);
        const data = await apiFetch(`/mcp/instance/${id}/caches`) as {
          caches: Array<{ name: string; type: string; hit_rate: number; total_ops: number; status: string }>;
        };
        if (isLicenseError(data)) {
          return { content: [{ type: 'text' as const, text: licenseErrorResult(data) }] };
        }
        if (data.caches.length === 0) {
          return { content: [{ type: 'text' as const, text: 'No caches registered for this instance.' }] };
        }
        const lines = data.caches.map((c) =>
          `${c.name} (${c.type}, ${c.status}) — hit rate ${(c.hit_rate * 100).toFixed(1)}%, ops ${c.total_ops}`,
        );
        return { content: [{ type: 'text' as const, text: lines.join('\n') }] };
      } catch (err) {
        return {
          content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }],
          isError: true,
        };
      }
    }),
  );

• packages/mcp/src/index.ts:729-731 (schema)

  Input schema for cache_list: optional instanceId parameter (string matching /^[a-zA-Z0-9_-]+$/).

  {
    instanceId: z.string().regex(/^[a-zA-Z0-9_-]+$/).optional().describe('Connection ID; defaults to the active instance'),
  },