mavis_usage

Instructions

Implementation Reference

• src/index.js:77-92 (handler)

  The runTool function is the generic handler for all tools, including mavis_usage. It executes the tool by calling execMavisJSON with the buildArgs result.

  function runTool(spec, parsedArgs) {
    const { execFn, outputMode, stdin, buildArgs } = spec;
    const args = buildArgs(parsedArgs);
    const input = typeof stdin === 'function' ? stdin(parsedArgs) : stdin;
  
    const execPromise = execFn
      ? execMavis(args, input || '')
      : execMavisJSON(args);
  
    return execPromise.then(result => {
      const text = outputMode === OUTPUT_RAW
        ? (result || '')
        : JSON.stringify(result, null, 2);
      return [{ type: 'text', text }];
    });
  }

• src/index.js:449-455 (schema)

  Input schema for mavis_usage: accepts optional sessionId, agentName, from (unix-ms), to (unix-ms), and group (enum: agent/session/model/day).

  inputSchema: z.object({
    sessionId: z.string().optional().describe('Session ID to query usage for'),
    agentName: z.string().optional().describe('Agent name to query usage for'),
    from: z.number().optional().describe('Start of time range (unix-ms)'),
    to: z.number().optional().describe('End of time range (unix-ms)'),
    group: z.enum(['agent', 'session', 'model', 'day']).optional().describe('Group by dimension')
  }).strict(),

• src/index.js:446-466 (registration)

  The mavis_usage tool definition in the tools array, with name, description, inputSchema, and buildArgs. Registered as part of the tool list.

  {
    name: 'mavis_usage',
    description: 'Inspect token usage by session, agent, or globally.',
    inputSchema: z.object({
      sessionId: z.string().optional().describe('Session ID to query usage for'),
      agentName: z.string().optional().describe('Agent name to query usage for'),
      from: z.number().optional().describe('Start of time range (unix-ms)'),
      to: z.number().optional().describe('End of time range (unix-ms)'),
      group: z.enum(['agent', 'session', 'model', 'day']).optional().describe('Group by dimension')
    }).strict(),
    buildArgs: ({ sessionId, agentName, from, to, group }) => {
      const args = sessionId ? ['usage', 'session', sessionId]
        : agentName ? ['usage', 'agent', agentName]
        : ['usage', 'list'];
      if (from !== undefined) args.push('--from', String(from));
      if (to !== undefined) args.push('--to', String(to));
      if (group) args.push('--group', group);
      args.push('--json');
      return args;
    }
  }

• src/index.js:55-64 (helper)

  execMavisJSON helper wraps execMavis to parse JSON output - used by mavis_usage since it has no execFn, so it goes through execMavisJSON.

  function execMavisJSON(args) {
    return execMavis(args).then(raw => {
      try {
        return JSON.parse(raw);
      } catch {
        const jsonStart = raw.indexOf('{');
        return JSON.parse(jsonStart >= 0 ? raw.slice(jsonStart) : raw);
      }
    });
  }

• src/index.js:484-509 (registration)

  MavisServer registers all tools (including mavis_usage) by building a toolMap and handling CallToolRequestSchema by looking up the tool, parsing args, and running it.

  this.toolMap = new Map(tools.map(t => [t.name, t]));
  
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: tools.map(t => ({
      name: t.name,
      description: t.description,
      inputSchema: normalizeObjectSchema(t.inputSchema),
    })),
  }));
  
  this.server.setRequestHandler(CallToolRequestSchema, async request => {
    const { name, arguments: args } = request.params;
    const tool = this.toolMap.get(name);
  
    if (!tool) {
      return { content: [{ type: 'text', text: `Error: unknown tool "${name}"` }], isError: true };
    }
  
    try {
      const parsedArgs = tool.inputSchema.parse(args || {});
      const results = await runTool(tool, parsedArgs);
      return { content: results };
    } catch (err) {
      return { content: [{ type: 'text', text: `Mavis error: ${err.message}` }], isError: true };
    }
  });