refactor: simplify getTotalTvl API and update related documentation

Author: sai-aarna

apps/api/src/config/openapi.ts

@@ -584,18 +584,10 @@ export const openApiSpec = {
       get: {
         summary: "Get platform TVL",
         description:
-          "Returns the total TVL across all vaults, or for a specific vault, sourced from the Aarna engine database.",
+          "Returns the total TVL across all vaults, sourced from the Aarna engine database.",
         operationId: "getTotalTvl",
         tags: ["Analytics"],
-        parameters: [
-          {
-            name: "address",
-            in: "query",
-            required: false,
-            description: "Filter to a specific vault address (omit for platform-wide total)",
-            schema: { type: "string", example: "0xabc123..." },
-          },
-        ],
+        parameters: [],
         responses: {
           "200": {
             description: "TVL data",

apps/api/src/config/vault-registry.ts

@@ -36,11 +36,7 @@ class VaultRegistry {
     const vaults = await this.getVaults();
     return Object.fromEntries(
       vaults.map((v) => {
-        const key =
-          v.depositContractType === DepositContractType.ERC4626 &&
-          v.contracts.timelock?.address
-            ? v.contracts.timelock.address.toLowerCase()
-            : v.atvTokenAddress.toLowerCase();
+        const key = v.atvTokenAddress.toLowerCase();
         return [key, v];
       }),
     );

apps/api/src/handlers/analytics.handler.ts

@@ -4,12 +4,12 @@ import { UserInvestmentsQuery } from '../types/api.types';
 
 export const analyticsHandler = {
     getTotalTvl: async (
-        req: Request<{}, {}, {}, { address?: string }>,
+        req: Request,
         res: Response,
         next: NextFunction,
     ) => {
         try {
-            const data = await engineService.getTotalTvl(req.query.address);
+            const data = await engineService.getTotalTvl();
             res.json({ data, message: 'Total TVL retrieved', statusCode: 200 });
         } catch (err) {
             next(err);

apps/api/src/routes/mcp.routes.ts

@@ -409,16 +409,11 @@ Analytics (engine API):
 
   server.tool(
     "get_total_tvl",
-    "Get the total TVL (Total Value Locked) across all ATV vaults, or for a specific vault, from the Aarna engine database.",
-    {
-      address: z
-        .string()
-        .optional()
-        .describe("Vault contract address to filter to a single vault (omit for platform-wide TVL)"),
-    },
+    "Get the total TVL (Total Value Locked) across all ATV vaults from the Aarna engine database.",
+    {},
     { annotations: { title: "Get Total TVL", readOnlyHint: true, destructiveHint: false, openWorldHint: true } },
-    async ({ address }) => {
-      const data = await engineService.getTotalTvl(address);
+    async () => {
+      const data = await engineService.getTotalTvl();
       return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     },
   );

apps/api/src/services/engine.service.ts

@@ -30,15 +30,11 @@ class EngineService {
         headers: { Authorization: env.ENGINE_API_KEY },
       });
     } catch (err: any) {
-      throw new Error(
-        `Failed to reach engine API at ${url}: ${err.message}`,
-      );
+      throw new Error(`Failed to reach engine API at ${url}: ${err.message}`);
     }
 
     if (!response.ok) {
-      throw new Error(
-        `Engine API returned HTTP ${response.status} for ${url}`,
-      );
+      throw new Error(`Engine API returned HTTP ${response.status} for ${url}`);
     }
 
     return response.json() as Promise<T>;
@@ -69,7 +65,11 @@ class EngineService {
    * Returns the underlying token portfolio for the vault.
    */
   async getVaultPortfolio(vaultAddress: string): Promise<unknown> {
-    return this.get("/afi/vault-balance-data", { vaultAddress });
+    const { data } = await this.get<{ data: unknown }>(
+      "/afi/vault-balance-data",
+      { vaultAddress },
+    );
+    return data;
   }
 
   /**
@@ -80,9 +80,16 @@ class EngineService {
     userAddress: string,
     vaultAddress?: string,
   ): Promise<unknown> {
-    const params: Record<string, string> = { address: userAddress };
+    const params: Record<string, any> = {
+      address: userAddress,
+      metaInfo: false,
+    };
     if (vaultAddress) params.vaultAddress = vaultAddress;
-    return this.get("/afi/user-investments", params);
+    const { data } = await this.get<{ data: unknown }>(
+      "/afi/user-investments",
+      params,
+    );
+    return data;
   }
 
   /**
@@ -128,13 +135,12 @@ class EngineService {
   }
 
   /**
-   * GET /afi/total-tvl?vault_address=<addr>
-   * Returns platform-wide or per-vault TVL from the engine DB.
+   * GET /afi/total-tvl
+   * Returns platform-wide TVL from the engine DB.
    */
-  async getTotalTvl(vaultAddress?: string): Promise<unknown> {
-    const params: Record<string, string> = {};
-    if (vaultAddress) params.vault_address = vaultAddress;
-    return this.get("/afi/total-tvl", params);
+  async getTotalTvl(): Promise<unknown> {
+    const { data } = await this.get<{ data: unknown }>("/afi/total-tvl");
+    return data;
   }
 }
 

packages/mcp-server/README.md

@@ -96,7 +96,7 @@ Add to `.vscode/settings.json`:
 | `get_vault_portfolio` | Underlying token portfolio |
 | `get_historical_nav` | NAV over a period (7, 30, 60, 360, max) |
 | `get_historical_tvl` | TVL over a period (7, 30, 60, 360, max) |
-| `get_total_tvl` | Platform-wide or per-vault TVL |
+| `get_total_tvl` | Platform-wide TVL |
 | `get_user_investments` | User portfolio and positions |
 
 ## Example Prompts