add_instrument
Insert debug instrumentation at a specified line to log variable values during execution for debugging purposes.
Instructions
Add a debug instrument at a specific line in a file. The instrument will log variable values when executed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the file to instrument (relative to working directory) | |
| line | Yes | Line number where to insert the instrument (1-indexed) | |
| capture | No | Variable names to capture and log |
Implementation Reference
- src/index.ts:177-207 (handler)Main handler for the 'add_instrument' tool. Validates active session, parses input arguments, creates instrument using SessionManager, inserts code using Instrumenter, and returns success message with details.case 'add_instrument': { if (!sessionManager.isActive() || !instrumenter) { return { content: [{ type: 'text', text: 'No active debug session. Start one first with start_debug_session.' }], isError: true, }; } const file = args?.file as string; const line = args?.line as number; const capture = (args?.capture as string[]) || []; if (!file || !line) { return { content: [{ type: 'text', text: 'Missing required parameters: file and line' }], isError: true, }; } const instrument = sessionManager.addInstrument({ file, line, capture }); instrumenter.addInstrument(instrument); return { content: [ { type: 'text', text: `Instrument added!\n\nID: ${instrument.id}\nFile: ${instrument.file}\nLine: ${line}\nCapturing: ${capture.length > 0 ? capture.join(', ') : '(no variables)'}\n\nThe instrument will log data when that line is executed.`, }, ], }; }
- src/index.ts:56-79 (registration)Tool registration in the listTools response, including name, description, and input schema.{ name: 'add_instrument', description: 'Add a debug instrument at a specific line in a file. The instrument will log variable values when executed.', inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Path to the file to instrument (relative to working directory)', }, line: { type: 'number', description: 'Line number where to insert the instrument (1-indexed)', }, capture: { type: 'array', items: { type: 'string' }, description: 'Variable names to capture and log', default: [], }, }, required: ['file', 'line'], }, },
- src/index.ts:59-78 (schema)Input schema defining parameters for the add_instrument tool: file (string, required), line (number, required), capture (array of strings, optional).inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Path to the file to instrument (relative to working directory)', }, line: { type: 'number', description: 'Line number where to insert the instrument (1-indexed)', }, capture: { type: 'array', items: { type: 'string' }, description: 'Variable names to capture and log', default: [], }, }, required: ['file', 'line'], },
- src/session.ts:59-76 (helper)SessionManager.addInstrument: Creates Instrument instance with resolved file path, detected language, generates ID, stores in session's instruments Map, returns the instrument.addInstrument(options: InstrumentOptions): Instrument { if (!this.session) { throw new Error('No active debug session'); } const language = this.detectLanguage(options.file); const instrument: Instrument = { id: `dbg-${randomUUID().slice(0, 8)}`, file: resolve(this.workingDirectory, options.file), line: options.line, language, capture: options.capture, createdAt: Date.now() }; this.session.instruments.set(instrument.id, instrument); return instrument; }
- src/instrumenter.ts:16-35 (helper)Instrumenter.addInstrument: Reads target file, validates line number, generates language-specific instrument code, inserts it before the specified line, writes back to file.addInstrument(instrument: Instrument): void { if (!existsSync(instrument.file)) { throw new Error(`File not found: ${instrument.file}`); } const content = readFileSync(instrument.file, 'utf-8'); const lines = content.split('\n'); if (instrument.line < 1 || instrument.line > lines.length + 1) { throw new Error(`Line ${instrument.line} is out of range (file has ${lines.length} lines)`); } const code = this.generateInstrumentCode(instrument); const codeLines = code.split('\n'); // Insert at the specified line (1-indexed, so line 5 means insert before index 4) lines.splice(instrument.line - 1, 0, ...codeLines); writeFileSync(instrument.file, lines.join('\n')); }