trace_file
Analyze TypeScript files to detect schema mismatches between data producers and consumers, preventing runtime errors by validating contracts during development.
Instructions
Trace MCP tool usage in a single TypeScript file.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to a TypeScript file |
Implementation Reference
- src/index.ts:357-375 (handler)Main handler switch case for the 'trace_file' tool. Validates input using TraceFileInput schema, invokes traceFromFile helper, formats consumer usage data as JSON, and returns it.
case 'trace_file': { const input = TraceFileInput.parse(args); log(`Tracing file: ${input.filePath}`); const usage = await traceFromFile(input.filePath); return { content: [ { type: 'text', text: JSON.stringify({ success: true, count: usage.length, usage, }, null, 2), }, ], }; } - src/index.ts:69-71 (schema)Zod input validation schema for the trace_file tool requiring a filePath.
const TraceFileInput = z.object({ filePath: z.string().describe('Path to a single TypeScript file to trace tool usage in'), }); - src/index.ts:167-177 (registration)Registration of the trace_file tool in the ListTools response, defining name, description, and JSON inputSchema.
{ name: 'trace_file', description: 'Trace MCP tool usage in a single TypeScript file.', inputSchema: { type: 'object', properties: { filePath: { type: 'string', description: 'Path to a TypeScript file' }, }, required: ['filePath'], }, }, - src/trace/index.ts:53-75 (helper)Helper function invoked by the handler. Defaults to TypeScript parser, traces usage by scanning parent directory but including only the target file, filters results to that file.
export async function traceFromFile(filePath: string, language?: string): Promise<ConsumerSchema[]> { // For backward compatibility, default to TypeScript const lang = language || 'typescript'; if (!hasParser(lang)) { throw new Error( `No parser available for language: ${lang}. Make sure to call bootstrapLanguageParsers() at startup.` ); } const parser = getParser(lang); // Extract from the directory containing the file const rootDir = filePath.substring(0, filePath.lastIndexOf('/') || filePath.lastIndexOf('\\')); const fileName = filePath.substring((filePath.lastIndexOf('/') || filePath.lastIndexOf('\\')) + 1); const allSchemas = await parser.traceUsage({ rootDir: rootDir || '.', include: [fileName], }); return allSchemas.filter(s => s.callSite.file === filePath); } - src/languages/typescript.ts:273-299 (helper)Core TypeScript-specific tracing logic. Scans AST for callTool expressions, parses tool name and arguments, traces expected output properties via result usage analysis.
private traceFile(sourceFile: SourceFile, filePath: string): ConsumerSchema[] { const schemas: ConsumerSchema[] = []; // Find all callTool() calls sourceFile.forEachDescendant((node) => { if (Node.isCallExpression(node)) { const callInfo = this.parseCallToolExpression(node); if (callInfo) { // Track how the result is used const expectedProps = this.traceResultUsage(node); schemas.push({ toolName: callInfo.toolName, callSite: { file: filePath, line: node.getStartLineNumber(), column: node.getStartLinePos(), }, argumentsProvided: callInfo.arguments, expectedProperties: expectedProps, }); } } }); return schemas; }