Skip to content

Diff

diff

MCP tool for structural branch diff.

DiffTool

Bases: AXMTool

Compare two git refs at symbol level.

Registered as ast_diff via axm.tools entry point. Uses git worktrees to avoid disturbing the working tree.

Source code in packages/axm-ast/src/axm_ast/tools/diff.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
class DiffTool(AXMTool):
    """Compare two git refs at symbol level.

    Registered as ``ast_diff`` via axm.tools entry point.
    Uses git worktrees to avoid disturbing the working tree.
    """

    @property
    def name(self) -> str:
        """Return tool name for registry lookup."""
        return "ast_diff"

    def execute(
        self,
        *,
        path: str = ".",
        base: str = "",
        head: str = "",
        **kwargs: Any,
    ) -> ToolResult:
        """Compare two branches at symbol level.

        Args:
            path: Path to package directory.
            base: Base git ref (branch, tag, commit).
            head: Head git ref (branch, tag, commit).

        Returns:
            ToolResult with structural diff data.
        """
        if not base:
            return ToolResult(success=False, error="base parameter is required")
        if not head:
            return ToolResult(success=False, error="head parameter is required")

        try:
            project_path = Path(path).resolve()
            if not project_path.is_dir():
                return ToolResult(
                    success=False, error=f"Not a directory: {project_path}"
                )

            from axm_ast.core.structural_diff import structural_diff

            result = structural_diff(project_path, base, head)

            if "error" in result:
                return ToolResult(success=False, error=result["error"])

            return ToolResult(
                success=True,
                data=result,
                hint="Tip: Use ast_impact(symbol) on changed symbols to assess risk.",
            )
        except Exception as exc:
            return ToolResult(success=False, error=str(exc))
name property

Return tool name for registry lookup.

execute(*, path='.', base='', head='', **kwargs)

Compare two branches at symbol level.

Parameters:

Name Type Description Default
path str

Path to package directory.

 '.'
base str

Base git ref (branch, tag, commit).

 ''
head str

Head git ref (branch, tag, commit).

 ''

Returns:

Type Description
ToolResult

ToolResult with structural diff data.
Source code in packages/axm-ast/src/axm_ast/tools/diff.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def execute(
    self,
    *,
    path: str = ".",
    base: str = "",
    head: str = "",
    **kwargs: Any,
) -> ToolResult:
    """Compare two branches at symbol level.

    Args:
        path: Path to package directory.
        base: Base git ref (branch, tag, commit).
        head: Head git ref (branch, tag, commit).

    Returns:
        ToolResult with structural diff data.
    """
    if not base:
        return ToolResult(success=False, error="base parameter is required")
    if not head:
        return ToolResult(success=False, error="head parameter is required")

    try:
        project_path = Path(path).resolve()
        if not project_path.is_dir():
            return ToolResult(
                success=False, error=f"Not a directory: {project_path}"
            )

        from axm_ast.core.structural_diff import structural_diff

        result = structural_diff(project_path, base, head)

        if "error" in result:
            return ToolResult(success=False, error=result["error"])

        return ToolResult(
            success=True,
            data=result,
            hint="Tip: Use ast_impact(symbol) on changed symbols to assess risk.",
        )
    except Exception as exc:
        return ToolResult(success=False, error=str(exc))