Xdebug MCP Server

Instructions

Implementation Reference

• src/tools/inspection.ts:461-523 (handler)

  The MCP tool handler for 'get_source'. Resolves the debug session, calls session.getSource to retrieve the source code, handles errors, and returns the result as MCP text content.

  async ({ file, begin_line, end_line, session_id }) => {
    const session = sessionManager.resolveSession(session_id);
  
    if (!session) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: 'No active debug session' }),
          },
        ],
      };
    }
  
    try {
      const source = await session.getSource(file, begin_line, end_line);
  
      if (source === null) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to get source',
                file,
                message: 'File not found or not accessible',
              }),
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(
              {
                file,
                beginLine: begin_line,
                endLine: end_line,
                source,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              error: 'Failed to get source',
              message: error instanceof Error ? error.message : String(error),
            }),
          },
        ],
      };
    }
  }

• src/tools/inspection.ts:455-460 (schema)

  Zod input schema defining parameters for the get_source tool: file path and optional line range.

  {
    file: z.string().describe('File path to get source from'),
    begin_line: z.number().int().optional().describe('Starting line number'),
    end_line: z.number().int().optional().describe('Ending line number'),
    session_id: z.string().optional().describe('Session ID'),
  },

• src/tools/inspection.ts:452-524 (registration)

  Registration of the 'get_source' tool using server.tool(), including name, description, schema, and handler within the registerInspectionTools function.

  server.tool(
    'get_source',
    'Get the source code of a file or a specific line range',
    {
      file: z.string().describe('File path to get source from'),
      begin_line: z.number().int().optional().describe('Starting line number'),
      end_line: z.number().int().optional().describe('Ending line number'),
      session_id: z.string().optional().describe('Session ID'),
    },
    async ({ file, begin_line, end_line, session_id }) => {
      const session = sessionManager.resolveSession(session_id);
  
      if (!session) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ error: 'No active debug session' }),
            },
          ],
        };
      }
  
      try {
        const source = await session.getSource(file, begin_line, end_line);
  
        if (source === null) {
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  error: 'Failed to get source',
                  file,
                  message: 'File not found or not accessible',
                }),
              },
            ],
          };
        }
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(
                {
                  file,
                  beginLine: begin_line,
                  endLine: end_line,
                  source,
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                error: 'Failed to get source',
                message: error instanceof Error ? error.message : String(error),
              }),
            },
          ],
        };
      }
    }
  );

• src/session/session.ts:457-482 (helper)

  Core helper method in DebugSession that sends the DBGP 'source' command to retrieve file source code, handles base64 decoding if needed, and returns the source string.

  async getSource(
    fileUri: string,
    beginLine?: number,
    endLine?: number
  ): Promise<string | null> {
    const args: Record<string, string> = {
      f: this.normalizeFileUri(fileUri),
    };
  
    if (beginLine !== undefined) args['b'] = beginLine.toString();
    if (endLine !== undefined) args['e'] = endLine.toString();
  
    const response = await this.connection.sendCommand('source', args);
  
    if (response.error) return null;
  
    const data = response.data as Record<string, string>;
    const encoding = data['@_encoding'];
    const content = data['#text'] || '';
  
    if (encoding === 'base64' && content) {
      return Buffer.from(content, 'base64').toString('utf8');
    }
  
    return content;
  }