mcp-win-stdio-explorer 0.2.3__tar.gz

mcp_win_stdio_explorer-0.2.3/.gitignore

@@ -0,0 +1,60 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+*.manifest
+*.spec
+api.txt
+pip-log.txt
+pip-delete-this-directory.txt
+pypi api.txt
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+*.mo
+*.pot
+
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+
+*.log

mcp_win_stdio_explorer-0.2.3/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.5
+Name: mcp-win-stdio-explorer
+Version: 0.2.3
+Summary: Lightweight Model Context Protocol (MCP) server for token-safe workspace exploration: collapsible directory trees, dynamic .gitignore resolution, in-file grep, RapidFuzz fuzzy search, and AST code outline.
+Author-email: indala <indala@example.com>
+License-Expression: MIT
+Keywords: ast,claude,explorer,fuzzy-search,gitignore,grep,llm,mcp,workspace
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp-win-stdio>=0.2.3
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: rapidfuzz>=3.0.0
+Description-Content-Type: text/markdown
+
+# mcp-win-stdio-explorer
+
+Lightweight, token-safe **Model Context Protocol (MCP)** server for directory exploration, `.gitignore` resolution, in-file grep, RapidFuzz fuzzy search, and code symbol extraction.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (11 Tools)
+
+- **Token-Safe Directory Navigation**: Depth-controlled tree (`get_directory_tree`) that automatically collapses heavy build directories (`node_modules`, `.next`, `dist`, `.git`) to protect LLM context windows.
+- **Git-Wildmatch Pattern Engine**: Respects workspace `.gitignore` rules with high-performance `pathspec` matching.
+- **Fast Content Search (Grep)**: Regex and plain-text search across file contents with surrounding context lines.
+- **Typo-Tolerant Search**: RapidFuzz fuzzy search to locate files even with incomplete names or abbreviations.
+- **Code Symbol Outlines**: Symbol extractor (`get_code_outline`) extracting classes, functions, arguments, docstrings, and line numbers from Python (AST) and JS/TS without loading entire files into memory.
+
+---
+
+## 🛠️ Included Tools (11 Tools)
+
+1. `list_dir`: Detailed listing (PowerShell Get-ChildItem style) with file sizes, counts, and heavy folder indicators.
+2. `get_directory_tree`: Depth-controlled tree with automatic heavy folder collapsing.
+3. `find_files`: Advanced glob search honoring `.gitignore` and build caches.
+4. `fuzzy_find`: RapidFuzz typo-tolerant file search.
+5. `grep_search`: Fast text and regex search inside file contents with context lines.
+6. `read_file`: Windowed file reader with line numbers and binary file safeguard.
+7. `read_head_tail`: Quick top N (head) or bottom N (tail) line peek for logs and large files.
+8. `get_code_outline`: Symbol extractor for Python AST and JavaScript/TypeScript symbols.
+9. `get_file_info`: File metadata, line counts, line endings (CRLF vs LF), and hashes.
+10. `workspace_summary`: Folder disk usage, extension breakdown, and Git repo status.
+11. `export_tree_to_file`: Dumps an un-truncated workspace map directly to disk.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-explorer
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup explorer
+# or:
+mws add explorer
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "explorer": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.explorer"]
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws explorer guide     # Complete tool reference & prompt recipes
+mws explorer doctor    # Verify pathspec and rapidfuzz dependencies
+mws explorer setup     # Configure Claude Desktop / Claude Code
+mws explorer run       # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_explorer-0.2.3/README.md

@@ -0,0 +1,79 @@
+# mcp-win-stdio-explorer
+
+Lightweight, token-safe **Model Context Protocol (MCP)** server for directory exploration, `.gitignore` resolution, in-file grep, RapidFuzz fuzzy search, and code symbol extraction.
+
+Part of the **`mcp-win-stdio`** Windows-optimized suite.
+
+---
+
+## 🚀 Features (11 Tools)
+
+- **Token-Safe Directory Navigation**: Depth-controlled tree (`get_directory_tree`) that automatically collapses heavy build directories (`node_modules`, `.next`, `dist`, `.git`) to protect LLM context windows.
+- **Git-Wildmatch Pattern Engine**: Respects workspace `.gitignore` rules with high-performance `pathspec` matching.
+- **Fast Content Search (Grep)**: Regex and plain-text search across file contents with surrounding context lines.
+- **Typo-Tolerant Search**: RapidFuzz fuzzy search to locate files even with incomplete names or abbreviations.
+- **Code Symbol Outlines**: Symbol extractor (`get_code_outline`) extracting classes, functions, arguments, docstrings, and line numbers from Python (AST) and JS/TS without loading entire files into memory.
+
+---
+
+## 🛠️ Included Tools (11 Tools)
+
+1. `list_dir`: Detailed listing (PowerShell Get-ChildItem style) with file sizes, counts, and heavy folder indicators.
+2. `get_directory_tree`: Depth-controlled tree with automatic heavy folder collapsing.
+3. `find_files`: Advanced glob search honoring `.gitignore` and build caches.
+4. `fuzzy_find`: RapidFuzz typo-tolerant file search.
+5. `grep_search`: Fast text and regex search inside file contents with context lines.
+6. `read_file`: Windowed file reader with line numbers and binary file safeguard.
+7. `read_head_tail`: Quick top N (head) or bottom N (tail) line peek for logs and large files.
+8. `get_code_outline`: Symbol extractor for Python AST and JavaScript/TypeScript symbols.
+9. `get_file_info`: File metadata, line counts, line endings (CRLF vs LF), and hashes.
+10. `workspace_summary`: Folder disk usage, extension breakdown, and Git repo status.
+11. `export_tree_to_file`: Dumps an un-truncated workspace map directly to disk.
+
+---
+
+## 📦 Installation
+
+```powershell
+pip install mcp-win-stdio-explorer
+```
+*(Installing this package automatically installs `mws` CLI orchestrator)*.
+
+---
+
+## 🚀 One-Command Claude Setup
+
+```powershell
+mws setup explorer
+# or:
+mws add explorer
+```
+
+### Manual Configuration Example
+In `%APPDATA%\Claude\claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "explorer": {
+      "command": "python",
+      "args": ["-m", "mcp_win_stdio.explorer"]
+    }
+  }
+}
+```
+
+---
+
+## 📖 CLI Commands & Interactive Guide
+
+```powershell
+mws explorer guide     # Complete tool reference & prompt recipes
+mws explorer doctor    # Verify pathspec and rapidfuzz dependencies
+mws explorer setup     # Configure Claude Desktop / Claude Code
+mws explorer run       # Launch server over stdio
+```
+
+---
+
+## 📜 License
+MIT License. Copyright (c) 2026 Mohan Kumar Indala.

mcp_win_stdio_explorer-0.2.3/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-win-stdio-explorer"
+version = "0.2.3"
+description = "Lightweight Model Context Protocol (MCP) server for token-safe workspace exploration: collapsible directory trees, dynamic .gitignore resolution, in-file grep, RapidFuzz fuzzy search, and AST code outline."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "indala", email = "indala@example.com" }
+]
+keywords = ["mcp", "claude", "workspace", "explorer", "grep", "fuzzy-search", "gitignore", "ast", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Win32 (MS Windows)",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+]
+
+dependencies = [
+    "mcp-win-stdio>=0.2.3",
+    "mcp>=1.2.0",
+    "pathspec>=0.12.0",
+    "rapidfuzz>=3.0.0",
+]
+
+[project.scripts]
+mcp-win-stdio-explorer = "mcp_win_stdio.explorer.cli:main"
+mws-explorer = "mcp_win_stdio.explorer.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_win_stdio"]

mcp_win_stdio_explorer-0.2.3/src/mcp_win_stdio/explorer/__init__.py

@@ -0,0 +1,5 @@
+"""
+mcp-win-stdio-explorer: Workspace Explorer MCP Server.
+"""
+
+__version__ = "0.2.3"

mcp_win_stdio_explorer-0.2.3/src/mcp_win_stdio/explorer/__main__.py

@@ -0,0 +1,8 @@
+"""
+Direct module execution for mcp_win_stdio.explorer.
+"""
+
+from mcp_win_stdio.explorer.server import mcp
+
+if __name__ == "__main__":
+    mcp.run()

mcp_win_stdio_explorer-0.2.3/src/mcp_win_stdio/explorer/cli.py

@@ -0,0 +1,176 @@
+"""
+CLI entry point for mcp-win-stdio-explorer.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+from mcp_win_stdio.explorer import __version__
+from mcp_win_stdio.explorer.guide import print_guide
+from mcp_win_stdio.explorer.server import mcp
+
+
+def get_claude_desktop_config_path() -> Path | None:
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        p = Path(appdata) / "Claude" / "claude_desktop_config.json"
+        if p.exists():
+            return p
+    default_p = Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    return default_p if default_p.exists() else None
+
+
+def get_claude_cli_config_path() -> Path | None:
+    p = Path.home() / ".claude.json"
+    return p if p.exists() else None
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    """Setup explorer MCP server in Claude Desktop and Claude Code CLI."""
+    client = args.client.lower()
+    python_exe = sys.executable.replace("\\", "/")
+    cmd_args = ["-m", "mcp_win_stdio.explorer.server"]
+
+    print(f"\nSetting up 'explorer' MCP server (target: {client})...\n")
+
+    # 1. Desktop
+    if client in ("all", "desktop"):
+        desktop_cfg = get_claude_desktop_config_path()
+        if desktop_cfg:
+            try:
+                shutil.copy2(desktop_cfg, desktop_cfg.with_suffix(".json.bak"))
+                with open(desktop_cfg, "r", encoding="utf-8") as f:
+                    data = json.load(f)
+                if "mcpServers" not in data:
+                    data["mcpServers"] = {}
+                data["mcpServers"]["explorer"] = {
+                    "command": python_exe,
+                    "args": cmd_args,
+                }
+                with open(desktop_cfg, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+                print(f"[OK] Claude Desktop: Configured 'explorer' in {desktop_cfg}")
+            except Exception as e:
+                print(f"[ERROR] Claude Desktop: Failed to configure: {e}")
+        else:
+            print("[WARN] Claude Desktop configuration not found.")
+
+    # 2. CLI
+    if client in ("all", "cli"):
+        added_cli = False
+        try:
+            res = subprocess.run(
+                ["claude", "mcp", "add", "-s", "user", "explorer", "--", python_exe] + cmd_args,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if res.returncode == 0:
+                added_cli = True
+                print("[OK] Claude Code CLI: Configured via `claude mcp add`")
+        except Exception:
+            pass
+
+        if not added_cli:
+            cli_cfg = get_claude_cli_config_path()
+            if cli_cfg:
+                try:
+                    with open(cli_cfg, "r", encoding="utf-8") as f:
+                        cli_data = json.load(f)
+                    if "mcpServers" not in cli_data:
+                        cli_data["mcpServers"] = {}
+                    cli_data["mcpServers"]["explorer"] = {
+                        "command": python_exe,
+                        "args": cmd_args,
+                    }
+                    with open(cli_cfg, "w", encoding="utf-8") as f:
+                        json.dump(cli_data, f, indent=2)
+                    print(f"[OK] Claude Code CLI: Configured directly in {cli_cfg}")
+                except Exception as e:
+                    print(f"[ERROR] Claude CLI: Failed to configure: {e}")
+
+    print("\nWorkspace Explorer MCP setup complete! Please restart Claude Desktop if active.\n")
+
+
+def cmd_remove(args: argparse.Namespace) -> None:
+    """Remove explorer MCP server from Claude Desktop and CLI."""
+    desktop_cfg = get_claude_desktop_config_path()
+    if desktop_cfg and desktop_cfg.exists():
+        try:
+            with open(desktop_cfg, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            if "mcpServers" in data and "explorer" in data["mcpServers"]:
+                del data["mcpServers"]["explorer"]
+                with open(desktop_cfg, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=2)
+                print(f"[OK] Removed 'explorer' from Claude Desktop.")
+        except Exception as e:
+            print(f"[ERROR] Claude Desktop: {e}")
+
+    try:
+        res = subprocess.run(["claude", "mcp", "remove", "-s", "user", "explorer"], capture_output=True, text=True)
+        if res.returncode == 0:
+            print("[OK] Removed 'explorer' from Claude Code CLI.")
+    except Exception:
+        pass
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run explorer MCP server over stdio."""
+    mcp.run()
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Check Workspace Explorer health and dependencies."""
+    print(f"\n=== mcp-win-stdio-explorer Doctor Diagnostic (v{__version__}) ===\n")
+    print(f"[OK] Python: {sys.version.split()[0]} ({sys.executable})")
+
+    for dep in ("mcp", "pathspec", "rapidfuzz"):
+        try:
+            __import__(dep)
+            print(f"[OK] Dependency: {dep:<12}")
+        except ImportError:
+            print(f"[FAIL] Dependency: {dep:<12} (MISSING)")
+
+    print("\nDiagnostic complete.\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-win-stdio-explorer",
+        description="Workspace Explorer MCP Server CLI",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    sub_setup = subparsers.add_parser("setup", help="Auto-configure into Claude Desktop & CLI")
+    sub_setup.add_argument("--client", "-c", choices=["all", "desktop", "cli"], default="all")
+    sub_setup.set_defaults(func=cmd_setup)
+
+    sub_remove = subparsers.add_parser("remove", help="Remove from Claude Desktop & CLI")
+    sub_remove.set_defaults(func=cmd_remove)
+
+    sub_guide = subparsers.add_parser("guide", help="View usage guide and prompt recipes")
+    sub_guide.set_defaults(func=lambda args: print_guide())
+
+    sub_run = subparsers.add_parser("run", help="Run Explorer MCP server over stdio")
+    sub_run.set_defaults(func=cmd_run)
+
+    sub_doctor = subparsers.add_parser("doctor", help="Check dependencies")
+    sub_doctor.set_defaults(func=cmd_doctor)
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio_explorer-0.2.3/src/mcp_win_stdio/explorer/guide.py

@@ -0,0 +1,68 @@
+"""
+Interactive and printable guide for the Workspace Explorer MCP server.
+"""
+
+EXPLORER_GUIDE = """
+# ================================================================
+# WORKSPACE EXPLORER MCP - USER & LLM GUIDE
+# ================================================================
+
+The Workspace Explorer MCP server provides 11 specialized tools for
+token-safe directory navigation, smart .gitignore awareness,
+in-file grep, RapidFuzz fuzzy search, and code symbol extraction.
+
+----------------------------------------------------------------
+1. TOOL SUMMARY
+----------------------------------------------------------------
+* Directory Navigation & Hierarchy:
+  - list_dir(path, filter_pattern, sort_by, limit, offset):
+    Detailed listing (PowerShell Get-ChildItem style) with sizes,
+    child counts, and heavy build directory flags.
+  - get_directory_tree(path, max_depth, ignore_mode, collapse_heavy_dirs):
+    Depth-controlled tree. Automatically collapses node_modules, .next,
+    dist, and .git into informative summary nodes to protect context.
+
+* Fast Search:
+  - find_files(search_path, pattern, extensions, min/max_size, modified_after):
+    Advanced glob search honoring .gitignore and build caches.
+  - fuzzy_find(query, search_path, extensions, score_cutoff):
+    RapidFuzz typo-tolerant search. Find files by abbreviation (e.g. 'usrctrl').
+  - grep_search(query, search_path, is_regex, context_lines, max_matches):
+    Search text or regex INSIDE file contents across the workspace.
+
+* Token-Safe Reading:
+  - read_file(file_path, start_line, end_line, line_numbers, max_lines):
+    Windowed file reader with automatic binary detection/protection.
+  - read_head_tail(file_path, mode, lines):
+    Quick top N (head) or bottom N (tail) line peek for logs/CSVs.
+
+* Code Structure & Diagnostics:
+  - get_code_outline(file_path):
+    Extracts classes, functions, arguments, docstrings, and line numbers
+    from Python (AST), JS/TS, and JSON without loading the whole file!
+  - get_file_info(path, include_hash):
+    Full diagnostics (timestamps, line count, CRLF/LF, MD5/SHA256).
+  - workspace_summary(path):
+    Folder disk usage, file count breakdown by extension, recent files, Git status.
+  - export_tree_to_file(path, output_file_path, format):
+    Writes a complete un-truncated workspace map directly to disk.
+
+----------------------------------------------------------------
+2. EXAMPLE PROMPTS FOR CLAUDE
+----------------------------------------------------------------
+* Find files with typos:
+  "Use fuzzy_find to look for 'reconcil' or 'authctrl' in my repo."
+
+* Check outline without token blowup:
+  "Use get_code_outline on src/server.py so I can see available methods."
+
+* Grep inside code:
+  "Use grep_search to find 'SAP_PO' across all .py and .ts files."
+
+* Tree view without node_modules bloat:
+  "Show me the directory tree of this project with max_depth=2."
+# ================================================================
+"""
+
+def print_explorer_guide() -> None:
+    print(EXPLORER_GUIDE.strip())