mcp-win-stdio 0.1.0__py3-none-any.whl

mcp_win_stdio/__init__.py

@@ -0,0 +1,5 @@
+"""
+mcp-win-stdio: Windows-optimized Model Context Protocol suite and CLI orchestrator.
+"""
+
+__version__ = "0.1.0"

mcp_win_stdio/cli.py

@@ -0,0 +1,375 @@
+"""
+mcp-win-stdio CLI: Windows-optimized Model Context Protocol suite orchestrator.
+"""
+
+import argparse
+import importlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from typing import Dict, List, Optional
+
+# Ensure Windows console uses UTF-8 without crashing on cp1252
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+from mcp_win_stdio import __version__
+from mcp_win_stdio.core.config import INDALA_DIR, PLUGINS_DIR, ensure_workspace_dirs, load_config, save_config
+from mcp_win_stdio.core.discovery import BUILTIN_SERVERS, get_server_info, list_available_servers
+from mcp_win_stdio.core.installer import (
+    generate_claude_cli_command,
+    generate_claude_desktop_snippet,
+    get_claude_cli_config_path,
+    get_claude_desktop_config_path,
+    install_pip_dependencies,
+    remove_server_from_cli,
+    remove_server_from_desktop,
+    safe_apply_to_cli,
+    safe_apply_to_desktop,
+)
+from mcp_win_stdio.guides.excel_guide import print_excel_guide
+from mcp_win_stdio.guides.explorer_guide import print_explorer_guide
+from mcp_win_stdio.guides.tsc_guide import print_tsc_guide
+from mcp_win_stdio.guides.word_guide import print_word_guide
+
+
+def print_dashboard() -> None:
+    """Print interactive home dashboard when run with no arguments."""
+    ensure_workspace_dirs()
+    servers = list_available_servers()
+    desktop_cfg = get_claude_desktop_config_path()
+    cli_cfg = get_claude_cli_config_path()
+
+    print(f"\n" + "=" * 76)
+    print(f"   🚀  mcp-win-stdio — Windows Model Context Protocol Suite (v{__version__})")
+    print("=" * 76)
+    print(f" Single-Source Hub:      {INDALA_DIR}")
+    print(f" Claude Desktop Config:  {desktop_cfg or 'Not detected (%APPDATA%\\Claude)'}")
+    print(f" Claude Code CLI Config: {cli_cfg or 'Not detected (~/.claude.json)'}")
+    print("-" * 76)
+
+    print(f"{'SERVER':<12} {'STATUS':<16} {'TOOLS':<8} {'DESCRIPTION'}")
+    print("-" * 76)
+
+    for name, srv in servers.items():
+        is_inst = srv.get("is_installed", False)
+        status_str = "[Installed]" if is_inst else "[Not Installed]"
+        tools = str(srv.get("tools_count", "?"))
+        desc = srv.get("description", "")
+        if len(desc) > 36:
+            desc = desc[:33] + "..."
+        print(f"{name:<12} {status_str:<16} {tools:<8} {desc}")
+
+    print("-" * 76)
+    print(" 💡 Quick Commands:")
+    print("   mws setup <server>    -> Install dependencies & show Claude config")
+    print("   mws guide <server>    -> View complete tool reference & Claude prompts")
+    print("   mws doctor            -> Run health checks (Office COM, Python, Node)")
+    print("   mws run <server>      -> Launch MCP server over stdio")
+    print("   mws list              -> List all servers and custom plugins")
+    print("=" * 76 + "\n")
+
+
+def cmd_list(args: argparse.Namespace) -> None:
+    """List available MCP servers and installation status."""
+    print_dashboard()
+
+
+def cmd_guide(args: argparse.Namespace) -> None:
+    """Print guide and prompt recipes for a specific server."""
+    target = (args.server or "all").lower()
+
+    if target in ("excel", "all"):
+        print_excel_guide()
+    if target in ("word", "all"):
+        print_word_guide()
+    if target in ("explorer", "workspace-explorer", "all"):
+        print_explorer_guide()
+    if target in ("tsc", "all"):
+        print_tsc_guide()
+
+    if target not in ("excel", "word", "explorer", "workspace-explorer", "tsc", "all"):
+        print(f"No built-in guide for '{target}'. Built-in guides: 'excel', 'word', 'explorer', 'tsc'.")
+
+
+def cmd_setup(args: argparse.Namespace) -> None:
+    """Setup and configure a server with transparent guidance and optional safe auto-apply."""
+    ensure_workspace_dirs()
+    servers = list_available_servers()
+
+    target = args.server
+    client = args.client.lower()
+
+    if not target:
+        if sys.stdin.isatty():
+            print("\n=== 🛠️  mcp-win-stdio Setup Wizard ===")
+            print("Select an MCP server to configure:")
+            print("  [1] excel     (20 tools: Pandas queries, RapidFuzz reconciliation, Office COM)")
+            print("  [2] word      (10 tools: Multi-unit margins, multi-columns, typography, images)")
+            print("  [3] explorer  (11 tools: Token-safe tree, .gitignore, regex grep, AST outline)")
+            print("  [4] tsc       (6 tools: TypeScript diagnostic watcher, 0ms cache)")
+            print("  [5] all       (Configure all servers)")
+            print("  [6] Exit")
+            choice = input("\nEnter choice (1-6) [default: 1]: ").strip() or "1"
+            mapping = {"1": "excel", "2": "word", "3": "explorer", "4": "tsc", "5": "all"}
+            if choice not in mapping:
+                print("Setup cancelled.")
+                return
+            target = mapping[choice]
+        else:
+            target = "all"
+
+    selected_servers = ["excel", "word", "explorer", "tsc"] if target.lower() == "all" else [target.lower()]
+
+    for srv_name in selected_servers:
+        srv = get_server_info(srv_name)
+        if not srv:
+            print(f"\n[ERROR] Unknown server: '{srv_name}'. Run 'mws list' to see available servers.")
+            continue
+
+        print(f"\n" + "=" * 70)
+        print(f"  Configuration Setup for: {srv['title']}")
+        print("=" * 70)
+
+        # 1. Dependency check & optional installation
+        env_vars = {}
+        if not srv.get("is_installed"):
+            req_pip = srv.get("required_pip", [])
+            print(f"\n[INFO] '{srv_name}' requires the following Python packages: {', '.join(req_pip)}")
+            if sys.stdin.isatty():
+                do_install = input(f"Would you like to install them now via pip? [Y/n]: ").strip().lower()
+                if do_install not in ("n", "no"):
+                    ok, msg = install_pip_dependencies(req_pip)
+                    if ok:
+                        print(f"[OK] {msg}")
+                    else:
+                        print(f"[WARN] {msg}")
+            else:
+                install_pip_dependencies(req_pip)
+
+        # Special prompt for TSC watch directory
+        if srv_name == "tsc":
+            default_dir = os.getcwd()
+            if sys.stdin.isatty():
+                chosen_dir = input(f"\nEnter TypeScript project directory to watch [default: {default_dir}]: ").strip() or default_dir
+            else:
+                chosen_dir = default_dir
+            env_vars["TSC_WATCH_DIR"] = os.path.abspath(chosen_dir)
+
+        # 2. Transparent Configuration Guidance
+        snippet_dict = generate_claude_desktop_snippet(srv_name, env_vars if env_vars else None)
+        snippet_json = json.dumps({srv_name: snippet_dict}, indent=2)
+        cli_command = generate_claude_cli_command(srv_name, env_vars if env_vars else None)
+
+        print("\n" + "-" * 70)
+        print("📋 Claude Desktop Configuration:")
+        print("File: %APPDATA%\\Claude\\claude_desktop_config.json")
+        print("Add this snippet inside your \"mcpServers\" object:\n")
+        print(snippet_json)
+
+        print("\n" + "-" * 70)
+        print("💻 Claude Code CLI Command:")
+        print("Run this command in your terminal:\n")
+        print(f"  {cli_command}")
+        print("-" * 70)
+
+        # 3. Optional Safe Auto-Write
+        if sys.stdin.isatty():
+            auto_apply = input("\n👉 Would you like mws to safely write this configuration for you? [y/N]: ").strip().lower()
+            if auto_apply in ("y", "yes"):
+                if client in ("all", "desktop"):
+                    ok, msg = safe_apply_to_desktop(srv_name, env_vars if env_vars else None)
+                    symbol = "OK" if ok else "ERROR"
+                    print(f"  [{symbol}] Claude Desktop: {msg}")
+                if client in ("all", "cli"):
+                    ok, msg = safe_apply_to_cli(srv_name, env_vars if env_vars else None)
+                    symbol = "OK" if ok else "ERROR"
+                    print(f"  [{symbol}] Claude Code CLI: {msg}")
+                print("\n[NOTE] Please restart Claude Desktop if it is currently running.")
+        else:
+            print("\nTo auto-apply via script, pass interactive input or use the JSON snippet above.")
+
+    print("\n" + "=" * 70)
+    print("Setup guide complete!")
+    print("=" * 70 + "\n")
+
+
+def cmd_remove(args: argparse.Namespace) -> None:
+    """Remove server(s) from Claude Desktop and CLI."""
+    target = args.server.lower()
+    client = args.client.lower()
+
+    servers_to_remove = ["excel", "word", "explorer", "tsc"] if target == "all" else [target]
+
+    for srv_name in servers_to_remove:
+        print(f"\nRemoving '{srv_name}'...")
+        if client in ("all", "desktop"):
+            ok, msg = remove_server_from_desktop(srv_name)
+            print(f"  Claude Desktop: {msg}")
+        if client in ("all", "cli"):
+            ok, msg = remove_server_from_cli(srv_name)
+            print(f"  Claude CLI:     {msg}")
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run an MCP server over stdio."""
+    server_name = args.server.lower()
+    srv = get_server_info(server_name)
+
+    if not srv:
+        print(f"Error: Server '{server_name}' not found. Run 'mws list' to view available servers.", file=sys.stderr)
+        sys.exit(1)
+
+    if srv["is_builtin"]:
+        module_name = srv["module"]
+        try:
+            mod = importlib.import_module(module_name)
+            if hasattr(mod, "mcp"):
+                mod.mcp.run()
+            else:
+                print(f"Error: Module '{module_name}' does not expose 'mcp'.", file=sys.stderr)
+                sys.exit(1)
+        except Exception as e:
+            print(f"Error launching server '{server_name}': {str(e)}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        # Run custom user plugin
+        plugin_path = srv["path"]
+        try:
+            subprocess.run([sys.executable, plugin_path])
+        except Exception as e:
+            print(f"Error running plugin: {str(e)}", file=sys.stderr)
+            sys.exit(1)
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Run diagnostic health checks on Windows environment, COM automation, and dependencies."""
+    print(f"\n=== mcp-win-stdio Doctor Diagnostic (v{__version__}) ===\n")
+
+    # 1. Python Check
+    py_ver = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    py_status = "OK" if sys.version_info >= (3, 10) else "FAIL (Requires Python 3.10+)"
+    print(f"[{py_status}] Python Runtime: {py_ver} ({sys.executable})")
+
+    # 2. Python Dependencies
+    deps = [
+        ("mcp", "MCP Protocol Framework (Core)"),
+        ("docx", "Python-Docx (Word MCP)"),
+        ("pandas", "Pandas DataFrames (Excel MCP)"),
+        ("openpyxl", "OpenPyXL Engine (Excel MCP)"),
+        ("rapidfuzz", "RapidFuzz Vector Matcher (Excel & Explorer)"),
+        ("pathspec", "Git-Wildmatch Pattern Engine (Explorer MCP)"),
+        ("win32com", "PyWin32 Windows COM Automation (Excel & Word)"),
+    ]
+    print("\n--- Python Dependencies ---")
+    for mod, desc in deps:
+        try:
+            importlib.import_module(mod)
+            print(f"[OK] {mod:<14} : {desc}")
+        except ImportError:
+            print(f"[MISSING] {mod:<10} : {desc}")
+
+    # 3. Microsoft Office COM Automation
+    print("\n--- Microsoft Office COM Automation ---")
+    try:
+        import win32com.client
+        excel_app = win32com.client.DispatchEx("Excel.Application")
+        excel_ver = excel_app.Version
+        excel_app.Quit()
+        print(f"[OK] Microsoft Excel COM Automation: Ready (Version {excel_ver})")
+    except Exception as e:
+        print(f"[INFO] Microsoft Excel COM Automation: Not available ({str(e)})")
+
+    try:
+        import win32com.client
+        word_app = win32com.client.Dispatch("Word.Application")
+        word_app.Visible = False
+        word_ver = word_app.Version
+        word_app.Quit()
+        print(f"[OK] Microsoft Word COM Automation: Ready (Version {word_ver})")
+    except Exception as e:
+        print(f"[INFO] Microsoft Word COM Automation: Not available ({str(e)})")
+
+    # 4. Node.js & TypeScript
+    print("\n--- Node.js & TypeScript Environment ---")
+    node_bin = shutil.which("node")
+    print(f"[{'OK' if node_bin else 'INFO'}] Node.js: {node_bin or 'Not found on PATH'}")
+
+    tsc_bin = shutil.which("tsc")
+    print(f"[{'OK' if tsc_bin else 'INFO'}] Global tsc: {tsc_bin or 'Not found on PATH (will check local projects)'}")
+
+    # 5. Claude Config Files
+    print("\n--- Claude Configuration Targets ---")
+    desktop_cfg = get_claude_desktop_config_path()
+    if desktop_cfg and desktop_cfg.exists():
+        print(f"[OK] Claude Desktop: {desktop_cfg}")
+    else:
+        print(f"[INFO] Claude Desktop config: {desktop_cfg or 'Not found in %APPDATA%\\Claude'}")
+
+    cli_cfg = get_claude_cli_config_path()
+    if cli_cfg and cli_cfg.exists():
+        print(f"[OK] Claude Code CLI: {cli_cfg}")
+    else:
+        print(f"[INFO] Claude Code CLI config: {cli_cfg or 'Not found in ~/.claude.json'}")
+
+    print("\nDiagnostic complete.\n")
+
+
+def main() -> None:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="mcp-win-stdio",
+        description="Windows-optimized Model Context Protocol suite & setup orchestrator.",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    # list
+    sub_list = subparsers.add_parser("list", help="List available MCP servers and tool counts")
+    sub_list.set_defaults(func=cmd_list)
+
+    # guide
+    sub_guide = subparsers.add_parser("guide", help="View usage guide, tool specs, and LLM prompts")
+    sub_guide.add_argument("server", nargs="?", default="all", help="Server name ('excel', 'word', 'explorer', 'tsc', 'all')")
+    sub_guide.set_defaults(func=cmd_guide)
+
+    # setup
+    sub_setup = subparsers.add_parser("setup", help="Configure server(s) into Claude Desktop and CLI")
+    sub_setup.add_argument("server", nargs="?", default=None, help="Server to install ('excel', 'word', 'explorer', 'tsc', 'all')")
+    sub_setup.add_argument("--client", "-c", choices=["all", "desktop", "cli"], default="all", help="Target client")
+    sub_setup.set_defaults(func=cmd_setup)
+
+    # remove
+    sub_remove = subparsers.add_parser("remove", help="Remove server(s) from Claude Desktop and CLI")
+    sub_remove.add_argument("server", help="Server to remove ('excel', 'word', 'explorer', 'tsc', 'all')")
+    sub_remove.add_argument("--client", "-c", choices=["all", "desktop", "cli"], default="all", help="Target client")
+    sub_remove.set_defaults(func=cmd_remove)
+
+    # run
+    sub_run = subparsers.add_parser("run", help="Launch an MCP server over stdio for Claude")
+    sub_run.add_argument("server", help="Server name to launch ('excel', 'word', 'explorer', 'tsc', or custom plugin)")
+    sub_run.set_defaults(func=cmd_run)
+
+    # doctor
+    sub_doctor = subparsers.add_parser("doctor", help="Check system health, dependencies, and COM readiness")
+    sub_doctor.set_defaults(func=cmd_doctor)
+
+    args = parser.parse_args()
+    if not args.command:
+        # Default action when run with no arguments: show interactive dashboard
+        print_dashboard()
+        sys.exit(0)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio/core/config.py

@@ -0,0 +1,55 @@
+"""
+Core configuration and single-source path management for mcp-win-stdio.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+# Standard single-source directory: ~/.mcp-win-stdio/
+USER_HOME = Path.home()
+INDALA_DIR = USER_HOME / ".mcp-win-stdio"
+PLUGINS_DIR = INDALA_DIR / "plugins"
+LOGS_DIR = INDALA_DIR / "logs"
+EXPORTS_DIR = INDALA_DIR / "exports"
+CONFIG_FILE = INDALA_DIR / "config.json"
+
+
+def ensure_workspace_dirs() -> Dict[str, Path]:
+    """Ensure all core directories exist and return paths."""
+    for d in (INDALA_DIR, PLUGINS_DIR, LOGS_DIR, EXPORTS_DIR):
+        d.mkdir(parents=True, exist_ok=True)
+    if not CONFIG_FILE.exists():
+        default_config = {
+            "version": "0.1.0",
+            "default_client": "all",
+            "installed_servers": {},
+            "log_level": "INFO",
+        }
+        with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(default_config, f, indent=2)
+    return {
+        "root": INDALA_DIR,
+        "plugins": PLUGINS_DIR,
+        "logs": LOGS_DIR,
+        "exports": EXPORTS_DIR,
+        "config": CONFIG_FILE,
+    }
+
+
+def load_config() -> Dict[str, Any]:
+    """Load configuration from ~/.mcp-win-stdio/config.json."""
+    ensure_workspace_dirs()
+    try:
+        with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def save_config(cfg: Dict[str, Any]) -> None:
+    """Save configuration to ~/.mcp-win-stdio/config.json."""
+    ensure_workspace_dirs()
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)

mcp_win_stdio/core/discovery.py

@@ -0,0 +1,110 @@
+"""
+Discovery service for built-in MCP servers and user plugins in ~/.mcp-win-stdio/plugins.
+"""
+
+import importlib
+import importlib.util
+from pathlib import Path
+import sys
+from typing import Any, Dict, List, Optional
+
+from mcp_win_stdio.core.config import PLUGINS_DIR, ensure_workspace_dirs
+
+BUILTIN_SERVERS = {
+    "excel": {
+        "name": "excel",
+        "title": "Excel MCP (Windows Native + Pandas)",
+        "module": "mcp_win_stdio.excel.server",
+        "description": "20 tools: Pandas queries, RapidFuzz reconciliation, OpenPyXL editing, and native Excel COM automation (PDF exports, recalc, pivots, macros).",
+        "tools_count": 20,
+        "is_builtin": True,
+        "required_pip": ["pandas>=2.0.0", "openpyxl>=3.1.0", "rapidfuzz>=3.0.0", "pywin32>=306"],
+        "dependencies": ["pandas", "openpyxl", "rapidfuzz"],
+        "optional_dependencies": ["win32com"],
+    },
+    "word": {
+        "name": "word",
+        "title": "Word MCP (Advanced Layout & Typography)",
+        "module": "mcp_win_stdio.word.server",
+        "description": "10 tools: multi-unit margins (in, cm, mm, pt), multi-column layout, paragraph spacing/indentation, typography (fonts, sizes, colors), images, tables.",
+        "tools_count": 10,
+        "is_builtin": True,
+        "required_pip": ["python-docx>=1.1.0", "pywin32>=306"],
+        "dependencies": ["docx"],
+        "optional_dependencies": ["win32com"],
+    },
+    "explorer": {
+        "name": "explorer",
+        "title": "Workspace Explorer MCP (Smart Tree & Grep)",
+        "module": "mcp_win_stdio.explorer.server",
+        "description": "11 tools: token-safe collapsible directory trees, .gitignore resolution, in-file grep, RapidFuzz fuzzy search, and Python/TS AST outline.",
+        "tools_count": 11,
+        "is_builtin": True,
+        "required_pip": ["pathspec>=0.12.0", "rapidfuzz>=3.0.0"],
+        "dependencies": ["pathspec", "rapidfuzz"],
+        "optional_dependencies": [],
+    },
+    "tsc": {
+        "name": "tsc",
+        "title": "TypeScript Watcher MCP (0ms Diagnostic Cache)",
+        "module": "mcp_win_stdio.tsc.server",
+        "description": "6 tools: background tsc compiler watchers, in-memory diagnostic cache, 0ms error checks, and dynamic project switching.",
+        "tools_count": 6,
+        "is_builtin": True,
+        "required_pip": ["mcp>=1.2.0"],
+        "dependencies": ["mcp"],
+        "optional_dependencies": [],
+    },
+}
+
+
+def check_server_installed(server_info: Dict[str, Any]) -> bool:
+    """Check if all mandatory dependencies for a server are importable."""
+    if not server_info.get("is_builtin"):
+        return Path(server_info.get("path", "")).exists()
+
+    for dep in server_info.get("dependencies", []):
+        try:
+            if not importlib.util.find_spec(dep):
+                return False
+        except Exception:
+            return False
+    return True
+
+
+def list_available_servers() -> Dict[str, Dict[str, Any]]:
+    """Return dictionary of all available servers with live installation status."""
+    ensure_workspace_dirs()
+    servers = {}
+
+    for name, srv in BUILTIN_SERVERS.items():
+        data = dict(srv)
+        data["is_installed"] = check_server_installed(data)
+        servers[name] = data
+
+    # Discover custom user plugins in ~/.mcp-win-stdio/plugins
+    if PLUGINS_DIR.exists():
+        for item in PLUGINS_DIR.glob("*.py"):
+            if item.name.startswith("__"):
+                continue
+            plugin_name = item.stem
+            servers[plugin_name] = {
+                "name": plugin_name,
+                "title": f"User Plugin: {plugin_name}",
+                "path": str(item),
+                "module": None,
+                "description": f"Custom user plugin script loaded from {item}",
+                "tools_count": "dynamic",
+                "is_builtin": False,
+                "is_installed": True,
+                "required_pip": [],
+                "dependencies": [],
+                "optional_dependencies": [],
+            }
+    return servers
+
+
+def get_server_info(name: str) -> Optional[Dict[str, Any]]:
+    """Get metadata and live installation status for a specific server."""
+    servers = list_available_servers()
+    return servers.get(name.lower())