py-commander-mcp 0.1.0__tar.gz

py_commander_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: py-commander-mcp
+Version: 0.1.0
+Summary: MCP Server for filesystem operations — read, write, edit, search, manage files and directories
+Author-email: Yohann <yohann@example.com>
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pymupdf>=1.25.0
+Requires-Dist: python-docx>=1.1.0
+Description-Content-Type: text/markdown
+
+# py-commander-mcp
+
+MCP Server for filesystem operations — read, write, edit, search, and manage files and directories.
+
+Built as a Python port of the key features from Desktop Commander.
+
+## Features
+
+- **Read files**: text (with offset/length pagination), PDF, Excel, DOCX, images (base64)
+- **Write files**: text, DOCX (from markdown), Excel (from JSON 2D arrays)
+- **Edit files**: surgical find/replace with `edit_block`
+- **Directory ops**: list (recursive with depth), create, move/rename
+- **File metadata**: size, dates, line counts
+- **Search**: by file name (glob/regex) or file content with context lines
+
+## Usage
+
+```json
+{
+  "mcpServers": {
+    "py-commander-mcp": {
+      "command": "uvx",
+      "args": ["py-commander-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read files (text, PDF, Excel, DOCX, images) |
+| `read_multiple_files` | Read multiple files at once |
+| `write_file` | Write/create/append files |
+| `edit_block` | Surgical find/replace edits |
+| `create_directory` | Create directories |
+| `list_directory` | List directory contents with depth |
+| `move_file` | Move/rename files and directories |
+| `get_file_info` | File metadata |
+| `start_search` | Search files by name or content |
+| `get_more_search_results` | Paginate search results |
+| `stop_search` | Stop and free a search session |
+| `list_searches` | List active searches |

py_commander_mcp-0.1.0/README.md

@@ -0,0 +1,44 @@
+# py-commander-mcp
+
+MCP Server for filesystem operations — read, write, edit, search, and manage files and directories.
+
+Built as a Python port of the key features from Desktop Commander.
+
+## Features
+
+- **Read files**: text (with offset/length pagination), PDF, Excel, DOCX, images (base64)
+- **Write files**: text, DOCX (from markdown), Excel (from JSON 2D arrays)
+- **Edit files**: surgical find/replace with `edit_block`
+- **Directory ops**: list (recursive with depth), create, move/rename
+- **File metadata**: size, dates, line counts
+- **Search**: by file name (glob/regex) or file content with context lines
+
+## Usage
+
+```json
+{
+  "mcpServers": {
+    "py-commander-mcp": {
+      "command": "uvx",
+      "args": ["py-commander-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read files (text, PDF, Excel, DOCX, images) |
+| `read_multiple_files` | Read multiple files at once |
+| `write_file` | Write/create/append files |
+| `edit_block` | Surgical find/replace edits |
+| `create_directory` | Create directories |
+| `list_directory` | List directory contents with depth |
+| `move_file` | Move/rename files and directories |
+| `get_file_info` | File metadata |
+| `start_search` | Search files by name or content |
+| `get_more_search_results` | Paginate search results |
+| `stop_search` | Stop and free a search session |
+| `list_searches` | List active searches |

py_commander_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "py-commander-mcp"
+version = "0.1.0"
+description = "MCP Server for filesystem operations — read, write, edit, search, manage files and directories"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Yohann", email = "yohann@example.com" },
+]
+
+dependencies = [
+    "mcp[cli]>=1.6.0",
+    "PyMuPDF>=1.25.0",
+    "openpyxl>=3.1.0",
+    "python-docx>=1.1.0",
+    "Pillow>=10.0.0",
+]
+
+[project.scripts]
+py-commander-mcp = "py_commander_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/py_commander_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src"]

py_commander_mcp-0.1.0/src/py_commander_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""py-commander-mcp: filesystem MCP server for file read/write/edit/search operations."""
+
+__version__ = "0.1.0"

py_commander_mcp-0.1.0/src/py_commander_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""Entry point for the ``py-commander-mcp`` MCP server."""
+from .server import main
+
+main()

py_commander_mcp-0.1.0/src/py_commander_mcp/server.py

@@ -0,0 +1,802 @@
+"""py-commander-mcp MCP Server — filesystem operations.
+
+Provides tools for reading, writing, editing, searching, and managing
+files and directories, with support for text, PDF, Excel, DOCX, and images.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import logging
+import os
+import re
+import shutil
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP("py-commander")
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff"}
+TEXT_EXTENSIONS = {
+    ".txt", ".md", ".py", ".js", ".ts", ".jsx", ".tsx", ".json", ".yaml",
+    ".yml", ".toml", ".cfg", ".ini", ".conf", ".csv", ".xml", ".html", ".css",
+    ".sh", ".bash", ".zsh", ".env", ".gitignore", ".dockerfile", ".sql",
+    ".rb", ".go", ".rs", ".java", ".c", ".h", ".cpp", ".hpp", ".swift",
+    ".kt", ".scala", ".clj", ".cljs", ".edn", ".r", ".m", ".mm",
+}
+
+SEARCH_SESSION_TTL = 300  # 5 minutes
+
+# ---------------------------------------------------------------------------
+# In-memory state for search sessions
+# ---------------------------------------------------------------------------
+
+_search_sessions: dict[str, dict] = {}
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+SUFFIX_TO_FORMAT: dict[str, str] = {
+    ".xlsx": "xlsx",
+    ".xls": "xls",
+    ".xlsm": "xlsm",
+    ".pdf": "pdf",
+    ".docx": "docx",
+}
+
+
+def _detect_format(path: Path) -> str | None:
+    """Detect special file format from extension."""
+    return SUFFIX_TO_FORMAT.get(path.suffix.lower())
+
+
+def _is_text_file(path: Path) -> bool:
+    """Check if a file is likely a text file based on extension."""
+    fmt = _detect_format(path)
+    if fmt:
+        return False  # special binary formats
+    if path.suffix.lower() in IMAGE_EXTENSIONS:
+        return False
+    # Default to text for unknown extensions (try reading as text)
+    return True
+
+
+def _is_image_file(path: Path) -> bool:
+    """Check if a file is an image based on extension."""
+    return path.suffix.lower() in IMAGE_EXTENSIONS
+
+
+def _read_text_file(path: Path, offset: int = 0, length: int | None = None) -> dict:
+    """Read a text file with optional offset/length pagination."""
+    total_lines = 0
+    lines = []
+
+    with open(path, "r", encoding="utf-8", errors="replace") as f:
+        if offset < 0:
+            # Read last N lines (tail)
+            all_lines = f.readlines()
+            total_lines = len(all_lines)
+            wanted = abs(offset)
+            lines = all_lines[-wanted:]
+            start_line = total_lines - len(lines)
+        elif offset > 0:
+            all_lines = f.readlines()
+            total_lines = len(all_lines)
+            if offset >= total_lines:
+                lines = []
+                start_line = total_lines
+            else:
+                end = offset + length if length else total_lines
+                lines = all_lines[offset:end]
+                start_line = offset
+        else:
+            if length:
+                all_lines = f.readlines()
+                total_lines = len(all_lines)
+                lines = all_lines[:length]
+                start_line = 0
+            else:
+                content = f.read()
+                total_lines = content.count("\n") + 1
+                return {
+                    "content": content,
+                    "total_lines": total_lines,
+                    "start_line": 0,
+                    "end_line": total_lines - 1,
+                    "is_truncated": False,
+                }
+
+    return {
+        "content": "".join(lines),
+        "total_lines": total_lines,
+        "start_line": start_line,
+        "end_line": start_line + len(lines) - 1,
+        "is_truncated": total_lines > (start_line + len(lines)),
+    }
+
+
+def _read_xlsx(path: Path, sheet: str | None = None, range_str: str | None = None) -> list[list]:
+    """Read an Excel file and return as 2D list."""
+    import openpyxl
+
+    wb = openpyxl.load_workbook(path, read_only=True, data_only=True)
+    try:
+        if sheet and sheet in wb.sheetnames:
+            ws = wb[sheet]
+        elif sheet and sheet.isdigit():
+            idx = int(sheet)
+            ws = wb.worksheets[idx]
+        else:
+            ws = wb.active
+
+        if range_str and ":" in range_str:
+            from openpyxl.utils import range_boundaries
+            min_col, min_row, max_col, max_row = range_boundaries(range_str)
+            data = []
+            for row in ws.iter_rows(min_row=min_row, min_col=min_col,
+                                     max_row=max_row, max_col=max_col,
+                                     values_only=True):
+                data.append([v if v is not None else "" for v in row])
+            return data
+        else:
+            return [[cell.value if cell.value is not None else "" for cell in row] for row in ws.iter_rows(values_only=True)]
+    finally:
+        wb.close()
+
+
+def _read_pdf(path: Path) -> str:
+    """Extract text from a PDF file as markdown."""
+    import fitz  # PyMuPDF
+    doc = fitz.open(path)
+    parts = []
+    for i, page in enumerate(doc):
+        text = page.get_text()
+        parts.append(f"## Page {i + 1}\n\n{text}")
+    doc.close()
+    return "\n\n".join(parts)
+
+
+def _read_docx(path: Path) -> str:
+    """Extract text from a DOCX file."""
+    from docx import Document
+    doc = Document(path)
+    parts = []
+    for para in doc.paragraphs:
+        parts.append(para.text)
+    # Include tables
+    for table in doc.tables:
+        for row in table.rows:
+            cells = [cell.text for cell in row.cells]
+            parts.append(" | ".join(cells))
+    return "\n\n".join(parts)
+
+
+def _read_image_base64(path: Path) -> dict:
+    """Read an image file and return base64 data with MIME type."""
+    from PIL import Image
+    import base64
+
+    img = Image.open(path)
+    mime_map = {
+        "png": "image/png",
+        "jpeg": "image/jpeg",
+        "jpg": "image/jpeg",
+        "gif": "image/gif",
+        "webp": "image/webp",
+        "bmp": "image/bmp",
+    }
+    fmt = img.format.lower() if img.format else "png"
+    mime = mime_map.get(fmt, "image/png")
+
+    buf = io.BytesIO()
+    img.save(buf, format=img.format or "PNG")
+    b64 = base64.b64encode(buf.getvalue()).decode("utf-8")
+
+    return {
+        "mime_type": mime,
+        "data": b64,
+        "width": img.width,
+        "height": img.height,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Search helpers
+# ---------------------------------------------------------------------------
+
+def _run_file_search(base_path: Path, pattern: str, ignore_case: bool = True,
+                     include_hidden: bool = False, max_results: int = 200) -> list[dict]:
+    """Search for files matching a pattern (glob or regex)."""
+    results = []
+    is_regex = any(c in pattern for c in "*?[]{}()+|^$\\")
+    flags = re.IGNORECASE if ignore_case else 0
+
+    try:
+        regex = re.compile(pattern, flags) if is_regex else None
+    except re.error:
+        regex = None
+
+    # Simple glob matching for non-regex patterns without wildcards
+    if not is_regex and "*" not in pattern and "?" not in pattern:
+        # Search by exact filename or substring
+        pat_lower = pattern.lower() if ignore_case else pattern
+        for root, dirs, files in os.walk(base_path):
+            if not include_hidden:
+                dirs[:] = [d for d in dirs if not d.startswith(".")]
+                files = [f for f in files if not f.startswith(".")]
+            for f in files:
+                f_lower = f.lower() if ignore_case else f
+                if pat_lower in f_lower:
+                    results.append({"path": str(Path(root) / f), "type": "file"})
+                    if len(results) >= max_results:
+                        return results
+            for d in dirs:
+                d_lower = d.lower() if ignore_case else d
+                if pat_lower in d_lower:
+                    results.append({"path": str(Path(root) / d), "type": "directory"})
+                    if len(results) >= max_results:
+                        return results
+        return results
+
+    # Glob or regex matching
+    for root, dirs, files in os.walk(base_path):
+        if not include_hidden:
+            dirs[:] = [d for d in dirs if not d.startswith(".")]
+            files = [f for f in files if not f.startswith(".")]
+
+        for f in files:
+            if regex and regex.search(f):
+                results.append({"path": str(Path(root) / f), "type": "file"})
+            elif not regex:
+                import fnmatch
+                if fnmatch.fnmatch(f, pattern):
+                    results.append({"path": str(Path(root) / f), "type": "file"})
+            if len(results) >= max_results:
+                return results
+
+        for d in dirs:
+            if regex and regex.search(d):
+                results.append({"path": str(Path(root) / d), "type": "directory"})
+            elif not regex:
+                import fnmatch
+                if fnmatch.fnmatch(d, pattern):
+                    results.append({"path": str(Path(root) / d), "type": "directory"})
+            if len(results) >= max_results:
+                return results
+
+    return results
+
+
+def _run_content_search(base_path: Path, pattern: str, file_pattern: str | None = None,
+                        ignore_case: bool = True, context_lines: int = 5,
+                        max_results: int = 200) -> list[dict]:
+    """Search for text content inside files."""
+    results = []
+    flags = re.IGNORECASE | re.DOTALL if ignore_case else re.DOTALL
+
+    try:
+        regex = re.compile(pattern, flags)
+    except re.error:
+        return results
+
+    file_regex = None
+    if file_pattern:
+        try:
+            file_regex = re.compile(file_pattern, re.IGNORECASE)
+        except re.error:
+            pass
+
+    for root, dirs, files in os.walk(base_path):
+        dirs[:] = [d for d in dirs if not d.startswith(".")]
+        files = [f for f in files if not f.startswith(".")]
+
+        for fname in files:
+            if file_regex and not file_regex.search(fname):
+                continue
+
+            fpath = Path(root) / fname
+            # Skip binary-ish files
+            if fpath.suffix.lower() in IMAGE_EXTENSIONS:
+                continue
+            if _detect_format(fpath):
+                continue
+
+            try:
+                with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                    text = f.read()
+            except Exception:
+                continue
+
+            matches = list(regex.finditer(text))
+            for m in matches[:10]:  # limit matches per file
+                start = max(0, m.start() - context_lines * 200)
+                end = min(len(text), m.end() + context_lines * 200)
+                snippet = text[start:end]
+                lines_before = snippet[:m.start() - start].count("\n")
+                total_context = snippet.count("\n")
+
+                results.append({
+                    "path": str(fpath),
+                    "line": text[:m.start()].count("\n") + 1,
+                    "content": m.group(),
+                    "context": snippet,
+                    "context_lines_before": lines_before,
+                    "context_lines_total": total_context,
+                })
+
+                if len(results) >= max_results:
+                    return results
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# MCP Tools
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def read_file(
+    path: str,
+    offset: int = 0,
+    length: int | None = None,
+    sheet: str | None = None,
+    range: str | None = None,
+) -> dict:
+    """Read contents from files and URLs.
+
+    Supports text files (with offset/length pagination), PDF (extracted as
+    markdown), Excel (as 2D arrays), DOCX (as text), and images (as base64).
+
+    Args:
+        path: Absolute path to the file.
+        offset: Start line (0-based). Negative = read last N lines (tail).
+        length: Max lines to read (default: read all).
+        sheet: Sheet name or index (Excel only).
+        range: Cell range in FROM:TO format (Excel only, e.g. "A1:D100").
+    """
+    fpath = Path(path).resolve()
+    if not fpath.exists():
+        return {"error": f"File not found: {path}"}
+
+    fmt = _detect_format(fpath)
+
+    if fmt == "pdf":
+        text = _read_pdf(fpath)
+        return {"content": text, "format": "markdown"}
+
+    if fmt in ("xlsx", "xls", "xlsm"):
+        data = _read_xlsx(fpath, sheet=sheet, range_str=range)
+        return {"data": data, "format": "json"}
+
+    if fmt == "docx":
+        text = _read_docx(fpath)
+        return {"content": text, "format": "markdown"}
+
+    if _is_image_file(fpath):
+        img_data = _read_image_base64(fpath)
+        return img_data  # mime_type + data + width + height
+
+    # Text file (default)
+    result = _read_text_file(fpath, offset=offset, length=length)
+    return result
+
+
+@mcp.tool()
+def read_multiple_files(paths: list[str]) -> dict:
+    """Read the contents of multiple files simultaneously.
+
+    Each file's content is returned with its path as a reference.
+    Failed reads for individual files won't stop the entire operation.
+
+    Args:
+        paths: List of absolute file paths.
+    """
+    results = {}
+    for p in paths:
+        try:
+            result = read_file(path=p)
+            results[p] = result
+        except Exception as e:
+            results[p] = {"error": str(e)}
+    return {"files": results}
+
+
+@mcp.tool()
+def write_file(path: str, content: str, mode: str = "rewrite") -> dict:
+    """Write content to a file.
+
+    For .docx extension, creates a styled DOCX from markdown content.
+    For .xlsx/.xls extensions, content should be a JSON 2D array or
+    dict of sheet names to 2D arrays.
+
+    Args:
+        path: Absolute path to the file.
+        content: File content (text, or JSON for Excel).
+        mode: ``"rewrite"`` (overwrite) or ``"append"`` (append to existing).
+    """
+    fpath = Path(path).resolve()
+    fmt = _detect_format(fpath)
+
+    if fmt == "docx":
+        from docx import Document
+        from docx.shared import Pt, Inches
+        import re as _re
+
+        doc = Document()
+        for line in content.split("\n"):
+            line = line.rstrip()
+            if line.startswith("# "):
+                doc.add_heading(line[2:], level=1)
+            elif line.startswith("## "):
+                doc.add_heading(line[2:], level=2)
+            elif line.startswith("### "):
+                doc.add_heading(line[3:], level=3)
+            elif line.strip() == "":
+                doc.add_paragraph("")
+            else:
+                doc.add_paragraph(line)
+        doc.save(fpath)
+        return {"message": f"DOCX written ({len(content)} chars)", "path": str(fpath)}
+
+    if fmt in ("xlsx", "xls"):
+        import openpyxl
+
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError:
+            return {"error": "Content must be valid JSON for Excel files"}
+
+        wb = openpyxl.Workbook()
+        if isinstance(data, dict):
+            for sheet_name, rows in data.items():
+                if sheet_name == list(data.keys())[0]:
+                    ws = wb.active
+                    ws.title = sheet_name
+                else:
+                    ws = wb.create_sheet(title=sheet_name)
+                for row in rows:
+                    ws.append(row)
+        elif isinstance(data, list):
+            ws = wb.active
+            for row in data:
+                ws.append(row)
+        else:
+            return {"error": "Content must be a 2D array or dict of sheets"}
+
+        wb.save(fpath)
+        return {"message": f"Excel written ({len(content)} chars)", "path": str(fpath)}
+
+    # Text file
+    write_mode = "a" if mode == "append" else "w"
+    encoding = "utf-8"
+
+    fpath.parent.mkdir(parents=True, exist_ok=True)
+    with open(fpath, write_mode, encoding=encoding) as f:
+        f.write(content)
+
+    return {"message": f"File written ({len(content)} chars)", "path": str(fpath)}
+
+
+@mcp.tool()
+def edit_block(
+    file_path: str,
+    old_string: str,
+    new_string: str,
+    expected_replacements: int = 1,
+) -> dict:
+    """Apply surgical edits to text files.
+
+    Replaces occurrences of ``old_string`` with ``new_string``.
+    By default replaces exactly 1 occurrence (use ``expected_replacements``
+    for multiple).
+
+    Args:
+        file_path: Absolute path to the file to edit.
+        old_string: Text to search for.
+        new_string: Replacement text.
+        expected_replacements: Number of replacements expected (default: 1).
+    """
+    fpath = Path(file_path).resolve()
+    if not fpath.exists():
+        return {"error": f"File not found: {file_path}"}
+
+    with open(fpath, "r", encoding="utf-8") as f:
+        text = f.read()
+
+    count = text.count(old_string)
+    if count == 0:
+        # Try approximate matching
+        return {
+            "error": f"old_string not found in file. Found {count} occurrences.",
+            "hint": "Check exact whitespace and indentation in old_string.",
+        }
+
+    if count < expected_replacements:
+        return {
+            "error": f"Found {count} occurrence(s), expected {expected_replacements}.",
+        }
+
+    text = text.replace(old_string, new_string, expected_replacements)
+
+    with open(fpath, "w", encoding="utf-8") as f:
+        f.write(text)
+
+    return {
+        "message": f"Applied {expected_replacements} replacement(s)",
+        "path": str(fpath),
+    }
+
+
+@mcp.tool()
+def create_directory(path: str) -> dict:
+    """Create a new directory or ensure it exists.
+
+    Creates parent directories if needed. Succeeds silently if the
+    directory already exists.
+
+    Args:
+        path: Absolute path of the directory to create.
+    """
+    dpath = Path(path).resolve()
+    dpath.mkdir(parents=True, exist_ok=True)
+    return {"message": f"Directory ready: {dpath}"}
+
+
+@mcp.tool()
+def list_directory(path: str, depth: int = 2) -> list[dict]:
+    """Get a detailed listing of files and directories.
+
+    Results distinguish between files and directories with [FILE] and [DIR]
+    prefixes.
+
+    Args:
+        path: Absolute path to list.
+        depth: How deep to recurse (default: 2, minimum: 1).
+    """
+    base = Path(path).resolve()
+    if not base.exists():
+        return [{"type": "error", "message": f"Path not found: {path}"}]
+    if not base.is_dir():
+        return [{"type": "error", "message": f"Not a directory: {path}"}]
+
+    depth = max(1, depth)
+    results = []
+    _list_recursive(base, base, depth, results)
+    return results
+
+
+def _list_recursive(base: Path, current: Path, max_depth: int, results: list):
+    if not current.is_dir():
+        return
+    try:
+        entries = sorted(current.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+    except PermissionError:
+        results.append({
+            "type": "denied",
+            "path": str(current.relative_to(base)) if current != base else ".",
+        })
+        return
+
+    for entry in entries:
+        rel = str(entry.relative_to(base)) if entry != base else "."
+        if entry.is_dir():
+            results.append({"type": "dir", "path": rel})
+            if max_depth > 1:
+                _list_recursive(base, entry, max_depth - 1, results)
+        else:
+            results.append({"type": "file", "path": rel})
+
+
+@mcp.tool()
+def move_file(source: str, destination: str) -> dict:
+    """Move or rename files and directories.
+
+    Args:
+        source: Current absolute path.
+        destination: New absolute path.
+    """
+    src = Path(source).resolve()
+    dst = Path(destination).resolve()
+
+    if not src.exists():
+        return {"error": f"Source not found: {source}"}
+    if dst.exists():
+        return {"error": f"Destination already exists: {destination}"}
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(src), str(dst))
+    return {"message": f"Moved to {destination}"}
+
+
+@mcp.tool()
+def get_file_info(path: str) -> dict:
+    """Retrieve detailed metadata about a file or directory.
+
+    Returns size, creation time, last modified time, type, and for text
+    files: line count and last line number.
+
+    Args:
+        path: Absolute path to the file or directory.
+    """
+    fpath = Path(path).resolve()
+    if not fpath.exists():
+        return {"error": f"Path not found: {path}"}
+
+    stat = fpath.stat()
+    info = {
+        "path": str(fpath),
+        "size": stat.st_size,
+        "created": stat.st_ctime,
+        "modified": stat.st_mtime,
+        "type": "directory" if fpath.is_dir() else "file",
+    }
+
+    if fpath.is_file():
+        info["extension"] = fpath.suffix
+        # Try to count lines for text files
+        try:
+            if _is_text_file(fpath):
+                with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                    line_count = sum(1 for _ in f)
+                info["line_count"] = line_count
+                info["last_line"] = line_count - 1  # zero-indexed
+        except Exception:
+            pass
+
+    return info
+
+
+@mcp.tool()
+def start_search(
+    path: str,
+    pattern: str,
+    search_type: str = "files",
+    file_pattern: str | None = None,
+    ignore_case: bool = True,
+    max_results: int = 200,
+    include_hidden: bool = False,
+    context_lines: int = 5,
+    literal_search: bool = False,
+) -> dict:
+    """Start a search for files by name or content.
+
+    Args:
+        path: Directory to search in.
+        pattern: Search pattern (text or regex).
+        search_type: ``"files"`` (by name) or ``"content"`` (inside files).
+        file_pattern: Filter by file name pattern (content search only).
+        ignore_case: Case-insensitive search (default: true).
+        max_results: Maximum results to return (default: 200).
+        include_hidden: Include hidden files (default: false).
+        context_lines: Context lines for content search (default: 5).
+        literal_search: Treat pattern as literal string, not regex (default: false).
+    """
+    base_path = Path(path).resolve()
+    if not base_path.exists():
+        return {"error": f"Path not found: {path}"}
+
+    if literal_search:
+        pattern = re.escape(pattern)
+
+    session_id = str(uuid.uuid4())
+
+    if search_type == "content":
+        results = _run_content_search(
+            base_path, pattern, file_pattern=file_pattern,
+            ignore_case=ignore_case, context_lines=context_lines,
+            max_results=max_results,
+        )
+    else:
+        results = _run_file_search(
+            base_path, pattern, ignore_case=ignore_case,
+            include_hidden=include_hidden, max_results=max_results,
+        )
+
+    session = {
+        "id": session_id,
+        "results": results,
+        "pattern": pattern,
+        "search_type": search_type,
+        "created_at": time.time(),
+        "total": len(results),
+    }
+    _search_sessions[session_id] = session
+
+    return {
+        "session_id": session_id,
+        "results": results[:50],
+        "total": len(results),
+        "truncated": len(results) > 50,
+    }
+
+
+@mcp.tool()
+def get_more_search_results(
+    session_id: str,
+    offset: int = 0,
+    length: int = 100,
+) -> dict:
+    """Get more results from an active search.
+
+    Args:
+        session_id: Session ID from ``start_search``.
+        offset: Start index (0-based). Negative = last N results.
+        length: Max results to return (default: 100).
+    """
+    session = _search_sessions.get(session_id)
+    if not session:
+        return {"error": f"Search session not found: {session_id}"}
+
+    results = session["results"]
+
+    if offset < 0:
+        wanted = abs(offset)
+        chunk = results[-wanted:]
+        start = len(results) - len(chunk)
+    else:
+        end = offset + length if length else len(results)
+        chunk = results[offset:end]
+        start = offset
+
+    return {
+        "session_id": session_id,
+        "results": chunk,
+        "total": len(results),
+        "start": start,
+        "end": start + len(chunk),
+    }
+
+
+@mcp.tool()
+def stop_search(session_id: str) -> dict:
+    """Stop an active search and free its memory.
+
+    Args:
+        session_id: Session ID from ``start_search``.
+    """
+    if session_id in _search_sessions:
+        del _search_sessions[session_id]
+        return {"message": f"Search session {session_id} stopped and freed."}
+    return {"error": f"Search session not found: {session_id}"}
+
+
+@mcp.tool()
+def list_searches() -> dict:
+    """List all active search sessions."""
+    return {
+        "sessions": [
+            {
+                "id": sid,
+                "pattern": s["pattern"],
+                "search_type": s["search_type"],
+                "total": s["total"],
+                "age_seconds": time.time() - s["created_at"],
+            }
+            for sid, s in _search_sessions.items()
+        ]
+    }
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    """Run the py-commander-mcp MCP server."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()