set_breakpoint
Set a breakpoint at a specific line in source code to pause execution during debugging, enabling inspection of program state at that point.
Instructions
Set a breakpoint. Setting breakpoints on non-executable lines (structural, declarative) may lead to unexpected behavior
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sessionId | Yes | ||
| file | Yes | Path to the source file. Use absolute paths or paths relative to your current working directory | |
| line | Yes | Line number where to set breakpoint. Executable statements (assignments, function calls, conditionals, returns) work best. Structural lines (function/class definitions), declarative lines (imports), or non-executable lines (comments, blank lines) may cause unexpected stepping behavior | |
| condition | No |
Implementation Reference
- src/server.ts:447-447 (schema)MCP tool schema definition for 'set_breakpoint', including input schema with parameters sessionId, file, line, and optional condition. Registered in the ListTools response.{ name: 'set_breakpoint', description: 'Set a breakpoint. Setting breakpoints on non-executable lines (structural, declarative) may lead to unexpected behavior', inputSchema: { type: 'object', properties: { sessionId: { type: 'string' }, file: { type: 'string', description: fileDescription }, line: { type: 'number', description: 'Line number where to set breakpoint. Executable statements (assignments, function calls, conditionals, returns) work best. Structural lines (function/class definitions), declarative lines (imports), or non-executable lines (comments, blank lines) may cause unexpected stepping behavior' }, condition: { type: 'string' } }, required: ['sessionId', 'file', 'line'] } },
- src/server.ts:540-624 (handler)Primary handler for executing the 'set_breakpoint' MCP tool. Validates arguments, sets the breakpoint via sessionManager, fetches source context, logs the event, and formats the response with breakpoint details.case 'set_breakpoint': { if (!args.sessionId || !args.file || args.line === undefined) { throw new McpError(McpErrorCode.InvalidParams, 'Missing required parameters'); } try { const breakpoint = await this.setBreakpoint(args.sessionId, args.file, args.line, args.condition); // Log breakpoint event this.logger.info('debug:breakpoint', { event: 'set', sessionId: args.sessionId, sessionName: this.getSessionName(args.sessionId), breakpointId: breakpoint.id, file: breakpoint.file, line: breakpoint.line, verified: breakpoint.verified, timestamp: Date.now() }); // Try to get line context for the breakpoint let context; try { const lineContext = await this.lineReader.getLineContext( breakpoint.file, breakpoint.line, { contextLines: 2 } ); if (lineContext) { context = { lineContent: lineContext.lineContent, surrounding: lineContext.surrounding }; } } catch (contextError) { // Log but don't fail if we can't get context this.logger.debug('Could not get line context for breakpoint', { file: breakpoint.file, line: breakpoint.line, error: contextError }); } result = { content: [{ type: 'text', text: JSON.stringify({ success: true, breakpointId: breakpoint.id, file: breakpoint.file, line: breakpoint.line, verified: breakpoint.verified, message: breakpoint.message || `Breakpoint set at ${breakpoint.file}:${breakpoint.line}`, // Only add warning if there's a message from debugpy (indicating a problem) warning: breakpoint.message || undefined, // Include context if available context: context || undefined }) }] }; const contentEntry = Array.isArray(result.content) ? result.content[0] : undefined; const textContent = contentEntry && typeof (contentEntry as { text?: unknown }).text === 'string' ? (contentEntry as { text: string }).text : undefined; let parsedResponse: Record<string, unknown> | null = null; if (typeof textContent === 'string') { try { parsedResponse = JSON.parse(textContent) as Record<string, unknown>; } catch { parsedResponse = null; } } this.logger.info('tool:set_breakpoint:result', { sessionId: args.sessionId, response: parsedResponse }); } catch (error) { // Handle session state errors specifically if (error instanceof McpError && (error.message.includes('terminated') || error.message.includes('closed') || (error.message.includes('not found') && error.message.includes('Session')))) { result = { content: [{ type: 'text', text: JSON.stringify({ success: false, error: error.message }) }] }; } else { // Re-throw all other errors (including file validation errors) throw error; } } break;
- src/server.ts:268-283 (helper)Helper method that validates the session and file existence before delegating the breakpoint setting to the SessionManager.public async setBreakpoint(sessionId: string, file: string, line: number, condition?: string): Promise<Breakpoint> { this.validateSession(sessionId); // Check file exists for immediate feedback const fileCheck = await this.fileChecker.checkExists(file); if (!fileCheck.exists) { throw new McpError(McpErrorCode.InvalidParams, `Breakpoint file not found: '${file}'\nLooked for: '${fileCheck.effectivePath}'${fileCheck.errorMessage ? `\nError: ${fileCheck.errorMessage}` : ''}`); } this.logger.info(`[DebugMcpServer.setBreakpoint] File exists: ${fileCheck.effectivePath} (original: ${file})`); // Pass the effective path (which has been resolved for container) to session manager return this.sessionManager.setBreakpoint(sessionId, fileCheck.effectivePath, line, condition); }