trace_usage
Analyzes how client code interacts with MCP tools by identifying tool calls and tracking result property access patterns to detect usage patterns.
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)Main handler for the 'trace_usage' MCP tool. Parses input using TraceUsageInput schema, calls traceConsumerUsage from src/trace/index.ts, and formats the result as JSON.
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 validation for the trace_usage tool.
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:154-166 (registration)Registration of the 'trace_usage' tool in the 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 that delegates to the language-specific parser's traceUsage method.
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, }); }