Read Advisor Metadata

Instructions

Implementation Reference

• src/index.ts:563-627 (registration)

  Registration of the 'read_advisor_meta' tool on the MCP server with title, description, input schema, and annotations.

  server.registerTool("read_advisor_meta", {
    title: "Read Advisor Metadata",
    description:
      "Read structured metadata (latency, token counts, effort levels) from all " +
      "consultations. Useful for understanding cost and performance patterns.",
    inputSchema: {
      last_n: z
        .number()
        .optional()
        .describe("Number of recent entries to return. Omit for all."),
    },
    annotations: {
      readOnlyHint: true,
    },
  }, async ({ last_n }) => {
    try {
      const raw = await readFile(ADVISOR_META, "utf-8").catch(() => "");
      if (!raw.trim()) {
        return {
          content: [{ type: "text" as const, text: "No metadata yet." }],
        };
      }
      const lines = raw.trim().split("\n");
      const selected = last_n ? lines.slice(-last_n) : lines;
  
      // Parse and format as a summary table
      const entries = selected.map((line) => {
        try { return JSON.parse(line); } catch { return null; }
      }).filter(Boolean);
  
      const totalLatency = entries.reduce(
        (sum: number, e: { latencyMs: number }) => sum + e.latencyMs, 0,
      );
      const totalAdviceTokens = entries.reduce(
        (sum: number, e: { adviceTokens: number }) => sum + e.adviceTokens, 0,
      );
  
      const summary = [
        `## Advisor Metadata (${entries.length} consultations)`,
        "",
        `| # | Timestamp | Effort | Latency | Q Tokens | Advice Tokens |`,
        `|---|-----------|--------|---------|----------|---------------|`,
        ...entries.map((e: {
          timestamp: string;
          effort: string;
          latencyMs: number;
          questionTokens: number;
          adviceTokens: number;
        }, i: number) =>
          `| ${i + 1} | ${e.timestamp.slice(0, 19)} | ${e.effort} | ${(e.latencyMs / 1000).toFixed(1)}s | ~${e.questionTokens} | ~${e.adviceTokens} |`,
        ),
        "",
        `**Totals**: ${(totalLatency / 1000).toFixed(1)}s latency, ~${totalAdviceTokens} advice tokens`,
      ].join("\n");
  
      return { content: [{ type: "text" as const, text: summary }] };
    } catch (err) {
      const message =
        err instanceof Error ? err.message : "Unknown error reading metadata";
      return {
        content: [{ type: "text" as const, text: `Error: ${message}` }],
        isError: true,
      };
    }
  });

• src/index.ts:577-627 (handler)

  Handler function that reads advisor-meta.jsonl, parses JSON lines, computes aggregate stats (latency, token counts), and returns a formatted markdown table.

  }, async ({ last_n }) => {
    try {
      const raw = await readFile(ADVISOR_META, "utf-8").catch(() => "");
      if (!raw.trim()) {
        return {
          content: [{ type: "text" as const, text: "No metadata yet." }],
        };
      }
      const lines = raw.trim().split("\n");
      const selected = last_n ? lines.slice(-last_n) : lines;
  
      // Parse and format as a summary table
      const entries = selected.map((line) => {
        try { return JSON.parse(line); } catch { return null; }
      }).filter(Boolean);
  
      const totalLatency = entries.reduce(
        (sum: number, e: { latencyMs: number }) => sum + e.latencyMs, 0,
      );
      const totalAdviceTokens = entries.reduce(
        (sum: number, e: { adviceTokens: number }) => sum + e.adviceTokens, 0,
      );
  
      const summary = [
        `## Advisor Metadata (${entries.length} consultations)`,
        "",
        `| # | Timestamp | Effort | Latency | Q Tokens | Advice Tokens |`,
        `|---|-----------|--------|---------|----------|---------------|`,
        ...entries.map((e: {
          timestamp: string;
          effort: string;
          latencyMs: number;
          questionTokens: number;
          adviceTokens: number;
        }, i: number) =>
          `| ${i + 1} | ${e.timestamp.slice(0, 19)} | ${e.effort} | ${(e.latencyMs / 1000).toFixed(1)}s | ~${e.questionTokens} | ~${e.adviceTokens} |`,
        ),
        "",
        `**Totals**: ${(totalLatency / 1000).toFixed(1)}s latency, ~${totalAdviceTokens} advice tokens`,
      ].join("\n");
  
      return { content: [{ type: "text" as const, text: summary }] };
    } catch (err) {
      const message =
        err instanceof Error ? err.message : "Unknown error reading metadata";
      return {
        content: [{ type: "text" as const, text: `Error: ${message}` }],
        isError: true,
      };
    }
  });

• src/index.ts:568-573 (schema)

  Input schema for the tool: optional 'last_n' number to limit the number of recent entries returned.

  inputSchema: {
    last_n: z
      .number()
      .optional()
      .describe("Number of recent entries to return. Omit for all."),
  },

• src/index.ts:32-32 (helper)

  Constant ADVISOR_META defining the file path to advisor-meta.jsonl where the tool reads metadata from.

  const ADVISOR_META = join(ADVISOR_DIR, "advisor-meta.jsonl");