Metadata-Version: 2.5
Name: mcp-win-stdio
Version: 0.3.0
Summary: Windows-optimized Model Context Protocol (MCP) suite & interactive CLI hub for Claude Desktop & Claude Code CLI (Excel COM, Word layouts, Workspace Explorer, and TypeScript diagnostic watcher).
Author: Mohan Kumar Indala
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,excel,llm,mcp,stdio,typescript,windows,word,workspace-explorer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
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>=1.2.0
Provides-Extra: all
Requires-Dist: mcp-win-stdio-db>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-excel-db>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-excel>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-explorer>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-git>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-rag>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-ssh>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-tsc>=0.3.0; extra == 'all'
Requires-Dist: mcp-win-stdio-word>=0.3.0; extra == 'all'
Provides-Extra: db
Requires-Dist: mcp-win-stdio-db>=0.3.0; extra == 'db'
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: hatchling>=1.25.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: excel
Requires-Dist: mcp-win-stdio-excel>=0.3.0; extra == 'excel'
Provides-Extra: excel-db
Requires-Dist: mcp-win-stdio-excel-db>=0.3.0; extra == 'excel-db'
Provides-Extra: explorer
Requires-Dist: mcp-win-stdio-explorer>=0.3.0; extra == 'explorer'
Provides-Extra: git
Requires-Dist: mcp-win-stdio-git>=0.3.0; extra == 'git'
Provides-Extra: rag
Requires-Dist: mcp-win-stdio-rag>=0.3.0; extra == 'rag'
Provides-Extra: ssh
Requires-Dist: mcp-win-stdio-ssh>=0.3.0; extra == 'ssh'
Provides-Extra: tsc
Requires-Dist: mcp-win-stdio-tsc>=0.3.0; extra == 'tsc'
Provides-Extra: word
Requires-Dist: mcp-win-stdio-word>=0.3.0; extra == 'word'
Description-Content-Type: text/markdown

# mcp-win-stdio

Windows-optimized **Model Context Protocol (MCP)** suite and interactive CLI hub (`mws`) for local `stdio` execution with transparent Claude Desktop & Claude Code CLI configuration.

[![PyPI Version](https://img.shields.io/pypi/v/mcp-win-stdio.svg)](https://pypi.org/project/mcp-win-stdio/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)

---

## 🌟 Highlights (220+ Tools Across 10 Modular Servers)

* **Unified On-Demand Gateway Server (`mws server`)**: Configure just `mws server` (or `python -m mcp_win_stdio.server`) in Claude Desktop, Cursor, or Antigravity. Instead of dumping 200+ tools (30,000+ tokens) into the context window, it exposes 6 lightweight meta-tools (~400 tokens) that lazily spawn, cache, and proxy child servers on demand!
* **100% Dynamic & Zero-Env Architecture**: All configurations (databases, TypeScript projects, SSH hosts, Git repositories) are managed interactively and stored in `~/.mcp-win-stdio/`. No environment variables (`SERVERS`, `DATABASE_URL`, `TSC_WATCH_DIR`) required in client configs!
* **Interactive CLI Hub (`mws`)**: Run `mws` alone to view all servers, live installation status (`[Installed]` vs `[Not Installed]`), and quick commands.
* **Agent-Ready Project Bootstrap (`mws init`)**: Sets up installed servers for the current project, creates client-readable MCP and agent guidance files, adds safe `.env.example` scaffolding, and preserves user-authored files. Supports Codex, Antigravity, Claude, Copilot, Cursor, and Windsurf.
* **Safe Global Setup (`mws setup <server>` / `mws add <server>`)**: Installs missing dependencies on-demand and guides registration with Claude Desktop and Claude Code CLI.
* **Dynamic Guide Merging (`mws guide [server]`)**: View comprehensive tool schemas, prompt recipes, and diagnostic checks for individual servers (`mws excel-db guide`, `mws ssh guide`, `mws git guide`, `mws db guide`) or all installed servers merged (`mws guide all`).
* **Excel MCP (44 Tools)**: High-speed Pandas data queries, multi-column reconciliation with RapidFuzz, native styled Excel Tables (ListObjects), row/column structural mutations, formula templates, cell merging, workbook diffing, and native Windows Excel COM automation (PDF exports, recalculation, pivot refreshes, VBA macros).
* **Git & GitHub MCP (46 Tools)**: Unified local Git repository management (init, remotes, restore, bookmarks, branching, commits, paginated diffs, conflicts) and remote GitHub CLI (`gh`) operations (PR checks, releases, issues, Actions) with hybrid synergy workflows.
* **Multi-SSH & Remote Management MCP (34 Tools)**: Advanced multi-host connection pooling, auto-discovery of `~/.ssh/config` aliases/identity files/ProxyJump, sticky active host routing, command execution, elevated `sudo` automation, interactive PTY terminal sessions, detached background jobs, systemd/docker/pm2 service inspection, package listing, log tailing, comprehensive SFTP file management, and background local port forwarding tunnels.
* **Polyglot Database MCP (34 Tools)**: Unified PostgreSQL & MySQL database manager with dynamic connection hub (`~/.mcp-win-stdio/db_connections.json` shared with `excel-db`), cross-database switching, cross-schema auto-resolution, fast JSON queries, DBA administrative operations (safety-guarded DROP, CREATE, CLONE), active connection monitoring, index health audits, schema diffing with migration SQL, Mermaid ERD diagrams, row-level data diffing, slow queries, lock blocking trees, CSV/JSON streaming export, and transactional batch CSV import.
* **Word MCP (20 Tools)**: Multi-unit page layout geometry (margins in inches, cm, mm, pt), multi-column layout analysis, paragraph spacing/indentation, typography (fonts, sizes, hex colors), floating/inline header image extraction, document authoring, template placeholder filling, and native Word COM PDF export.
* **Workspace Explorer MCP (14 Tools)**: Token-safe directory exploration, collapsible heavy folders (`node_modules`, `.next`, `.git`), dynamic `.gitignore` parsing, in-file regex grep, RapidFuzz fuzzy search, and Python/TypeScript AST outline extraction.
* **Excel & DB Power Engine MCP (9 Tools)**: Zero-context streaming from database to Excel, chunked Excel-to-DB upserting, in-memory cross-source SQL joins, automated reconciliation diffs, multi-master datasets comparison with tolerance, transactional migration generation, and custom Python template pipelines.
* **TypeScript Diagnostic Watcher MCP (12 Tools)**: Persistent background `tsc` compiler watchers maintaining an in-memory cache for instantaneous (0ms latency) error inspection, dynamic multi-project workspace configuration (`list_projects`, `use_project`, `add_project`, `remove_project`), and actionable error fixes.
* **RAG MCP (10 Tools)**: Multi-collection web crawling, incremental local and zero-clone remote repository indexing, hybrid BM25 + TF-IDF search, related-chunk discovery, full-context retrieval, knowledge trees, and cache lifecycle management.
* **Extensible User Plugins**: Drop any standalone Python MCP script into `~/.mcp-win-stdio/plugins/` and it is immediately discovered, runnable, and configurable.

---

## 📦 Modular Architecture & Installation

Each server is published as an independent, lightweight PyPI package. Installing any standalone package automatically installs the `mws` CLI orchestrator.

| Server | Standalone Package | Tools | Primary Capabilities |
| :--- | :--- | :---: | :--- |
| **mws Server** | `pip install mcp-win-stdio` | 6 | Unified On-Demand Gateway & Dynamic Process Orchestrator (loads all servers on-demand, anti-bloat) |
| **Excel** | `pip install mcp-win-stdio-excel` | 44 | Native Excel Tables, row/col mutations, formulas, Pandas queries, RapidFuzz reconciliation, Office COM automation |
| **Git & GitHub** | `pip install mcp-win-stdio-git` | 46 | Local Git init/remotes/restore/bookmarks/branches, commits, diffs + GitHub PR checks, releases, issues, Actions |
| **SSH** | `pip install mcp-win-stdio-ssh` | 34 | Multi-host pooling, ~/.ssh/config discovery, PTY shells, background jobs, systemd/docker, package management, SFTP, tunnels |
| **Database** | `pip install mcp-win-stdio-db` | 34 | PostgreSQL & MySQL dynamic pooling, ~/.mcp-win-stdio config, cross-schema resolution, index audits, schema diffs, Mermaid ERD, slow queries, lock trees |
| **Word** | `pip install mcp-win-stdio-word` | 20 | Margins (in, cm, mm, pt), multi-column layout, typography, document authoring, template filling, Office COM PDF export |
| **Explorer** | `pip install mcp-win-stdio-explorer` | 14 | Token-safe collapsible tree, .gitignore resolution, in-file grep, AST outlines, fuzzy search |
| **Excel & DB** | `pip install mcp-win-stdio-excel-db` | 9 | Zero-context streaming, cross-joins, master reconciliation with tolerance, transactional migration plan, dry-run sync |
| **TypeScript** | `pip install mcp-win-stdio-tsc` | 12 | 0ms in-memory compilation error cache, dynamic multi-project config (add_project/use_project), multi-tsconfig watchers, fix suggestions |
| **RAG** | `pip install mcp-win-stdio-rag` | 10 | Web crawling, local/remote repo indexing, hybrid BM25 + TF-IDF search, context and collection lifecycle |

### Install Individual Servers:
```powershell
pip install mcp-win-stdio-excel
pip install mcp-win-stdio-git
pip install mcp-win-stdio-ssh
pip install mcp-win-stdio-db
pip install mcp-win-stdio-word
pip install mcp-win-stdio-explorer
pip install mcp-win-stdio-excel-db
pip install mcp-win-stdio-tsc
pip install mcp-win-stdio-rag
```

### Or Install the Complete Suite:
```powershell
pip install "mcp-win-stdio[all]"
```

### For Local Development:
```powershell
git clone https://github.com/indala/mcp-win-stdio.git
cd mcp-win-stdio
pip install -e .
```

---

## 🚀 Quick Start

### 1. Launch the Interactive Dashboard
```powershell
mws
```
Output:
```text
============================================================================
   🚀  mcp-win-stdio — Windows Model Context Protocol Suite (v0.3.0)
============================================================================

 Single-Source Hub:      C:\Users\admin\.mcp-win-stdio
 Claude Desktop Config:  C:\Users\admin\AppData\Roaming\Claude\claude_desktop_config.json
 Claude Code CLI Config: C:\Users\admin\.claude.json
----------------------------------------------------------------------------
SERVER       STATUS           TOOLS    DESCRIPTION
----------------------------------------------------------------------------
excel        [Installed]      20       20 tools: Pandas queries, RapidFuzz...
word         [Installed]      10       10 tools: multi-unit margins (in, cm...
explorer     [Installed]      11       11 tools: token-safe collapsible tree...
tsc          [Installed]      6        6 tools: background tsc compiler...
db           [Installed]      20       20 tools: polyglot multi-server p...
git          [Installed]      26       26 tools: Local Git branching, co...
----------------------------------------------------------------------------
 💡 Quick Commands:
   mws setup <server>    -> Configure Claude Desktop & Claude Code CLI
   mws guide <server>    -> View complete tool reference & Claude prompts
   mws doctor            -> Run health checks (COM, Python, DB, Git)
   mws run <server>      -> Launch MCP server over stdio
   mws list              -> Show concise server inventory
============================================================================
```

### 2. Configure a Server for Claude
```powershell
mws setup git
# or:
mws add db
```
`mws` verifies dependencies, generates absolute-path configurations (preventing Windows PATH lookup failures), and optionally writes directly to your Claude Desktop config with automatic backup.

---

## 📖 CLI Commands

| Command | Shorthand / Alternate Syntax | Description |
| :--- | :--- | :--- |
| `mws` | — | Opens the home dashboard with suite health, Claude client status, server overview, and quick commands. |
| `mws list` | — | Shows a focused inventory of built-in servers and custom plugins with install status and tool counts. |
| `mws install <server\|all>` | `mws <server> install` | Installs standalone server packages from PyPI. |
| `mws update <server\|all>` | `mws <server> update` | Checks PyPI for new versions and upgrades the suite or specific server. |
| `mws setup <server>` | `mws add <server>` / `mws <server> setup` | Guides setup, verifies dependencies, and generates Claude config snippets. |
| `mws init [servers...]` | `mws init codex [servers...]` | Bootstraps the current project for installed MCP servers; a client name configures that agent too. |
| `mws setup-project <servers...>` | `mws add-project <servers...>` | Adds or updates selected MCP servers in current-project configuration. |
| `mws status` | — | Reports project MCP configuration, installed servers, and environment readiness without changing files. |
| `mws remove <server>` | `mws <server> remove` | Safely removes server(s) from Claude Desktop and CLI configs. |
| `mws uninstall <server\|all>` | `mws <server> uninstall` | Cleanly uninstalls packages and removes Claude registrations while preserving your single-source hub (`~/.mcp-win-stdio`). |
| `mws guide [server]` | `mws <server> guide` | Prints tool reference, parameter schemas, and prompt recipes for Claude. |
| `mws doctor` | `mws <server> doctor` | Runs diagnostic health checks (Python, Git CLI, GitHub CLI, COM, DB drivers, PyPI updates). |
| `mws fix-path` | `mws path` | Checks and configures Python Scripts/bin directories in Windows User PATH. |
| `mws run <server>` | `mws <server> run` | Launches the MCP server over stdio. |


> [!TIP]
> If `mws` is not yet in Windows `PATH`, all commands can be executed using Python's module runner:
> ```powershell
> python -m mcp_win_stdio run git
> python -m mcp_win_stdio update all
> python -m mcp_win_stdio doctor
> ```

### What does `mws init` do versus `mws setup`?

* `mws init` (alias `mws init-project`) is **interactive project bootstrap**. It shows the target workspace and servers and asks before writing project config. It defaults to installed servers, then offers environment prompts for selected servers (for example a hidden `DATABASE_URL` prompt for `db`). Secrets are stored in ignored `.env`; `.env.example` stays secret-free. Use `--yes` to confirm without prompts. Existing project MCP entries and user-authored agent instructions are preserved.
* `mws setup <server>` (also `mws add <server>`) is **machine/client setup** for Claude Desktop and Claude Code. It checks or installs that server's package requirements and guides registration in Claude's user-level configuration. It does not bootstrap the current repository.
* `mws setup-project <servers...>` (also `mws add-project`) is the **incremental project operation**: it asks before adding only the named servers and their environment settings, without selecting all installed servers. `mws remove-project <servers...>` removes selected project registrations.

Examples:
```powershell
mws init                         # Review installed servers, confirm, then bootstrap project
mws init db                      # Confirm project setup; prompt for DATABASE_URL
mws init codex rag explorer      # Confirm those servers and configure Codex
mws setup rag                    # Install/check RAG and configure Claude
mws setup-project db             # Confirm and add only DB to this project
mws init db --yes                # Non-interactive; uses existing env/config without prompting
mws init db --dry-run            # Preview project changes without writing files
mws status                       # Inspect project/server/environment readiness
```


---

## 🛠️ The 6 MCP Servers (103 Tools)

### 🐙 1. Git & GitHub MCP (`mcp_win_stdio.git`) — 33 Tools
* **Local Git Suite (20 Tools)**: `git_init`, `git_remote`, `git_restore`, `use_repo`, `list_repos`, `add_repo`, `remove_repo`, `rename_alias`, `git_status`, `git_diff` (with offset pagination), `git_log`, `git_commit` (with untracked safeguards), `git_branch`, `git_stash`, `git_sync`, `git_blame`, `git_reset`, `git_tag`, `git_grep`, `git_worktree`, `git_config`, `git_conflict_resolve`, `git_cherry_pick`, `git_clean_untracked`.
* **Remote GitHub CLI Suite (10 Tools)**: `gh_auth_status`, `gh_switch_account`, `gh_pr_list`, `gh_pr_view`, `gh_pr_diff`, `gh_pr_checkout`, `gh_pr_action`, `gh_pr_checks`, `gh_pr_review_comments`, `gh_release_list`, `gh_release_create`, `gh_issue_list`, `gh_issue_view`, `gh_issue_create`, `gh_issue_comment`, `gh_run_status`, `gh_gist_create`, `gh_search`, `gh_api`.
* **Hybrid Synergy Workflows (3 Tools)**:
  * `repo_overview`: 360-degree status combining local branch, dirty status, ahead/behind tracking, active open PR, and latest GitHub Actions workflow run.
  * `pr_quickstart`: Stage $\rightarrow$ Commit $\rightarrow$ Push $\rightarrow$ Create PR via `gh pr create` in one turn.
  * `issue_start_work`: Fetches issue from GitHub and creates a linked local branch `feature/<id>-<slug>`.

### 🗄️ 2. Polyglot Database MCP (`mcp_win_stdio.db`) — 23 Tools
* **Inspection & Resolution**: `list_connections`, `use_database`, `list_databases`, `list_schemas`, `describe_table` (auto cross-schema lookup), `get_table_ddl`, `schema_overview`, `compact_schema_overview`, `get_table_sample`, `search_schema`.
* **Execution & Diagnostics**: `read_query` (safe SELECT with row counts), `execute_query` (DML/DDL transactions), `explain_query` (EXPLAIN plans), `get_database_stats`, `analyze_table_indexes`, `compare_schemas` (structural diff with migration SQL), `audit_database_health` (unindexed FKs, bloated tables).
* **DBA Management**: `add_connection`, `create_database`, `drop_database` (safety confirmation required), `clone_database` (instant PostgreSQL TEMPLATE clone), `terminate_connections`, `list_active_queries`.
* **Native Utilities**: `dump_database` (`pg_dump`/`mysqldump`), `restore_database` (`psql`/`mysql`).

### 📊 3. Excel MCP (`mcp_win_stdio.excel`) — 20 Tools
* **Pandas Querying**: `query_rows`, `read_range`, `get_column_values`, `compare_column_values`, `summarize_column`, `search_text`.
* **Reconciliation**: `analyze_reconciliation_keys`, `reconcile_and_merge` (RapidFuzz fuzzy joins + 3-tab audit workbook).
* **OpenPyXL Editing**: `create_workbook`, `append_rows`, `add_sheet`, `rename_sheet`, `delete_sheet`, `update_cells`, `export_to_csv`, `export_to_json`.
* **Native Windows Excel COM**: `recalculate_and_save`, `export_to_pdf`, `refresh_data_and_pivots`, `run_vba_macro`, `get_active_excel_window`.

### 📝 4. Word MCP (`mcp_win_stdio.word`) — 10 Tools
* **Layout Geometry**: `get_document_layout` (margins in inches, cm, mm, pt, paper format, multi-column layout, section breaks).
* **Typography & Spacing**: `get_paragraph_spacing_and_indentation`, `get_document_typography` (fonts, sizes in pt, hex colors).
* **Visuals & Tables**: `get_document_images` (inline vs floating anchor images, placement offsets, dimensions), `get_document_tables`, `get_headers_and_footers`.
* **Content & Search**: `read_word_document`, `search_word_document`, `get_document_outline`, `get_document_metadata`.

### 📁 5. Workspace Explorer MCP (`mcp_win_stdio.explorer`) — 11 Tools
* **Token-Safe Navigation**: `list_dir`, `get_directory_tree` (collapses `node_modules`, `.next`, `dist`, `.git`).
* **Search**: `find_files` (glob matching), `fuzzy_find` (RapidFuzz typo-tolerant search), `grep_search` (in-file regex grep with context lines).
* **Code Intelligence**: `get_code_outline` (AST extractor for Python classes/methods and JS/TS signatures), `get_file_info`, `workspace_summary`, `export_tree_to_file`.
* **Safe Reading**: `read_file` (windowed line slicing, binary safeguard), `read_head_tail`.

### ⚡ 6. TypeScript Diagnostic Watcher MCP (`mcp_win_stdio.tsc`) — 12 Tools
* **Dynamic Multi-Project Config**: `list_projects`, `use_project(alias_or_path)`, `add_project(path, alias)`, `remove_project(alias_or_path)`.
* **Instant Diagnostic Query**: `get_tsc_errors` (0ms in-memory cache), `get_file_errors`, `get_error_summary`, `get_error_category_breakdown`, `suggest_error_fixes`.
* **Dynamic Watchers**: `list_watched_projects`, `watch_project(path)`, `restart_tsc_watcher`.

---

## 🔌 Custom Plugins from Other PCs

Have custom Python MCP scripts?
Simply place your script into:
```text
%USERPROFILE%\.mcp-win-stdio\plugins\my_custom_mcp.py
```
`mcp-win-stdio` automatically discovers it:
* View it in `mws list` (or use `mws` for the full dashboard)
* Run it via `mws run my_custom_mcp`
* Add it to Claude via `mws setup my_custom_mcp`

---

## 📜 License
MIT License. Copyright (c) 2026 Mohan Kumar Indala.
