Local file finder

Instructions

Implementation Reference

• nanomcp/server.py:269-307 (handler)

  Main handler function for the 'find_files' tool. Takes arguments dict, extracts 'query' (required), 'root' (optional subdirectory), and 'max_results' (default 20, clamped 1-100). Walks the filesystem under the allowed root using os.walk, supports glob patterns if query contains wildcards (*?[]), otherwise does substring matching. Skips .git, __pycache__, node_modules, and dot-directories. Returns formatted file list or stops early when max_results or 20,000 file scan limit is reached.

  def find_files(arguments: dict[str, Any]) -> str:
      query = str(arguments.get("query", "")).strip()
      if not query:
          raise ToolError("query is required")
  
      root = search_root(arguments.get("root"))
      max_results = clamp_int(arguments.get("max_results", 20), 1, 100)
      query_lower = query.lower()
      use_glob = any(char in query for char in "*?[]")
  
      matches: list[str] = []
      visited = 0
      limit = 20_000
  
      for current, dirs, files in os.walk(root):
          dirs[:] = [
              d
              for d in dirs
              if d not in {".git", "__pycache__", "node_modules"}
              and not d.startswith(".")
          ]
          visited += len(files)
  
          for filename in files:
              filename_lower = filename.lower()
              if use_glob:
                  ok = fnmatch.fnmatch(filename_lower, query_lower)
              else:
                  ok = query_lower in filename_lower
              if ok:
                  path = Path(current) / filename
                  matches.append(str(path))
                  if len(matches) >= max_results:
                      return format_file_matches(query, root, matches, truncated=True)
  
          if visited >= limit:
              return format_file_matches(query, root, matches, truncated=True)
  
      return format_file_matches(query, root, matches, truncated=False)

• nanomcp/server.py:242-245 (helper)

  Helper function 'allowed_root' that returns the base directory for file searches. Defaults to ~/Desktop, overridable via NANOMCP_FILE_ROOT environment variable.

  def allowed_root() -> Path:
      default_root = Path.home() / "Desktop"
      configured = os.environ.get("NANOMCP_FILE_ROOT", str(default_root))
      return Path(configured).expanduser().resolve()

• nanomcp/server.py:248-266 (helper)

  Helper function 'search_root' that resolves and validates the root directory for a search. Ensures the target root is within the allowed root (prevents path traversal). Checks existence and directory status.

  def search_root(root_arg: Any) -> Path:
      base = allowed_root()
      if root_arg is None or str(root_arg).strip() == "":
          root = base
      else:
          candidate = Path(str(root_arg)).expanduser()
          root = candidate if candidate.is_absolute() else base / candidate
          root = root.resolve()
  
      try:
          root.relative_to(base)
      except ValueError as exc:
          raise ToolError(f"root must be inside allowed root: {base}") from exc
  
      if not root.exists():
          raise ToolError(f"root does not exist: {root}")
      if not root.is_dir():
          raise ToolError(f"root is not a directory: {root}")
      return root

• nanomcp/server.py:318-331 (helper)

  Helper function 'format_file_matches' that formats the list of matching files into a human-readable string, optionally noting if results were truncated.

  def format_file_matches(
      query: str,
      root: Path,
      matches: list[str],
      truncated: bool,
  ) -> str:
      if not matches:
          return f"No files matching {query!r} under {root}."
  
      lines = [f"Files matching {query!r} under {root}:"]
      lines.extend(f"- {path}" for path in matches)
      if truncated:
          lines.append("- Search stopped after reaching the result or scan limit.")
      return "\n".join(lines)

• nanomcp/server.py:49-77 (registration)

  Tool registration entry in the TOOLS list. Defines the 'find_files' tool with name, title, description, and inputSchema (query required string/glob, optional root string, optional max_results integer with min=1 max=100 default=20).

  {
      "name": "find_files",
      "title": "Local file finder",
      "description": (
          "Find local files by name under the allowed root. The default root is "
          "~/Desktop. Set NANOMCP_FILE_ROOT to change it."
      ),
      "inputSchema": {
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Filename substring or glob pattern, such as *.pdf.",
              },
              "root": {
                  "type": "string",
                  "description": "Optional subdirectory under NANOMCP_FILE_ROOT.",
              },
              "max_results": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100,
                  "default": 20,
              },
          },
          "required": ["query"],
          "additionalProperties": False,
      },
  },

• nanomcp/server.py:140-141 (registration)

  The 'call_tool' function dispatches 'find_files' requests to the find_files handler function and wraps the result via tool_result().

  if name == "find_files":
      return tool_result(find_files(arguments))