leanback 0.1.0__py3-none-any.whl

leanback/mcp_server.py

@@ -0,0 +1,1179 @@
+#!/usr/bin/env python3
+"""MCP server that exposes LeanBack tools for Lean 4 theorem proving."""
+
+import argparse
+import functools
+import inspect
+import json
+import logging
+import re
+import shlex
+import sys
+import time
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+
+def _json(obj: object) -> str:
+    """Serialize to JSON with Unicode symbols rendered (not escaped)."""
+    return json.dumps(obj, ensure_ascii=False)
+
+
+def _with_elapsed(func):
+    """Decorator that adds elapsed_ms to every tool response."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        result_json = func(*args, **kwargs)
+        elapsed = round((time.time() - start) * 1000)
+        try:
+            obj = json.loads(result_json)
+            if isinstance(obj, dict):
+                obj["elapsed_ms"] = elapsed
+            return json.dumps(obj, ensure_ascii=False)
+        except (json.JSONDecodeError, TypeError):
+            return result_json
+
+    wrapper.__signature__ = inspect.signature(func)
+    return wrapper
+
+
+# Configure logging (MCP servers use stderr for logging)
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    stream=sys.stderr,
+)
+logger = logging.getLogger(__name__)
+
+# Create the MCP server
+mcp = FastMCP(
+    "LeanBack",
+    instructions="""\
+LeanBack provides tools for Lean 4 theorem proving. All tools are read-only — they never \
+modify files. Use your own file tools to create/edit .lean files, then use LeanBack to verify them.
+
+## Getting Started
+1. Call project_info(project="/path/to/project") to check if a project is ready
+2. If no project exists, create one (requires shell access):
+   lake +leanprover-community/mathlib4:lean-toolchain new <name> math && cd <name> && lake exe cache get
+3. If you have no shell access, ask the user to create a project
+
+## Tool Selection
+- Check project status or get setup help → project_info
+- Want to know if code compiles? → check
+- Want to see the goal state during proof construction? → goals
+- Want to verify a completed proof? → prove
+- Want to run #eval, #check, or test definitions? → eval
+- Looking for a Mathlib lemma or definition? → search
+
+## Proof Development Workflow
+1. Search for relevant lemmas: search(project=..., pattern="add_comm")
+2. See the initial goal: goals(project=..., theorem="...")
+3. Try tactics and inspect remaining goals: goals(project=..., theorem="...", tactics=["intro n"])
+4. If a tactic fails at index i, inspect state before it: goals(project=..., theorem="...", tactics=original[:i])
+5. When proof is complete, verify: prove(project=..., theorem="...", tactics=["intro n", "simp"])
+6. Once working, write to a .lean file and verify: prove(project=..., file="MyProof.lean")
+
+## Important Details
+- All tools require 'project' as an absolute path (e.g., "/home/user/lean/myproject")
+- check has NO mathlib flag — use imports=["Mathlib.Tactic"] instead
+- goals, prove, and eval with mathlib=True all import Mathlib.Tactic (simp, ring, omega, linarith, norm_num, decide, aesop)
+- Tool calls typically take 5-30 seconds. The first call may be slower (Lean server startup).
+""",
+)
+
+
+def _resolve_project(project: str) -> Path | None:
+    """Resolve and validate a project path. Returns Path or None."""
+    p = Path(project)
+    if not p.is_absolute():
+        return None
+    if not p.exists() or not p.is_dir():
+        return None
+    # Check for lakefile
+    if not (p / "lakefile.toml").exists() and not (p / "lakefile.lean").exists():
+        return None
+    return p
+
+
+def _project_error(project: str) -> str:
+    """Return a JSON error for invalid project path."""
+    p = Path(project)
+    if not p.is_absolute():
+        return _json(
+            {
+                "success": False,
+                "error_code": "RELATIVE_PATH",
+                "message": f"Project path must be absolute, got: {project}",
+                "hint": "Use an absolute path like /home/user/lean/myproject",
+            }
+        )
+    if not p.exists():
+        return _json(
+            {
+                "success": False,
+                "error_code": "PATH_NOT_FOUND",
+                "message": f"Path does not exist: {project}",
+                "hint": "Use project_info() to diagnose, or create a project with: "
+                "lake +leanprover-community/mathlib4:lean-toolchain new <name> math",
+            }
+        )
+    if not p.is_dir():
+        return _json(
+            {
+                "success": False,
+                "error_code": "NOT_A_DIRECTORY",
+                "message": f"Path is not a directory: {project}",
+            }
+        )
+    return _json(
+        {
+            "success": False,
+            "error_code": "NOT_A_LEAN_PROJECT",
+            "message": f"No lakefile.toml or lakefile.lean found at: {project}",
+            "hint": "Use project_info() for setup instructions",
+        }
+    )
+
+
+def _sanitize_file_path(file_name: str) -> str:
+    """Replace temp file paths with a descriptive label."""
+    import tempfile
+
+    temp_dir = tempfile.gettempdir()
+    if file_name.startswith(temp_dir) or file_name.startswith("/var/folders/"):
+        return "<inline>"
+    return file_name
+
+
+def _clean_lean_message(message: str) -> str:
+    """Clean up verbose Lean error messages for AI-friendly output."""
+    # Wrap .olean/.lake path errors with a friendlier message
+    if ".olean" in message and "does not exist" in message:
+        match = re.search(r"of module\s+(\S+)", message)
+        module = match.group(1) if match else "the required module"
+        return (
+            f"Module {module} is not built. "
+            f"Run `lake build` in the project directory to compile dependencies.\n"
+            f"Original: {message}"
+        )
+
+    # Truncate verbose search path listings from unknown module errors
+    if "in the search path entries:" in message:
+        truncated = message.split("in the search path entries:")[0].rstrip()
+        return truncated
+
+    return message
+
+
+def _serialize_errors(errors: list, sanitize_paths: bool = False) -> list[dict]:
+    """Serialize LeanError objects to dicts for JSON output."""
+    return [
+        {
+            "file": _sanitize_file_path(e.file_name) if sanitize_paths else e.file_name,
+            "line": e.line,
+            "column": e.column,
+            "end_line": e.end_line,
+            "end_column": e.end_column,
+            "severity": e.severity,
+            "message": _clean_lean_message(e.message),
+            "suggestion": e.suggestion,
+        }
+        for e in errors
+    ]
+
+
+def _has_mathlib(project_path: Path) -> bool:
+    """Check if a project has Mathlib as a dependency."""
+    lakefile_lean = project_path / "lakefile.lean"
+    lakefile_toml = project_path / "lakefile.toml"
+    if lakefile_lean.exists():
+        try:
+            content = lakefile_lean.read_text()
+            return (
+                '"leanprover-community" / "mathlib"' in content
+                or "require mathlib" in content
+                or 'require "mathlib"' in content
+            )
+        except (OSError, UnicodeDecodeError):
+            return False
+    elif lakefile_toml.exists():
+        try:
+            content = lakefile_toml.read_text()
+            return "[dependencies.mathlib]" in content or (
+                "[[require]]" in content and "mathlib" in content
+            )
+        except (OSError, UnicodeDecodeError):
+            return False
+    return False
+
+
+def _get_mathlib_version(project_path: Path) -> str | None:
+    """Read Mathlib version from lake-manifest.json."""
+    manifest = project_path / "lake-manifest.json"
+    if not manifest.exists():
+        return None
+    try:
+        data = json.loads(manifest.read_text())
+        for pkg in data.get("packages", []):
+            if pkg.get("name") == "mathlib":
+                rev = pkg.get("rev", "")
+                return rev[:12] if rev else None
+        return None
+    except (OSError, json.JSONDecodeError, KeyError):
+        return None
+
+
+@mcp.tool()
+@_with_elapsed
+def project_info(project: str) -> str:
+    """Check the status of a Lean project and get setup instructions.
+
+    Call this tool to diagnose whether a project is ready to use, or to get
+    exact shell commands for setting one up. Use before other tools to verify
+    the project is properly configured.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
+
+    Returns JSON with project status. Possible scenarios:
+
+    1. Valid project with Mathlib:
+       {"valid": true, "lean_version": "...", "has_mathlib": true, "built": true}
+
+    2. Path does not exist (includes setup commands):
+       {"valid": false, "reason": "path_not_found", "setup_commands": [...]}
+
+    3. Directory exists but not a Lean project:
+       {"valid": false, "reason": "not_a_lean_project", "setup_commands": [...]}
+
+    4. Valid project without Mathlib:
+       {"valid": true, "has_mathlib": false, "hint": "search and mathlib=True require Mathlib"}
+
+    5. Project not yet built:
+       {"valid": true, "built": false, "setup_commands": ["lake build"]}
+
+    Examples:
+    - Check existing project: project_info(project="/home/user/lean/myproject")
+    - Check before starting: project_info(project="/home/user/lean/newproject")
+    """
+    try:
+        p = Path(project)
+
+        if not p.is_absolute():
+            return _json(
+                {
+                    "valid": False,
+                    "reason": "relative_path",
+                    "message": f"Project path must be absolute, got: {project}",
+                    "hint": "Use an absolute path like /home/user/lean/myproject",
+                }
+            )
+
+        parent = p.parent
+        name = p.name
+
+        # Path does not exist at all
+        if not p.exists():
+            result = {
+                "valid": False,
+                "reason": "path_not_found",
+                "message": f"No directory found at: {project}",
+            }
+            # If parent exists, give setup commands
+            if parent.exists():
+                result["setup_commands"] = [
+                    f"cd {shlex.quote(str(parent))}",
+                    f"lake +leanprover-community/mathlib4:lean-toolchain new {shlex.quote(name)} math",
+                    f"cd {shlex.quote(name)} && lake exe cache get",
+                ]
+                result["note"] = (
+                    "These commands create a Lean project with Mathlib. "
+                    "The cache download takes a few minutes."
+                )
+            else:
+                result["hint"] = f"Parent directory {parent} does not exist either"
+            return _json(result)
+
+        if not p.is_dir():
+            return _json(
+                {
+                    "valid": False,
+                    "reason": "not_a_directory",
+                    "message": f"Path is not a directory: {project}",
+                }
+            )
+
+        # Directory exists but not a Lean project
+        has_lakefile = (p / "lakefile.toml").exists() or (p / "lakefile.lean").exists()
+        if not has_lakefile:
+            return _json(
+                {
+                    "valid": False,
+                    "reason": "not_a_lean_project",
+                    "message": f"No lakefile.toml or lakefile.lean found at: {project}",
+                    "setup_commands": [
+                        f"cd {shlex.quote(str(p))}",
+                        "lake +leanprover-community/mathlib4:lean-toolchain init math",
+                        "lake exe cache get",
+                    ],
+                    "note": (
+                        "These commands initialize a Lean project with Mathlib in the existing directory. "
+                        "The cache download takes a few minutes."
+                    ),
+                }
+            )
+
+        # Valid Lean project — gather diagnostics
+        result = {"valid": True}
+
+        # Lean version
+        toolchain_file = p / "lean-toolchain"
+        if toolchain_file.exists():
+            try:
+                result["lean_version"] = toolchain_file.read_text().strip()
+            except OSError:
+                result["lean_version"] = "unknown"
+        else:
+            result["lean_version"] = "unknown (no lean-toolchain file)"
+
+        # Mathlib status
+        result["has_mathlib"] = _has_mathlib(p)
+
+        if result["has_mathlib"]:
+            mathlib_rev = _get_mathlib_version(p)
+            if mathlib_rev:
+                result["mathlib_revision"] = mathlib_rev
+
+        # Built status
+        build_dir = p / ".lake" / "build"
+        result["built"] = build_dir.exists()
+
+        if not result["built"]:
+            result["setup_commands"] = ["lake build"]
+            result["note"] = "Project exists but has not been built yet"
+
+        if not result["has_mathlib"]:
+            result["hint"] = (
+                "search and mathlib=True require Mathlib. "
+                "To create a project with Mathlib: "
+                "lake +leanprover-community/mathlib4:lean-toolchain new <name> math"
+            )
+
+        # Update hint for Mathlib cache
+        if result["has_mathlib"] and not result["built"]:
+            result["setup_commands"] = ["lake exe cache get", "lake build"]
+            result["note"] = (
+                "Project has Mathlib but is not built. "
+                "Run cache get first to download precompiled files (faster)."
+            )
+
+        return _json(result)
+
+    except Exception as e:
+        return _json(
+            {
+                "valid": False,
+                "reason": "error",
+                "message": str(e),
+            }
+        )
+
+
+@mcp.tool()
+@_with_elapsed
+def check(
+    project: str,
+    file: str | None = None,
+    check_all: bool = False,
+    expr: str | None = None,
+    imports: list[str] | None = None,
+) -> str:
+    """Verify Lean code correctness in a project.
+
+    Use this tool to check if Lean code compiles without errors. It can verify:
+    - Entire projects (when only 'project' is specified)
+    - Specific files within a project (using 'file' parameter)
+    - Individual Lean expressions (using 'expr' parameter)
+    - All files individually for detailed errors (using 'check_all' parameter)
+
+    Choose one mode: check entire project (default), check a specific file, check an expression, or check all files individually.
+    Use only one of 'file', 'expr', or 'check_all' in a single call.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
+    - file: Path to a .lean file within the project (e.g., "Basic.lean", "src/Logic.lean")
+    - check_all: Check each file individually for detailed error reporting (slower but more thorough)
+    - expr: A Lean expression or command to check (e.g., "2 + 2 = 4", "Nat.add", "#eval 1 + 1"). Bare expressions are auto-wrapped in #check.
+    - imports: List of modules to import when checking expressions (e.g., ["Mathlib.Tactic"])
+
+    Returns JSON with 'success' boolean. The 'messages' array contains objects with:
+    - file: Path to the file (or "<inline>" for expressions)
+    - line/column: Location of the issue
+    - severity: "error", "warning", or "info" (e.g., output from #check)
+    - message: The error or output message
+    - suggestion: Helpful hint to fix the issue (when available)
+
+    Examples:
+    - Verify project compiles: check(project="/home/user/lean/myproject")
+    - Check specific file: check(project="/home/user/lean/myproject", file="MyProof.lean")
+    - Test expression: check(project="/home/user/lean/myproject", expr="List.map")
+    - Check proposition: check(project="/home/user/lean/myproject", expr="2 + 2 = 4")
+    - Check with imports: check(project="/home/user/lean/myproject", expr="#check group", imports=["Mathlib.Algebra.Group.Defs"])
+    - Get detailed errors: check(project="/home/user/lean/myproject", check_all=True)
+    """
+    try:
+        from rich.console import Console
+
+        from leanback.check import check_file, check_lean_expr, check_project
+        from leanback.common.project_context import ProjectContext
+
+        project_path = _resolve_project(project)
+        if not project_path:
+            return _project_error(project)
+
+        console = Console(stderr=True)
+
+        # Case 1: Check an expression
+        if expr is not None:
+            expr_stripped = expr.strip()
+            if not expr_stripped:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "NO_EXPRESSION",
+                        "message": "Empty expression. Provide a Lean expression or command to check.",
+                    }
+                )
+
+            # Auto-wrap bare expressions that aren't valid Lean commands
+            lean_commands = (
+                "#",
+                "def ",
+                "theorem ",
+                "lemma ",
+                "example ",
+                "instance ",
+                "structure ",
+                "class ",
+                "inductive ",
+                "abbrev ",
+                "axiom ",
+                "import ",
+                "open ",
+                "namespace ",
+                "section ",
+                "variable ",
+                "set_option ",
+                "attribute ",
+                "noncomputable ",
+                "private ",
+                "protected ",
+                "mutual ",
+            )
+            if expr_stripped and not any(
+                expr_stripped.startswith(cmd) for cmd in lean_commands
+            ):
+                expr = f"#check ({expr_stripped})"
+
+            success, errors = check_lean_expr(
+                expr=expr,
+                imports=imports or [],
+                project_path=project_path,
+                console=console,
+            )
+
+            error_count = sum(1 for e in errors if e.severity == "error")
+            warning_count = sum(1 for e in errors if e.severity == "warning")
+            info_count = sum(1 for e in errors if e.severity == "info")
+
+            result = {
+                "success": success,
+                "type": "expression_check",
+                "expression": expr,
+                "imports": imports or [],
+                "messages": _serialize_errors(errors, sanitize_paths=True),
+                "statistics": {
+                    "total_errors": error_count,
+                    "total_warnings": warning_count,
+                    "total_info": info_count,
+                },
+            }
+            return _json(result)
+
+        # Case 2: Check a specific file
+        if file:
+            # Guard against path traversal
+            resolved_file = (project_path / file).resolve()
+            if not resolved_file.is_relative_to(project_path.resolve()):
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "PATH_TRAVERSAL",
+                        "message": f"File path '{file}' resolves outside the project directory",
+                    }
+                )
+
+            project_context = ProjectContext(project_path, console=console)
+            file_path = project_context.resolve_file_path(file)
+
+            if not file_path:
+                suggestions = project_context.suggest_file_path(file)
+                result = {
+                    "success": False,
+                    "error_code": "FILE_NOT_FOUND",
+                    "message": f"File '{file}' not found in project",
+                    "suggestions": suggestions if suggestions else None,
+                    "hint": f"Did you mean one of: {', '.join(suggestions[:3])}?"
+                    if suggestions
+                    else "Check the file path and try again.",
+                }
+                return _json(result)
+
+            success, errors = check_file(
+                file_path=file_path,
+                project_path=project_path,
+                console=console,
+            )
+
+            error_count = sum(1 for e in errors if e.severity == "error")
+            warning_count = sum(1 for e in errors if e.severity == "warning")
+            info_count = sum(1 for e in errors if e.severity == "info")
+
+            try:
+                display_path = file_path.relative_to(project_path)
+            except ValueError:
+                display_path = file
+
+            result = {
+                "success": success,
+                "type": "file_check",
+                "file_path": str(display_path),
+                "messages": _serialize_errors(errors),
+                "statistics": {
+                    "total_errors": error_count,
+                    "total_warnings": warning_count,
+                    "total_info": info_count,
+                    "files_checked": 1,
+                },
+            }
+            return _json(result)
+
+        # Case 3: Check entire project
+        success, errors = check_project(
+            project_path=project_path,
+            check_all_files=check_all,
+            console=console,
+        )
+
+        error_count = sum(1 for e in errors if e.severity == "error")
+        warning_count = sum(1 for e in errors if e.severity == "warning")
+        info_count = sum(1 for e in errors if e.severity == "info")
+
+        files_with_errors = set(e.file_name for e in errors if e.file_name != "unknown")
+
+        result = {
+            "success": success,
+            "type": "project_check",
+            "check_all_files": check_all,
+            "messages": _serialize_errors(errors),
+            "statistics": {
+                "total_errors": error_count,
+                "total_warnings": warning_count,
+                "total_info": info_count,
+                "files_with_errors": len(files_with_errors),
+            },
+        }
+        return _json(result)
+
+    except Exception as e:
+        result = {"success": False, "error_code": "EXECUTION_ERROR", "message": str(e)}
+        return _json(result)
+
+
+@mcp.tool()
+@_with_elapsed
+def prove(
+    project: str,
+    theorem: str | None = None,
+    tactics: list[str] | None = None,
+    file: str | None = None,
+    imports: list[str] | None = None,
+    mathlib: bool = False,
+) -> str:
+    """Verify theorem proofs in Lean.
+
+    Use this tool to verify that a theorem statement can be proved with given tactics,
+    or to check that a proof file is valid. This tool verifies proofs non-interactively.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
+    - theorem: Complete theorem statement to prove (e.g., "2 + 2 = 4")
+    - tactics: List of proof tactics to apply in order (e.g., ["intro n", "rfl"])
+    - file: Path to a .lean file containing complete proofs to verify
+    - imports: Additional modules to import (e.g., ["Mathlib.Data.Nat.Basic"])
+    - mathlib: Import Mathlib.Tactic for all standard tactics (simp, ring, omega, linarith, norm_num, decide, aesop, etc.)
+
+    Use either (theorem + tactics) OR (file), not both. When using theorem + tactics,
+    the tool constructs and verifies the proof. When using file, it verifies existing proofs.
+
+    Returns JSON with 'success' boolean. If proof fails, 'messages' array contains objects with:
+    - file: Path to the file (or "<inline>" for inline proofs)
+    - line/column: Location of the issue
+    - severity: "error" or "warning"
+    - message: Description of why the proof failed
+    - suggestion: Hint about what tactic might work (when available)
+
+    Examples:
+    - Simple equality: prove(project="/home/user/lean/myproject", theorem="2 + 2 = 4", tactics=["rfl"])
+    - Basic proof: prove(project="/home/user/lean/myproject", theorem="n + 0 = n", tactics=["omega"])
+    - With mathlib: prove(project="/home/user/lean/myproject", theorem="x > 0", tactics=["use 1", "simp"], mathlib=True)
+    - Check proof file: prove(project="/home/user/lean/myproject", file="MyTheorems.lean")
+    """
+    try:
+        from rich.console import Console
+
+        from leanback.prove import verify_proof
+
+        project_path = _resolve_project(project)
+        if not project_path:
+            return _project_error(project)
+
+        console = Console(stderr=True)
+
+        # Determine imports
+        resolved_imports = imports or []
+        if mathlib:
+            resolved_imports = ["Mathlib.Tactic", *resolved_imports]
+
+        # Reject conflicting inputs
+        if file and theorem:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "CONFLICTING_INPUTS",
+                    "message": "Cannot specify both file and theorem. Use one or the other.",
+                }
+            )
+
+        if file and (imports or mathlib):
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "CONFLICTING_INPUTS",
+                    "message": "Cannot use imports or mathlib with file — the file must contain its own imports.",
+                }
+            )
+
+        # Mode 1: Verify a proof file
+        if file:
+            proof_file = (project_path / file).resolve()
+            if not proof_file.is_relative_to(project_path.resolve()):
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "PATH_TRAVERSAL",
+                        "message": f"File path '{file}' resolves outside the project directory",
+                    }
+                )
+            if not proof_file.exists():
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "FILE_NOT_FOUND",
+                        "message": f"Proof file '{file}' not found in project",
+                    }
+                )
+
+            success, errors = verify_proof(
+                theorem="",
+                proof_file=str(proof_file),
+                imports=resolved_imports if resolved_imports else None,
+                project_path=project_path,
+                console=console,
+            )
+
+            return _json(
+                {
+                    "success": success,
+                    "type": "file_verification",
+                    "proof_file": file,
+                    "messages": _serialize_errors(errors) if errors else [],
+                }
+            )
+
+        # Mode 2: Verify theorem + tactics
+        elif theorem:
+            if tactics is None:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "MISSING_TACTICS",
+                        "message": 'No tactics provided. Use tactics=["rfl"], tactics=["simp"], etc.',
+                    }
+                )
+
+            if len(tactics) == 0:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "EMPTY_TACTICS",
+                        "message": 'Empty tactics list. Provide at least one tactic (e.g., ["rfl"], ["simp"], ["sorry"])',
+                    }
+                )
+
+            success, errors = verify_proof(
+                theorem=theorem,
+                tactics=tactics,
+                imports=resolved_imports,
+                project_path=project_path,
+                console=console,
+            )
+
+            # Detect sorry usage — sorry is not a real proof
+            sorry_used = any(
+                "declaration uses 'sorry'" in e.message
+                for e in errors
+                if e.severity == "warning"
+            )
+            if sorry_used:
+                success = False
+
+            result = {
+                "success": success,
+                "type": "theorem_verification",
+                "theorem": theorem,
+                "tactics": tactics or [],
+                "imports": resolved_imports,
+                "messages": _serialize_errors(errors, sanitize_paths=True)
+                if errors
+                else [],
+            }
+            if sorry_used:
+                result["sorry_used"] = True
+                result["warning"] = (
+                    "Proof uses 'sorry' — this is a placeholder, not a valid proof"
+                )
+            return _json(result)
+
+        else:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "NO_THEOREM_OR_FILE",
+                    "message": "Must provide either theorem (with optional tactics) or file parameter",
+                }
+            )
+
+    except Exception as e:
+        return _json(
+            {"success": False, "error_code": "EXECUTION_ERROR", "message": str(e)}
+        )
+
+
+@mcp.tool()
+@_with_elapsed
+def goals(
+    project: str,
+    theorem: str,
+    tactics: list[str] | None = None,
+    imports: list[str] | None = None,
+    mathlib: bool = False,
+) -> str:
+    """Inspect the proof state during proof construction.
+
+    Use this tool to see what goals remain after applying tactics to a theorem.
+    This is for proof exploration — to see the current state, not to verify completeness.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
+    - theorem: Theorem statement to prove (e.g., "2 + 2 = 4", "∀ n : Nat, n + 0 = n")
+    - tactics: List of tactics applied so far (e.g., ["intro n"]). Omit or pass [] to see the initial goal.
+    - imports: Additional modules to import (e.g., ["Mathlib.Data.Nat.Basic"])
+    - mathlib: Import Mathlib.Tactic for standard tactics (simp, ring, omega, linarith, norm_num, decide, aesop, etc.)
+
+    Returns JSON with:
+    - success: Whether the tool ran without internal errors
+    - status: "incomplete" (goals remain), "complete" (proof done), or "error" (tactic/setup failure)
+    - tactics_applied: Number of successfully applied tactics (0 when showing initial goal)
+    - goals: List of remaining goal strings (each contains hypotheses and ⊢ conclusion)
+
+    When a tactic fails, the response includes:
+    - failed_tactic: {"index": 0-based, "tactic": "...", "error": "..."}
+    - goals: May contain remaining goals if Lean provides them
+    - messages: Raw error details
+
+    To see the goal state before a failed tactic, call goals() again with tactics[:index].
+
+    Workflow:
+    1. See initial goal: goals(project=..., theorem="∀ n, n + 0 = n")
+    2. Apply tactics: goals(project=..., theorem="∀ n, n + 0 = n", tactics=["intro n"])
+    3. If tactic fails at index i, inspect: goals(project=..., theorem=..., tactics=original[:i])
+    4. When complete, verify with prove()
+
+    Examples:
+    - Initial goal: goals(project="/home/user/lean/myproject", theorem="∀ n : Nat, n + 0 = n")
+    - After intro: goals(project="/home/user/lean/myproject", theorem="∀ n : Nat, n + 0 = n", tactics=["intro n"])
+    - Multiple tactics: goals(project="/home/user/lean/myproject", theorem="True ∧ True", tactics=["constructor"], mathlib=True)
+    """
+    try:
+        from rich.console import Console
+
+        from leanback.goals import extract_goals
+
+        project_path = _resolve_project(project)
+        if not project_path:
+            return _project_error(project)
+
+        if not theorem or not theorem.strip():
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "NO_THEOREM",
+                    "message": "Theorem statement is required.",
+                }
+            )
+
+        console = Console(stderr=True)
+
+        # Resolve imports
+        resolved_imports = imports or []
+        if mathlib:
+            resolved_imports = ["Mathlib.Tactic", *resolved_imports]
+
+        result = extract_goals(
+            theorem=theorem,
+            tactics=tactics,
+            imports=resolved_imports,
+            project_path=project_path,
+            console=console,
+        )
+
+        return _json(result)
+
+    except Exception as e:
+        return _json(
+            {"success": False, "error_code": "EXECUTION_ERROR", "message": str(e)}
+        )
+
+
+@mcp.tool()
+@_with_elapsed
+def eval(
+    project: str,
+    code: str | None = None,
+    file: str | None = None,
+    imports: list[str] | None = None,
+    mathlib: bool = False,
+) -> str:
+    """Execute Lean expressions and see their results.
+
+    Use this tool to evaluate Lean code, check types, test functions, or run examples.
+    The code is executed in the context of the specified project.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (e.g., "/home/user/lean/myproject")
+    - code: Lean code to execute (e.g., "#eval 2 + 2", "#check Nat.add", "def f := 5")
+    - file: Path to a .lean file to execute instead of inline code
+    - imports: Additional modules to import (e.g., ["Mathlib.Data.Finset.Basic"])
+    - mathlib: Import Mathlib.Tactic for all standard tactics (simp, ring, omega, linarith, norm_num, decide, aesop, etc.)
+
+    Use either 'code' OR 'file', not both. The tool can handle multi-line code.
+
+    Returns JSON with 'success' boolean and 'messages' array containing:
+    - Actual errors (severity: "error")
+    - Warnings (severity: "warning")
+    - Output from #eval and #check (severity: "info")
+    Each entry has file, line, column, severity, and message fields.
+
+    Examples:
+    - Evaluate arithmetic: eval(project="/home/user/lean/myproject", code="#eval 2 + 2")
+    - Check type: eval(project="/home/user/lean/myproject", code="#check List.map")
+    - Define and test: eval(project="/home/user/lean/myproject", code="def double (n : Nat) := n * 2\\n#eval double 21")
+    - With mathlib: eval(project="/home/user/lean/myproject", code="#eval Nat.gcd 12 18", mathlib=True)
+    - With imports: eval(project="/home/user/lean/myproject", code="#check @Finset.sum", imports=["Mathlib.Algebra.BigOperators.Group.Finset"])
+    - Execute from file: eval(project="/home/user/lean/myproject", file="examples.lean")
+    """
+    try:
+        from rich.console import Console
+
+        from leanback.check import check_lean_expr
+
+        # Validate parameters
+        if (code is None or (isinstance(code, str) and not code.strip())) and not file:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "NO_CODE_PROVIDED",
+                    "message": "No code provided. Use 'code' parameter or 'file' parameter",
+                }
+            )
+
+        if code is not None and file:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "CONFLICTING_INPUTS",
+                    "message": "Cannot specify both code and file",
+                }
+            )
+
+        project_path = _resolve_project(project)
+        if not project_path:
+            return _project_error(project)
+
+        console = Console(stderr=True)
+
+        # Get the code to execute
+        if file:
+            file_path = (project_path / file).resolve()
+            if not file_path.is_relative_to(project_path.resolve()):
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "PATH_TRAVERSAL",
+                        "message": f"File path '{file}' resolves outside the project directory",
+                    }
+                )
+            if not file_path.exists():
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "FILE_NOT_FOUND",
+                        "message": f"File '{file}' not found in project",
+                    }
+                )
+            try:
+                with open(file_path) as f:
+                    code_to_execute = f.read()
+            except Exception as e:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "FILE_READ_ERROR",
+                        "message": f"Failed to read file '{file}': {e!s}",
+                    }
+                )
+        else:
+            code_to_execute = code
+
+        # Set up imports — merge mathlib defaults with user-provided imports
+        resolved_imports = list(imports or [])
+        if mathlib:
+            if "Mathlib.Tactic" not in resolved_imports:
+                resolved_imports.insert(0, "Mathlib.Tactic")
+
+        success, errors = check_lean_expr(
+            expr=code_to_execute,
+            imports=resolved_imports,
+            project_path=project_path,
+            console=console,
+        )
+
+        return _json(
+            {
+                "success": success,
+                "type": "code_execution",
+                "code": code_to_execute,
+                "imports": resolved_imports,
+                "messages": _serialize_errors(errors, sanitize_paths=True),
+            }
+        )
+
+    except Exception as e:
+        return _json(
+            {"success": False, "error_code": "EXECUTION_ERROR", "message": str(e)}
+        )
+
+
+@mcp.tool()
+@_with_elapsed
+def search(
+    project: str,
+    pattern: str | None = None,
+    batch: str | None = None,
+    max_results: int = 15,
+    filter_namespace: str | None = None,
+    include_internal: bool = False,
+) -> str:
+    """Find Lean declarations in Mathlib by pattern matching.
+
+    Use this tool to search for theorems, lemmas, definitions, and other declarations
+    in the project's Mathlib. Searches use Python regex patterns on declaration names.
+
+    Parameters:
+    - project: Absolute path to the Lean project directory (must have Mathlib)
+    - pattern: Single search pattern (regex or text) to find matching declarations
+    - batch: Comma-separated patterns for multiple searches (e.g., "add_comm,mul_comm")
+    - max_results: Maximum results to return per pattern (default: 15)
+    - filter_namespace: Only show results from this namespace (e.g., "List", "Nat")
+    - include_internal: Include internal/private declarations (default: false)
+
+    Use either 'pattern' OR 'batch', not both. Patterns can be:
+    - Exact names: "Nat.add_comm"
+    - Substrings: "comm" (finds anything containing 'comm')
+    - Regex: "theorem.*add.*comm"
+
+    Returns JSON with results. Each result has: name, type_signature, module, suggested_import.
+
+    Examples:
+    - Find theorem: search(project="/home/user/lean/myproject", pattern="Nat.add_comm")
+    - Find by substring: search(project="/home/user/lean/myproject", pattern="comm")
+    - Filtered: search(project="/home/user/lean/myproject", pattern="reverse", filter_namespace="List")
+    - Batch: search(project="/home/user/lean/myproject", batch="add_assoc,mul_assoc,add_comm")
+    """
+    try:
+        from leanback.mathlib_search import (
+            SearchError,
+            batch_search_declarations,
+            search_mathlib_declarations,
+        )
+
+        # Validate parameters
+        if pattern and batch:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "CONFLICTING_INPUTS",
+                    "message": "Use either 'pattern' or 'batch', not both",
+                }
+            )
+        if not pattern and not batch:
+            return _json(
+                {
+                    "success": False,
+                    "error_code": "MISSING_PATTERN",
+                    "message": "Either 'pattern' or 'batch' is required",
+                }
+            )
+
+        project_path = _resolve_project(project)
+        if not project_path:
+            return _project_error(project)
+
+        search_params = {
+            "timeout": 30,
+            "filter_namespace": filter_namespace,
+            "exclude_internal": not include_internal,
+            "max_results": max_results,
+            "use_minimal_import": False,
+            "backend": "auto",
+        }
+
+        if batch is not None:
+            if not batch.strip():
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "INVALID_PATTERN",
+                        "message": "Empty batch pattern list",
+                    }
+                )
+
+            patterns = [p.strip() for p in batch.split(",") if p.strip()]
+            if not patterns:
+                return _json(
+                    {
+                        "success": False,
+                        "error_code": "INVALID_PATTERN",
+                        "message": "No valid patterns in batch list",
+                    }
+                )
+
+            results = batch_search_declarations(patterns, project_path, **search_params)
+            return _json(results)
+        else:
+            try:
+                search_results, total_found = search_mathlib_declarations(
+                    pattern, project_path, **search_params
+                )
+
+                serializable_results = []
+                for r in search_results:
+                    if hasattr(r, "name"):
+                        serializable_results.append(
+                            {
+                                "name": r.name,
+                                "type_signature": r.type_signature,
+                                "module": r.module,
+                                "suggested_import": r.suggested_import,
+                            }
+                        )
+                    else:
+                        serializable_results.append(r)
+
+                metadata = {
+                    "total_found": len(serializable_results),
+                    "project_path": str(project_path),
+                }
+                if total_found > len(serializable_results):
+                    metadata["total_matched"] = total_found
+                result = {
+                    "success": True,
+                    "pattern": pattern,
+                    "results": serializable_results,
+                    "metadata": metadata,
+                }
+                if len(serializable_results) == 0:
+                    if filter_namespace and total_found > 0:
+                        result["note"] = (
+                            f"No matches in namespace '{filter_namespace}'. "
+                            f"{total_found} matches exist without the namespace filter. "
+                            f"Try searching without filter_namespace."
+                        )
+                    else:
+                        result["note"] = (
+                            "No matches found. This search covers Mathlib declarations only, "
+                            "not core Lean (e.g., Nat.add_comm, List.map). "
+                            "Try a broader pattern or check the declaration name."
+                        )
+                return _json(result)
+            except SearchError as e:
+                return _json({"success": False, "pattern": pattern, **e.to_dict()})
+
+    except SearchError as e:
+        return _json({"success": False, **e.to_dict()})
+    except Exception as e:
+        return _json(
+            {
+                "success": False,
+                "message": str(e),
+                "error_code": "UNEXPECTED_ERROR",
+            }
+        )
+
+
+def main():
+    """Main entry point for the MCP server."""
+    parser = argparse.ArgumentParser(description="LeanBack MCP Server")
+    parser.add_argument(
+        "--transport",
+        type=str,
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="Transport type to use (default: stdio)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=3000,
+        help="Port to listen on (for sse/streamable-http transport)",
+    )
+
+    args = parser.parse_args()
+
+    logger.info(f"Starting LeanBack MCP server with {args.transport} transport")
+
+    if args.transport == "stdio":
+        mcp.run()
+    elif args.transport == "sse":
+        mcp.run(transport="sse", port=args.port)
+    elif args.transport == "streamable-http":
+        mcp.run(transport="streamable-http", port=args.port)
+
+
+if __name__ == "__main__":
+    main()