mcp-files-context 0.2.0__tar.gz

mcp_files_context-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 convert.guru
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_files_context-0.2.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: mcp-files-context
+Version: 0.2.0
+Summary: MCP tools for text files inside a configured local workspace
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: fastmcp>=4.1.4,<5
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/jayanth-mkv/agent-mcp-registry
+Project-URL: Documentation, https://github.com/jayanth-mkv/agent-mcp-registry/tree/main/mcp-files
+Project-URL: Repository, https://github.com/jayanth-mkv/agent-mcp-registry
+Project-URL: Issues, https://github.com/jayanth-mkv/agent-mcp-registry/issues
+Description-Content-Type: text/markdown
+
+# File Server MCP
+
+An MCP server with 14 tools for managing UTF-8 text files within a configured workspace. No API key or external service is required.
+
+## Install a published release
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/). The distribution is `mcp-files-context`; the command is `mcp-files`:
+
+```bash
+uvx --python 3.13 --from mcp-files-context==0.2.0 mcp-files --workspace ./workspace
+```
+
+Published versions are listed on [PyPI](https://pypi.org/project/mcp-files-context/). If the version is not available yet, use the GitHub command below. Publishing is managed through [GitHub Actions](https://github.com/jayanth-mkv/agent-mcp-registry/blob/main/docs/publishing.md).
+
+## Run from GitHub without cloning
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. uv downloads the selected package and manages Python 3.13 and its dependencies:
+
+```bash
+uvx --python 3.13 --from "git+https://github.com/jayanth-mkv/agent-mcp-registry.git@main#subdirectory=mcp-files" mcp-files --workspace ./workspace
+```
+
+Only this MCP and its runtime dependencies are installed. uv fetches the repository internally; you do not need a local checkout. To pin the source, replace `main` with a release tag or full commit SHA.
+
+## Install from source
+
+From this directory, with Python 3.13+ and [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv sync --locked --no-dev
+uv run --locked --no-dev mcp-files --workspace ./workspace
+```
+
+The default transport is stdio. Configure your MCP client using the [repository example](https://github.com/jayanth-mkv/agent-mcp-registry#connect-an-mcp-client).
+
+For Streamable HTTP:
+
+```bash
+uv run --locked --no-dev mcp-files --transport http --host 127.0.0.1 --port 8000 --workspace ./workspace
+```
+
+Endpoint: `http://127.0.0.1:8000/mcp`. Legacy SSE is available with `--transport sse` at `/sse`.
+
+## Tools
+
+| Tool | Arguments | Behavior |
+| --- | --- | --- |
+| `create_file` | `path`, `content=""` | Create a new file; fail if it exists. |
+| `read_file` | `path` | Read UTF-8 text. |
+| `write_file` | `path`, `content` | Create or overwrite a text file. |
+| `append_file` | `path`, `content` | Append text; create the file if missing. |
+| `delete_path` | `path` | Delete a file or recursively delete a directory. |
+| `rename_path` | `src`, `dst` | Rename a file or directory. |
+| `copy_path` | `src`, `dst` | Copy a file or directory; merge existing directories. |
+| `move_path` | `src`, `dst` | Move a file or directory. |
+| `list_files` | None | List workspace files recursively. |
+| `list_dirs` | None | List workspace directories recursively. |
+| `search_file` | `path`, `term` | Return matching lines with line numbers. |
+| `file_info` | `path` | Return JSON metadata. |
+| `workspace_stats` | None | Return JSON counts, sizes, and extensions. |
+| `path_exists` | `path` | Return `file`, `dir`, or `none`. |
+
+Paths resolve inside the configured workspace. Parent directories are created when writing files. Relative workspace paths resolve from the process working directory; prefer an absolute workspace path in client configuration.
+
+## Configuration
+
+| Setting | Environment variable | Default |
+| --- | --- | --- |
+| Workspace | `MCP_WORKSPACE_DIR` | `./workspace` |
+| HTTP/SSE host | `MCP_SERVER_HOST` | `127.0.0.1` |
+| HTTP/SSE port | `MCP_SERVER_PORT` | `8000` |
+
+CLI flags override environment settings. `--workspace` is applied before the server starts. Startup diagnostics use stderr so stdout remains available for MCP messages.
+
+## Boundaries
+
+Use a dedicated workspace: callers have read and write access, including recursive deletion. The workspace root itself cannot be deleted, renamed, or moved. Symbolic links and Windows junctions are unsupported and rejected, including links inside copied directory trees. These checks do not provide isolation against concurrent filesystem changes by other processes.
+
+The server has no authentication or size quotas. Keep HTTP/SSE on loopback. Text tools read complete files into memory and are intended for small local text files.
+
+## Development
+
+```bash
+uv sync --locked
+uv run --locked pytest -q
+uv build
+```
+
+The CLI is now `mcp-files`; the former nested `mcp-server` workspace has been consolidated into this package. AI clients are in [experimental/](https://github.com/jayanth-mkv/agent-mcp-registry/tree/main/experimental).
+
+Version 0.2.0. Licensed under the [MIT License](https://github.com/jayanth-mkv/agent-mcp-registry/blob/main/mcp-files/LICENSE).

mcp_files_context-0.2.0/README.md

@@ -0,0 +1,91 @@
+# File Server MCP
+
+An MCP server with 14 tools for managing UTF-8 text files within a configured workspace. No API key or external service is required.
+
+## Install a published release
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/). The distribution is `mcp-files-context`; the command is `mcp-files`:
+
+```bash
+uvx --python 3.13 --from mcp-files-context==0.2.0 mcp-files --workspace ./workspace
+```
+
+Published versions are listed on [PyPI](https://pypi.org/project/mcp-files-context/). If the version is not available yet, use the GitHub command below. Publishing is managed through [GitHub Actions](https://github.com/jayanth-mkv/agent-mcp-registry/blob/main/docs/publishing.md).
+
+## Run from GitHub without cloning
+
+Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git. uv downloads the selected package and manages Python 3.13 and its dependencies:
+
+```bash
+uvx --python 3.13 --from "git+https://github.com/jayanth-mkv/agent-mcp-registry.git@main#subdirectory=mcp-files" mcp-files --workspace ./workspace
+```
+
+Only this MCP and its runtime dependencies are installed. uv fetches the repository internally; you do not need a local checkout. To pin the source, replace `main` with a release tag or full commit SHA.
+
+## Install from source
+
+From this directory, with Python 3.13+ and [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv sync --locked --no-dev
+uv run --locked --no-dev mcp-files --workspace ./workspace
+```
+
+The default transport is stdio. Configure your MCP client using the [repository example](https://github.com/jayanth-mkv/agent-mcp-registry#connect-an-mcp-client).
+
+For Streamable HTTP:
+
+```bash
+uv run --locked --no-dev mcp-files --transport http --host 127.0.0.1 --port 8000 --workspace ./workspace
+```
+
+Endpoint: `http://127.0.0.1:8000/mcp`. Legacy SSE is available with `--transport sse` at `/sse`.
+
+## Tools
+
+| Tool | Arguments | Behavior |
+| --- | --- | --- |
+| `create_file` | `path`, `content=""` | Create a new file; fail if it exists. |
+| `read_file` | `path` | Read UTF-8 text. |
+| `write_file` | `path`, `content` | Create or overwrite a text file. |
+| `append_file` | `path`, `content` | Append text; create the file if missing. |
+| `delete_path` | `path` | Delete a file or recursively delete a directory. |
+| `rename_path` | `src`, `dst` | Rename a file or directory. |
+| `copy_path` | `src`, `dst` | Copy a file or directory; merge existing directories. |
+| `move_path` | `src`, `dst` | Move a file or directory. |
+| `list_files` | None | List workspace files recursively. |
+| `list_dirs` | None | List workspace directories recursively. |
+| `search_file` | `path`, `term` | Return matching lines with line numbers. |
+| `file_info` | `path` | Return JSON metadata. |
+| `workspace_stats` | None | Return JSON counts, sizes, and extensions. |
+| `path_exists` | `path` | Return `file`, `dir`, or `none`. |
+
+Paths resolve inside the configured workspace. Parent directories are created when writing files. Relative workspace paths resolve from the process working directory; prefer an absolute workspace path in client configuration.
+
+## Configuration
+
+| Setting | Environment variable | Default |
+| --- | --- | --- |
+| Workspace | `MCP_WORKSPACE_DIR` | `./workspace` |
+| HTTP/SSE host | `MCP_SERVER_HOST` | `127.0.0.1` |
+| HTTP/SSE port | `MCP_SERVER_PORT` | `8000` |
+
+CLI flags override environment settings. `--workspace` is applied before the server starts. Startup diagnostics use stderr so stdout remains available for MCP messages.
+
+## Boundaries
+
+Use a dedicated workspace: callers have read and write access, including recursive deletion. The workspace root itself cannot be deleted, renamed, or moved. Symbolic links and Windows junctions are unsupported and rejected, including links inside copied directory trees. These checks do not provide isolation against concurrent filesystem changes by other processes.
+
+The server has no authentication or size quotas. Keep HTTP/SSE on loopback. Text tools read complete files into memory and are intended for small local text files.
+
+## Development
+
+```bash
+uv sync --locked
+uv run --locked pytest -q
+uv build
+```
+
+The CLI is now `mcp-files`; the former nested `mcp-server` workspace has been consolidated into this package. AI clients are in [experimental/](https://github.com/jayanth-mkv/agent-mcp-registry/tree/main/experimental).
+
+Version 0.2.0. Licensed under the [MIT License](https://github.com/jayanth-mkv/agent-mcp-registry/blob/main/mcp-files/LICENSE).

mcp_files_context-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "mcp-files-context"
+version = "0.2.0"
+description = "MCP tools for text files inside a configured local workspace"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["fastmcp>=4.1.4,<5"]
+
+[project.urls]
+Homepage = "https://github.com/jayanth-mkv/agent-mcp-registry"
+Documentation = "https://github.com/jayanth-mkv/agent-mcp-registry/tree/main/mcp-files"
+Repository = "https://github.com/jayanth-mkv/agent-mcp-registry"
+Issues = "https://github.com/jayanth-mkv/agent-mcp-registry/issues"
+
+[project.scripts]
+mcp-files = "mcp_server.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9.2.0,<10"]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mcp_server"

mcp_files_context-0.2.0/pyproject.toml.orig

@@ -0,0 +1,28 @@
+[project]
+name = "mcp-files-context"
+version = "0.2.0"
+description = "MCP tools for text files inside a configured local workspace"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["fastmcp>=4.1.4,<5"]
+
+[project.urls]
+Homepage = "https://github.com/jayanth-mkv/agent-mcp-registry"
+Documentation = "https://github.com/jayanth-mkv/agent-mcp-registry/tree/main/mcp-files"
+Repository = "https://github.com/jayanth-mkv/agent-mcp-registry"
+Issues = "https://github.com/jayanth-mkv/agent-mcp-registry/issues"
+
+[project.scripts]
+mcp-files = "mcp_server.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9.2.0,<10"]
+
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mcp_server"

mcp_files_context-0.2.0/src/mcp_server/__init__.py

@@ -0,0 +1,72 @@
+"""Lean MCP File Server tools.
+
+Simplified + organized. Redundant / niche tools removed.
+Core focus: create, read, write, list, search, move, copy, delete, stats.
+Paths are validated & sandboxed inside the configured workspace.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from .mcp import mcp
+from .config import configure_workspace, DEFAULT_HOST, DEFAULT_PORT
+from .tools import (
+    create_file,
+    read_file,
+    write_file,
+    append_file,
+    delete_path,
+    rename_path,
+    copy_path,
+    move_path,
+    list_files,
+    list_dirs,
+    search_file,
+    file_info,
+    workspace_stats,
+    path_exists,
+)
+
+
+
+__all__ = [
+    "mcp",
+    "run",
+    # file ops
+    "create_file",
+    "read_file",
+    "write_file",
+    "append_file",
+    "delete_path",
+    "rename_path",
+    "copy_path",
+    "move_path",
+    "list_files",
+    "list_dirs",
+    "search_file",
+    "file_info",
+    "workspace_stats",
+    "path_exists",
+]
+
+
+# ----------------------------- server run ------------------------------- #
+
+
+def run(
+    host: str | None = None,
+    port: int | None = None,
+    transport: str = "stdio",
+    workspace: str | None = None,
+) -> None:
+    """Run the MCP server."""
+    _host = host or os.getenv("MCP_SERVER_HOST", DEFAULT_HOST)
+    _port = int(port or os.getenv("MCP_SERVER_PORT", DEFAULT_PORT))
+    root = configure_workspace(workspace)
+    print(f"Workspace: {root}", file=sys.stderr)
+    if transport in {"sse", "http"}:
+        mcp.run(transport=transport, host=_host, port=_port)
+    else:
+        mcp.run(transport=transport)

mcp_files_context-0.2.0/src/mcp_server/cli.py

@@ -0,0 +1,52 @@
+"""Command line interface for the mcp-server package.
+
+Usage examples:
+  uv run mcp-files --transport http --port 9000
+  python -m mcp_server.cli --transport sse
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Optional
+
+from . import run as run_programmatic
+from .config import DEFAULT_HOST, DEFAULT_PORT
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Run the MCP file server.")
+    parser.add_argument(
+        "--host",
+        default=None,
+        help=f"Host interface to bind (default: env MCP_SERVER_HOST or {DEFAULT_HOST})",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=None,
+        help=f"Port to listen on (default: env MCP_SERVER_PORT or {DEFAULT_PORT})",
+    )
+    parser.add_argument(
+        "--transport",
+        default="stdio",
+        choices=["sse", "http", "stdio"],
+        help="MCP transport (default: stdio; sse is a legacy option).",
+    )
+    parser.add_argument(
+        "--workspace",
+        default=None,
+        help="Workspace directory (default: MCP_WORKSPACE_DIR or ./workspace).",
+    )
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    run_programmatic(host=args.host, port=args.port, transport=args.transport, workspace=args.workspace)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

mcp_files_context-0.2.0/src/mcp_server/config.py

@@ -0,0 +1,22 @@
+"""Runtime configuration without filesystem changes during import."""
+
+import os
+from pathlib import Path
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+_workspace: Path | None = None
+
+
+def configure_workspace(path: str | None = None) -> Path:
+    global _workspace
+    root = Path(path or os.getenv("MCP_WORKSPACE_DIR", "workspace")).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    if not root.is_dir():
+        raise ValueError("Workspace must be a directory")
+    _workspace = root
+    return root
+
+
+def get_workspace() -> Path:
+    return _workspace if _workspace is not None else configure_workspace()

mcp_files_context-0.2.0/src/mcp_server/helpers.py

@@ -0,0 +1,57 @@
+import os
+from pathlib import Path
+from fastmcp.exceptions import ToolError
+from .config import get_workspace
+from typing import Iterable
+
+
+# ----------------------------- helpers ---------------------------------- #
+
+def _resolve(rel: str, *, protect_root: bool = False) -> Path:
+    """Resolve a relative path safely within the workspace sandbox."""
+    base = get_workspace()
+    candidate = base / rel
+    p = candidate.resolve()
+    if base not in p.parents and p != base:
+        raise ValueError("Path escapes workspace")
+    for component in (candidate, *candidate.parents):
+        if component == base:
+            break
+        if component.is_symlink() or component.is_junction():
+            raise ValueError("Symbolic links and junctions are not supported")
+    if protect_root and p == base:
+        raise ValueError("Cannot replace, move, or delete the workspace root")
+    return p
+
+
+def _iter_files() -> Iterable[Path]:
+    for p in _iter_paths():
+        if p.is_file():
+            yield p
+
+
+def _iter_paths(root: Path | None = None) -> Iterable[Path]:
+    """Walk without following links; reject linked entries before using them."""
+    start = root if root is not None else get_workspace()
+    for current, directories, files in os.walk(start, followlinks=False):
+        for name in directories + files:
+            p = Path(current) / name
+            if p.is_symlink() or p.is_junction():
+                raise ValueError("Symbolic links and junctions are not supported")
+            yield p
+
+
+def _check_tree(root: Path) -> None:
+    if root.is_dir():
+        for _ in _iter_paths(root):
+            pass
+
+
+def _ok(msg: str) -> str:  # tiny convention wrapper
+    return msg
+
+
+def _err(e: Exception) -> str:  # pragma: no cover (simple path)
+    raise ToolError(str(e)) from e
+
+__all__ = ["_resolve", "_iter_files", "_iter_paths", "_check_tree", "_ok", "_err"]

mcp_files_context-0.2.0/src/mcp_server/mcp.py

@@ -0,0 +1,2 @@
+from fastmcp import FastMCP
+mcp = FastMCP(name="File Server", version="0.2.0")

mcp_files_context-0.2.0/src/mcp_server/tools.py

@@ -0,0 +1,240 @@
+import json
+import shutil
+import time
+from .helpers import _resolve, _iter_files, _iter_paths, _check_tree, _ok, _err
+from .mcp import mcp
+from .config import get_workspace
+
+# ----------------------------- file + dir ops --------------------------- #
+
+
+@mcp.tool
+def create_file(path: str, content: str = "") -> str:
+    """Create a new text file without overwriting an existing file."""
+    try:
+        p = _resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("x", encoding="utf-8") as f:
+            f.write(content)
+        return _ok(f"created: {path}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def read_file(path: str) -> str:
+    """Read a text file."""
+    try:
+        return _resolve(path).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return f"Not found: {path}"
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def write_file(path: str, content: str) -> str:
+    """Overwrite (or create) a file."""
+    try:
+        p = _resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+        return _ok(f"written: {path}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def append_file(path: str, content: str) -> str:
+    """Append to a file (creates if missing)."""
+    try:
+        p = _resolve(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with p.open("a", encoding="utf-8") as f:
+            f.write(content)
+        return _ok(f"appended: {path}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def delete_path(path: str) -> str:
+    """Delete file or directory (recursive)."""
+    try:
+        p = _resolve(path, protect_root=True)
+        _check_tree(p)
+        if p.is_dir():
+            shutil.rmtree(p)
+        elif p.exists():
+            p.unlink()
+        else:
+            return f"Not found: {path}"
+        return _ok(f"deleted: {path}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def rename_path(src: str, dst: str) -> str:
+    """Rename a file or directory inside the workspace."""
+    try:
+        s = _resolve(src, protect_root=True)
+        d = _resolve(dst, protect_root=True)
+        _check_tree(s)
+        _check_tree(d)
+        d.parent.mkdir(parents=True, exist_ok=True)
+        s.rename(d)
+        return _ok(f"renamed: {src} -> {dst}")
+    except FileNotFoundError:
+        return f"Not found: {src}"
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def copy_path(src: str, dst: str) -> str:
+    """Copy file or directory."""
+    try:
+        s = _resolve(src)
+        d = _resolve(dst, protect_root=True)
+        if not s.exists():
+            return f"Not found: {src}"
+        if s == d or s in d.parents:
+            raise ValueError("Cannot copy a path into itself")
+        _check_tree(s)
+        _check_tree(d)
+        if s.is_dir():
+            shutil.copytree(s, d, dirs_exist_ok=True)
+        else:
+            d.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(s, d)
+        return _ok(f"copied: {src} -> {dst}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def move_path(src: str, dst: str) -> str:
+    """Move file or directory."""
+    try:
+        s = _resolve(src, protect_root=True)
+        d = _resolve(dst, protect_root=True)
+        if not s.exists():
+            return f"Not found: {src}"
+        if s == d or s in d.parents:
+            raise ValueError("Cannot move a path into itself")
+        _check_tree(s)
+        _check_tree(d)
+        d.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(s), str(d))
+        return _ok(f"moved: {src} -> {dst}")
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def list_files() -> str:
+    """List all files (relative)."""
+    try:
+        files = sorted(str(p.relative_to(get_workspace())) for p in _iter_files())
+        return "\n".join(files) if files else "(none)"
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def list_dirs() -> str:
+    """List all directories (relative)."""
+    try:
+        dirs = sorted(str(p.relative_to(get_workspace())) for p in _iter_paths() if p.is_dir())
+        return "\n".join(dirs) if dirs else "(none)"
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def search_file(path: str, term: str) -> str:
+    """Return matching lines containing term."""
+    try:
+        p = _resolve(path)
+        lines = []
+        for i, line in enumerate(p.read_text(encoding="utf-8").splitlines(), 1):
+            if term in line:
+                lines.append(f"{i}: {line.strip()}")
+        return "\n".join(lines) if lines else "(no matches)"
+    except FileNotFoundError:
+        return f"Not found: {path}"
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def file_info(path: str) -> str:
+    """Basic metadata (JSON)."""
+    try:
+        p = _resolve(path)
+        if not p.exists():
+            return f"Not found: {path}"
+        st = p.stat()
+        info = {
+            "path": path,
+            "type": "dir" if p.is_dir() else "file",
+            "size": st.st_size,
+            "modified": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(st.st_mtime)),
+            "created": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(st.st_ctime)),
+            "absolute": str(p),
+        }
+        if p.is_file():
+            try:
+                info["lines"] = sum(1 for _ in p.open("r", encoding="utf-8"))
+            except Exception:
+                pass
+        return json.dumps(info, indent=2)
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def workspace_stats() -> str:
+    """Aggregate workspace stats (JSON)."""
+    try:
+        files = 0
+        dirs = 0
+        size = 0
+        exts: dict[str, int] = {}
+        for p in _iter_paths():
+            if p.is_dir():
+                dirs += 1
+            elif p.is_file():
+                files += 1
+                try:
+                    size += p.stat().st_size
+                except OSError:
+                    pass
+                ext = p.suffix.lower() or "<none>"
+                exts[ext] = exts.get(ext, 0) + 1
+        data = {
+            "workspace": str(get_workspace()),
+            "files": files,
+            "directories": dirs,
+            "bytes": size,
+            "extensions": dict(sorted(exts.items(), key=lambda x: (-x[1], x[0]))),
+        }
+        return json.dumps(data, indent=2)
+    except Exception as e:  # pragma: no cover
+        return _err(e)
+
+
+@mcp.tool
+def path_exists(path: str) -> str:
+    """Return one of: file | dir | none."""
+    try:
+        p = _resolve(path)
+        if p.is_file():
+            return "file"
+        if p.is_dir():
+            return "dir"
+        return "none"
+    except Exception:  # pragma: no cover
+        return "none"
+