trace_usage
Analyze how client code interacts with MCP tools by identifying callTool() invocations and tracking property access on results to detect schema mismatches.
Instructions
Trace how client code uses MCP tools. Finds callTool() invocations and tracks which properties are accessed on results.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rootDir | Yes | Root directory of consumer source code | |
| include | No | Glob patterns to include | |
| exclude | No | Glob patterns to exclude |
Implementation Reference
- src/index.ts:331-355 (handler)MCP tool handler for 'trace_usage': parses input with TraceUsageInput schema, invokes traceConsumerUsage on the consumer directory, logs progress, and returns JSON with traced usage data.
case 'trace_usage': { const input = TraceUsageInput.parse(args); log(`Tracing usage in: ${input.rootDir}`); const usage = await traceConsumerUsage({ rootDir: input.rootDir, include: input.include, exclude: input.exclude, }); log(`Found ${usage.length} tool calls`); return { content: [ { type: 'text', text: JSON.stringify({ success: true, count: usage.length, usage, }, null, 2), }, ], }; } - src/index.ts:51-55 (schema)Zod input schema for the trace_usage tool, defining rootDir (required), include/exclude globs (optional).
const TraceUsageInput = z.object({ rootDir: z.string().describe('Root directory of consumer/client source code'), include: z.array(z.string()).optional().describe('Glob patterns to include'), exclude: z.array(z.string()).optional().describe('Glob patterns to exclude'), }); - src/index.ts:155-166 (registration)Registration of 'trace_usage' tool in the MCP server's listTools response, including name, description, and inputSchema.
name: 'trace_usage', description: 'Trace how client code uses MCP tools. Finds callTool() invocations and tracks which properties are accessed on results.', inputSchema: { type: 'object', properties: { rootDir: { type: 'string', description: 'Root directory of consumer source code' }, include: { type: 'array', items: { type: 'string' }, description: 'Glob patterns to include' }, exclude: { type: 'array', items: { type: 'string' }, description: 'Glob patterns to exclude' }, }, required: ['rootDir'], }, }, - src/trace/index.ts:26-47 (helper)Core helper function traceConsumerUsage invoked by the handler; selects language parser (default: typescript) and delegates to parser.traceUsage for actual tracing logic.
export async function traceConsumerUsage( options: TracerOptions ): Promise<ConsumerSchema[]> { // For backward compatibility, default to TypeScript const language = options.language || 'typescript'; // Get parser from registry if (!hasParser(language)) { throw new Error( `No parser available for language: ${language}. Make sure to call bootstrapLanguageParsers() at startup.` ); } const parser = getParser(language); return parser.traceUsage({ rootDir: options.rootDir, callPatterns: options.callPatterns, include: options.include, exclude: options.exclude, }); }