winterm-mcp 0.1.1__py3-none-any.whl

winterm_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""
+winterm-mcp - Windows Terminal MCP Service
+"""
+
+__version__ = "0.1.1"
+__author__ = "winterm-mcp contributors"

winterm_mcp/__main__.py

@@ -0,0 +1,19 @@
+"""
+winterm-mcp 主入口
+"""
+
+from .server import app, init_service
+from .service import RunCmdService
+
+
+def main():
+    """
+    主函数，启动 MCP 服务器
+    """
+    service = RunCmdService()
+    init_service(service)
+    app.run()
+
+
+if __name__ == "__main__":
+    main()

winterm_mcp/server.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import Annotated, Optional, Dict, Any
+from mcp.server.fastmcp import FastMCP
+from .service import RunCmdService
+from pydantic import Field
+
+CommandStr = Annotated[
+    str,
+    Field(
+        description="要执行的命令字符串",
+        min_length=1,
+        max_length=1000,
+    ),
+]
+
+ShellTypeStr = Annotated[
+    str,
+    Field(
+        description="Shell 类型 (powershell 或 cmd)，默认 powershell",
+        pattern="^(powershell|cmd)$",
+    ),
+]
+
+TimeoutInt = Annotated[
+    Optional[int],
+    Field(
+        description="超时秒数 (1-3600)，默认 30 秒",
+        ge=1,
+        le=3600,
+        default=30,
+    ),
+]
+
+WorkingDirectoryStr = Annotated[
+    Optional[str],
+    Field(
+        description="工作目录（可选，默认为当前目录）",
+        default=None,
+        max_length=1000,
+    ),
+]
+
+app = FastMCP("winterm-mcp")
+
+_service: Optional[RunCmdService] = None
+
+
+def init_service(service: RunCmdService) -> None:
+    global _service
+    _service = service
+
+
+def _svc() -> RunCmdService:
+    if _service is None:
+        raise RuntimeError(
+            "Service not initialized. "
+            "Call init_service() before running the server."
+        )
+    return _service
+
+
+@app.tool(
+    name="run_command",
+    description=(
+        "异步执行Windows终端命令，立即返回 token。"
+        "命令将在后台执行，可通过 query_command_status 查询结果。"
+    ),
+    annotations={
+        "title": "异步命令执行器",
+        "readOnlyHint": False,
+        "destructiveHint": True,
+        "idempotentHint": False,
+        "openWorldHint": True,
+    },
+)
+def run_command(
+    command: CommandStr,
+    shell_type: ShellTypeStr = "powershell",
+    timeout: TimeoutInt = 30,
+    working_directory: WorkingDirectoryStr = None,
+) -> Dict[str, Any]:
+    """
+    异步执行Windows终端命令
+
+    Args:
+        command: 要执行的命令
+        shell_type: Shell 类型 (powershell 或 cmd)，默认 powershell
+        timeout: 超时秒数 (1-3600)，默认 30 秒
+        working_directory: 工作目录（可选，默认为当前目录）
+
+    Returns:
+        包含token和状态信息的字典
+    """
+    try:
+        token = _svc().run_command(
+            command, shell_type, timeout, working_directory
+        )
+        return {"token": token, "status": "pending", "message": "submitted"}
+    except Exception as e:
+        return {"error": str(e)}
+
+
+@app.tool(
+    name="query_command_status",
+    description=("查询命令执行状态和结果。" "返回命令的当前状态、退出码、输出等信息。"),
+    annotations={
+        "title": "命令状态查询器",
+        "readOnlyHint": True,
+        "destructiveHint": False,
+        "idempotentHint": True,
+        "openWorldHint": False,
+    },
+)
+def query_command_status(token: str) -> Dict[str, Any]:
+    """
+    查询命令执行状态和结果
+
+    Args:
+        token: 任务 token (GUID 字符串)
+
+    Returns:
+        包含命令状态和结果的字典
+    """
+    try:
+        result = _svc().query_command_status(token)
+        return result
+    except Exception as e:
+        return {"error": str(e)}

winterm_mcp/service.py

@@ -0,0 +1,182 @@
+"""
+winterm服务模块 - 异步执行Windows终端命令服务
+"""
+
+import subprocess
+import threading
+import uuid
+import time
+from datetime import datetime
+from typing import Dict, Optional, Any
+
+
+class RunCmdService:
+    """
+    异步命令执行服务类，管理所有异步命令的执行和状态
+    """
+
+    def __init__(self):
+        self.commands: Dict[str, Dict[str, Any]] = {}
+        self.lock = threading.Lock()
+
+    def run_command(
+        self,
+        command: str,
+        shell_type: str = "powershell",
+        timeout: int = 30,
+        working_directory: Optional[str] = None,
+    ) -> str:
+        """
+        异步运行命令
+
+        Args:
+            command: 要执行的命令
+            shell_type: Shell 类型 (powershell 或 cmd)
+            timeout: 超时时间（秒）
+            working_directory: 工作目录
+
+        Returns:
+            命令执行的token
+        """
+        token = str(uuid.uuid4())
+
+        cmd_info = {
+            "token": token,
+            "command": command,
+            "shell_type": shell_type,
+            "status": "pending",
+            "start_time": datetime.now(),
+            "timeout": timeout,
+            "working_directory": working_directory,
+            "stdout": "",
+            "stderr": "",
+            "exit_code": None,
+            "execution_time": None,
+            "timeout_occurred": False,
+        }
+
+        with self.lock:
+            self.commands[token] = cmd_info
+
+        thread = threading.Thread(
+            target=self._execute_command,
+            args=(token, command, shell_type, timeout, working_directory),
+        )
+        thread.daemon = True
+        thread.start()
+
+        return token
+
+    def _execute_command(
+        self,
+        token: str,
+        command: str,
+        shell_type: str,
+        timeout: int,
+        working_directory: Optional[str],
+    ):
+        """
+        在单独线程中执行命令
+        """
+        try:
+            start_time = time.time()
+
+            with self.lock:
+                if token in self.commands:
+                    self.commands[token]["status"] = "running"
+
+            encoding = "utf-8" if shell_type == "powershell" else "gbk"
+
+            if shell_type == "powershell":
+                cmd_args = ["powershell", "-Command", command]
+            else:
+                cmd_args = ["cmd", "/c", command]
+
+            result = subprocess.run(
+                cmd_args,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                cwd=working_directory,
+                encoding=encoding,
+            )
+
+            execution_time = time.time() - start_time
+
+            with self.lock:
+                if token in self.commands:
+                    self.commands[token].update(
+                        {
+                            "status": "completed",
+                            "stdout": result.stdout,
+                            "stderr": result.stderr,
+                            "exit_code": result.returncode,
+                            "execution_time": execution_time,
+                        }
+                    )
+
+        except subprocess.TimeoutExpired:
+            execution_time = time.time() - start_time
+            with self.lock:
+                if token in self.commands:
+                    self.commands[token].update(
+                        {
+                            "status": "completed",
+                            "stdout": "",
+                            "stderr": (
+                                f"Command timed out after {timeout} seconds"
+                            ),
+                            "exit_code": -1,
+                            "execution_time": execution_time,
+                            "timeout_occurred": True,
+                        }
+                    )
+        except Exception as e:
+            execution_time = time.time() - start_time
+            with self.lock:
+                if token in self.commands:
+                    self.commands[token].update(
+                        {
+                            "status": "completed",
+                            "stdout": "",
+                            "stderr": str(e),
+                            "exit_code": -1,
+                            "execution_time": execution_time,
+                            "timeout_occurred": False,
+                        }
+                    )
+
+    def query_command_status(self, token: str) -> Dict[str, Any]:
+        """
+        查询命令执行状态
+
+        Args:
+            token: 命令的token
+
+        Returns:
+            包含命令状态的字典
+        """
+        with self.lock:
+            if token not in self.commands:
+                return {
+                    "token": token,
+                    "status": "not_found",
+                    "message": "Token not found",
+                }
+
+            cmd_info = self.commands[token].copy()
+
+            if cmd_info["status"] == "running":
+                return {"token": cmd_info["token"], "status": "running"}
+            elif cmd_info["status"] in ["completed", "pending"]:
+                return {
+                    "token": cmd_info["token"],
+                    "status": cmd_info["status"],
+                    "exit_code": cmd_info["exit_code"],
+                    "stdout": cmd_info["stdout"],
+                    "stderr": cmd_info["stderr"],
+                    "execution_time": cmd_info["execution_time"],
+                    "timeout_occurred": cmd_info["timeout_occurred"],
+                }
+            else:
+                return cmd_info

winterm_mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: winterm-mcp
+Version: 0.1.1
+Summary: A Model Context Protocol (MCP) service for executing Windows terminal commands asynchronously
+Author-email: winterm-mcp contributors <maintainer@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/username/winterm-mcp
+Project-URL: Repository, https://github.com/username/winterm-mcp
+Project-URL: Documentation, https://github.com/username/winterm-mcp/blob/main/README.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# winterm-mcp
+
+**更新日期**: 2026-01-16  
+**版本**: 0.1.1
+
+Windows Terminal MCP Service - 专门支持 Windows 终端的异步命令执行工具。
+
+## 功能特性
+
+- **PowerShell 支持**: 直接执行 PowerShell 命令（默认）
+- **Cmd 支持**: 可选执行 cmd 命令
+- **异步执行**: 后台执行命令，立即返回 token
+- **状态查询**: 查询命令执行状态和结果
+- **超时控制**: 可设置超时时间（1-3600秒）
+- **工作目录**: 指定执行目录
+- **自动编码**: 自动处理 PowerShell (UTF-8) 和 Cmd (GBK) 编码
+
+## 安装
+
+```bash
+cd winterm_mcp_standalone
+pip install -e .
+```
+
+## 使用方法
+
+### MCP 配置
+
+在 MCP 客户端配置中添加：
+
+```json
+{
+  "mcpServers": {
+    "winterm-mcp": {
+      "command": "winterm-mcp"
+    }
+  }
+}
+```
+
+### 工具接口
+
+#### run_command
+
+异步执行 Windows 终端命令。
+
+**参数**:
+- `command` (string): 要执行的命令（必填，1-1000字符）
+- `shell_type` (string, optional): Shell 类型，`powershell` 或 `cmd`，默认 `powershell`
+- `timeout` (integer, optional): 超时秒数（1-3600），默认 30
+- `working_directory` (string, optional): 工作目录（可选，默认当前目录）
+
+**返回**:
+```json
+{
+  "token": "uuid-string",
+  "status": "pending",
+  "message": "submitted"
+}
+```
+
+#### query_command_status
+
+查询命令执行状态和结果。
+
+**参数**:
+- `token` (string): 命令 token
+
+**返回**:
+```json
+{
+  "token": "uuid-string",
+  "status": "completed",
+  "exit_code": 0,
+  "stdout": "command output",
+  "stderr": "",
+  "execution_time": 0.123,
+  "timeout_occurred": false
+}
+```
+
+## 使用示例
+
+### PowerShell 命令
+
+```python
+# 获取当前日期
+run_command("Get-Date")
+
+# 列出进程
+run_command("Get-Process | Select-Object -First 5")
+
+# 构建项目
+run_command("dotnet build", timeout=60, working_directory="d:/project")
+```
+
+### Cmd 命令
+
+```python
+# 列出目录
+run_command("dir", shell_type="cmd")
+
+# Ping 测试
+run_command("ping 127.0.0.1 -n 4", shell_type="cmd")
+```
+
+### 查询命令状态
+
+```python
+# 提交命令
+result = run_command("Get-Process")
+token = result["token"]
+
+# 查询状态
+status = query_command_status(token)
+if status["status"] == "completed":
+    print(status["stdout"])
+```
+
+## 技术架构
+
+- **框架**: FastMCP
+- **并发**: 多线程异步执行
+- **编码**: 自动处理 UTF-8 和 GBK
+- **平台**: Windows
+
+## 与 runcmd-mcp 的区别
+
+| 特性 | runcmd-mcp | winterm-mcp |
+|------|-----------|-------------|
+| Shell 类型 | 仅 cmd | PowerShell + Cmd |
+| Windows 支持 | 部分 | 完整 |
+| 编码处理 | 固定 | 自动适配 |
+| 平台 | 跨平台 | Windows 专用 |
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request。

winterm_mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+winterm_mcp/__init__.py,sha256=2Z5_ooE56FyBhidVPwkvcWPyl4ONfzi5ZRmmg2RvUm4,120
+winterm_mcp/__main__.py,sha256=aCm888vzPOYtBDLtV02zAKkjIhrFAd2xB-TZAl4qHCc,300
+winterm_mcp/server.py,sha256=JEZc6NJeOrMuZejV6aho1UINZEOTDWNor3YYEdzPWCI,3204
+winterm_mcp/service.py,sha256=m6EZrxH99HoRzeriDPeY0iGRjmmH-rnkjJ5MiLnEWtQ,5624
+winterm_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=GPZ4VAbf_gxeFMSUHCmNQING30GK0kNduK8EJIO5-gc,1081
+winterm_mcp-0.1.1.dist-info/METADATA,sha256=RpV-V8oLCHhCP1rzGZl0UMMFkSHFDO_8RfCMGWsKdjo,4052
+winterm_mcp-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+winterm_mcp-0.1.1.dist-info/entry_points.txt,sha256=0OGioH1DKGxuxvSFD1OCRcbLoutfqdEPmJy_j2GhJTA,113
+winterm_mcp-0.1.1.dist-info/top_level.txt,sha256=S7w96DR3MB-CMIuXLnrMOvs5ApqPF-2PsAcfVCphCHw,12
+winterm_mcp-0.1.1.dist-info/RECORD,,

winterm_mcp-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

winterm_mcp-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+winterm-mcp = winterm_mcp.__main__:main
+
+[mcp.servers]
+winterm-mcp = winterm_mcp.__main__:main

winterm_mcp-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 winterm-mcp contributors
+
+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.

winterm_mcp-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+winterm_mcp