Pwsh MCP Demo

PowerShell MCP服务器演示

  

在PowerShell中实现的模型上下文协议（MCP）服务器的轻量级、易于理解的演示。此服务器通过标准化的MCP接口公开PowerShell系统信息和管理功能，使AI助手能够与Windows环境交互。

目录

• 概述
• 特性
• 先决条件
• 安装
• 快速开始
• 配置
• 用法

- 可用工具 - 可用资源 - 示例提示

• 建筑
• API 参考
• 故障排除
• 贡献
• 许可证
• 支持

概述

本项目演示了如何使用PowerShell构建功能强大的MCP（模型上下文协议）服务器。服务器通过JSON-RPC在stdin/stdout上进行通信，使其与启用MCP的AI助手兼容，如Claude Desktop、Cline和其他MCP客户端。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，使AI助手能够安全地与本地工具和数据源进行交互。此服务器实现展示了：

• JSON-RPC 2.0 通过stdio进行通信
• 工具暴露 用于PowerShell操作
• 资源管理 获取工作空间信息
• 内容长度框架 JSON行回退
• 最小依赖性 便于理解和修改

为什么选择PowerShell？

PowerShell提供对Windows系统信息的本机访问，使其非常适合：

• 系统管理任务
• 模块和服务管理
• 配置检查
• 跨平台脚本编写（PowerShell核心）

特性

✨ 核心能力

• 配置文件状态检查 -检查所有作用域中的PowerShell配置文件
• 模块发现 -使用模式筛选列出已安装的PowerShell模块
• 服务管理 -按状态查询具有可配置限制的Windows服务
• 工作区信息 -访问当前目录、用户和环境详细信息

🔧 技术特性

• 双重运输模式 -支持内容长度框架和JSON行
• 自动检测 -自动检测传输协议
• 调试日志记录 -全面记录到stderr以进行故障排除
• 错误处理 -JSON-RPC错误代码的稳健错误响应
• 可配置限制 -使用合理的默认值防止资源耗尽

先决条件

所需软件

• PowerShell 7.0或更高版本 （PowerShell核心）

- 下载： PowerShell发布 - 验证安装： pwsh --version

• MCP兼容客户端 （以下之一）：

- 克劳德桌面版 -Anthropic的桌面应用程序 - 临床VSCode扩展 - 任何支持stdio传输的MCP兼容客户端

操作系统

• Windows 10/11 -功能齐全（所有工具可用）
• macOS/Linux -部分功能（仅配置文件和模块工具；维修工具不可用）

可选依赖关系

• Visual Studio Code -用于开发和调试
• Git -用于克隆存储库

安装

选项1：克隆存储库

# Clone or download the repository to your local machine

# Navigate to the directory
cd pwsh-mcp-demo

# Verify the server script exists
Test-Path ./mcp-server.ps1

选项2：手动下载

1. 下载 mcp-server.ps1 来自此存储库
2. 将其保存到您选择的目录
3. 注意配置的完整路径

验证安装

# Test the server responds to input
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | pwsh ./mcp-server.ps1

您应该看到一个包含服务器信息的JSON响应。

快速开始

让服务器在5分钟内运行：

步骤1：配置MCP客户端

适用于克劳德桌面

编辑您的Claude Desktop配置文件：

窗户： %APPDATA%\Claude\claude_desktop_config.json

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加此服务器配置：

{
  "mcpServers": {
    "pwsh-mcp-demo": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "C:/path/to/pwsh-mcp-demo/mcp-server.ps1"
      ],
      "env": {
        "MCP_DEBUG": "true",
        "MCP_TRANSPORT_MODE": "auto"
      }
    }
  }
}

重要提示： 替换 C:/path/to/pwsh-mcp-demo/mcp-server.ps1 使用服务器脚本的实际路径。

对于Cline（VSCode扩展）

创建或编辑 .vscode/mcp.json 在您的工作空间中：

{
  "servers": {
    "pwsh-mcp-demo": {
      "type": "stdio",
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "${workspaceFolder}/mcp-server.ps1"
      ],
      "env": {
        "MCP_DEBUG": "true",
        "MCP_TRANSPORT_MODE": "auto"
      }
    }
  }
}

步骤2：重新启动MCP客户端

• 克劳德桌面： 完全退出并重新启动应用程序
• 克莱恩： 重新加载VSCode窗口(Ctrl+Shift+P → “开发人员：重新加载窗口”）

步骤3：测试连接

在MCP客户端中尝试以下提示：

Check my PowerShell profile status

List installed PowerShell modules matching Az*

Show me 10 running Windows services

如果你看到结果，恭喜你！您的MCP服务器正在工作。 🎉

配置

环境变量

服务器支持多种环境变量进行自定义：

交通方式详解

• auto -自动检测Content-Length标头或回退到JSON行
• content-length -力内容长度框架（建议用于生产）
• jsonl -强制使用换行符分隔的JSON（适用于手动测试）

调试日志记录

当 MCP_DEBUG=true，服务器将详细日志写入stderr：

[2026-02-16 20:35:27.123] [STARTUP] Starting pwsh-mcp-demo 1.0.0
[2026-02-16 20:35:27.456] [INFO] Received: {"jsonrpc":"2.0","id":1,"method":"initialize"...}
[2026-02-16 20:35:27.789] [INFO] Sent: {"jsonrpc":"2.0","id":1,"result":{...}}

提示： 禁用生产中的调试日志记录以获得更好的性能：

"env": {
  "MCP_DEBUG": "false"
}

执行策略

服务器使用 -ExecutionPolicy Bypass 以确保脚本在没有策略限制的情况下运行。这是安全的，因为：

• 服务器只执行自己的代码
• 未加载外部脚本
• 用户输入经过验证和净化

用法

可用工具

服务器通过MCP接口公开三个PowerShell工具：

1. get_powershell_profile_status

检索所有作用域中有关PowerShell配置文件的信息。

参数： 无

退货： 包含配置文件信息的JSON数组，包括：

• 配置文件范围名称
• 完整文件路径
• 存在状态
• 文件大小（如果存在）
• 上次修改的时间戳（如果存在）

输出示例：

[
  {
    "profile": "CurrentUserCurrentHost",
    "path": "C:\\Users\\YourName\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1",
    "exists": true,
    "length": 2048,
    "lastWriteTime": "2026-02-15T10:30:00"
  },
  {
    "profile": "AllUsersAllHosts",
    "path": "C:\\Program Files\\PowerShell\\7\\profile.ps1",
    "exists": false,
    "length": null,
    "lastWriteTime": null
  }
]

2. list_installed_modules

列出已安装的具有可选通配符筛选的PowerShell模块。

参数：

退货： JSON模块数组（最多200个），包含：

• 模块名称
• 版本号
• 模块基础路径
• PowerShell版本兼容性

输出示例：

[
  {
    "Name": "Az.Accounts",
    "Version": "2.15.1",
    "ModuleBase": "C:\\Program Files\\PowerShell\\Modules\\Az.Accounts\\2.15.1",
    "PSEdition": "Core"
  },
  {
    "Name": "Az.Storage",
    "Version": "6.1.0",
    "ModuleBase": "C:\\Program Files\\PowerShell\\Modules\\Az.Storage\\6.1.0",
    "PSEdition": "Core"
  }
]

3. get_windows_services

使用状态筛选和结果限制查询Windows服务。

参数：

退货： JSON服务数组，包含：

• 服务名称
• 显示名称
• 当前状态
• 服务类型

输出示例：

[
  {
    "Name": "EventLog",
    "DisplayName": "Windows Event Log",
    "Status": 4,
    "ServiceType": 16
  },
  {
    "Name": "Winmgmt",
    "DisplayName": "Windows Management Instrumentation",
    "Status": 4,
    "ServiceType": 16
  }
]

注： 状态代码： 1 =已停止， 4 =跑步

可用资源

workspace://info

提供当前工作区和环境信息。

URI： workspace://info

MIME类型： application/json

退货：

{
  "currentDirectory": "C:\\Users\\YourName\\Projects\\pwsh-mcp-demo",
  "timestamp": "2026-02-16 20:35:27",
  "environment": {
    "user": "YourName",
    "computer": "DESKTOP-ABC123"
  }
}

示例提示

在MCP客户端上使用这些自然语言提示与服务器交互：

配置文件管理

Check my PowerShell profile files and tell me which ones exist

Show me the size and last modified date of my PowerShell profiles

模块发现

List all installed PowerShell modules matching Az*

What PowerShell modules are installed on this system?

服务管理

List 25 running Windows services

Show me 50 stopped services

Get 10 services regardless of status

工作区信息

Read workspace://info and show me the current directory

What's my current workspace information?

多步操作

First check my PowerShell profiles, then list Az* modules, and summarize both

Get workspace info and list 15 running services, then create a system report

建筑

高级设计

┌─────────────────────────────────────────────────────────────┐
│                        MCP Client                           │
│                  (Claude Desktop / Cline)                   │
└────────────────────────┬────────────────────────────────────┘
                         │ JSON-RPC over stdio
                         │ (Content-Length or JSON-lines)
                         ↓
┌─────────────────────────────────────────────────────────────┐
│                   PowerShell MCP Server                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Transport Layer                        │  │
│  │  • Read-Message (stdin)                            │  │
│  │  • Write-Response (stdout)                         │  │
│  │  • Content-Length detection                        │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Request Router                         │  │
│  │  • Invoke-Request (method dispatcher)              │  │
│  │  • JSON-RPC validation                             │  │
│  │  • Error handling                                  │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              Business Logic                         │  │
│  │  • Invoke-Tool (tool implementations)              │  │
│  │  • Get-ResourceContent (resource handler)          │  │
│  └─────────────────────────────────────────────────────┘  │
│                         ↓                                   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │              PowerShell APIs                        │  │
│  │  • $PROFILE (profile paths)                        │  │
│  │  • Get-Module (module listing)                     │  │
│  │  • Get-Service (service queries)                   │  │
│  └─────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

请求的生命周期

1. 阅读 -服务器从stdin读取JSON-RPC请求
2. 解析 -请求被解析并验证为JSON
3. 路线 -方法被分派给适当的处理程序
4. 执行 -工具或资源逻辑运行
5. 回应 -JSON-RPC响应被写入stdout

关键组件

设计原则

• 简洁 -最小化抽象，易于理解
• 明确性 -明确功能名称和控制流程
• 模块化 -单独关注点（传输、路由、逻辑）
• 鲁棒性 -全面的错误处理
• 调试性 -用于故障排除的详细日志记录

API 参考

支持的MCP方法

JSON-RPC错误代码

请求/响应对示例

初始化会话

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05"
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "pwsh-mcp-demo",
      "version": "1.0.0"
    },
    "capabilities": {
      "tools": {},
      "resources": {}
    }
  }
}

列出工具

请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

答复：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_powershell_profile_status",
        "description": "Get PowerShell profile paths and whether they exist",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      },
      {
        "name": "list_installed_modules",
        "description": "List installed PowerShell modules with optional name pattern filtering",
        "inputSchema": {
          "type": "object",
          "properties": {
            "namePattern": {
              "type": "string",
              "description": "Wildcard pattern for module names (for example: Az* or Pester*)"
            }
          }
        }
      },
      {
        "name": "get_windows_services",
        "description": "List Windows services filtered by status",
        "inputSchema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "description": "Service status filter: all, running, or stopped",
              "enum": ["all", "running", "stopped"]
            },
            "limit": {
              "type": "integer",
              "description": "Maximum number of services to return (default 25, max 200)"
            }
          }
        }
      }
    ]
  }
}

呼叫工具

请求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_windows_services",
    "arguments": {
      "status": "running",
      "limit": 5
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"Name\":\"EventLog\",\"DisplayName\":\"Windows Event Log\",\"Status\":4,\"ServiceType\":16},{\"Name\":\"Winmgmt\",\"DisplayName\":\"Windows Management Instrumentation\",\"Status\":4,\"ServiceType\":16}]"
      }
    ]
  }
}

故障排除

常见问题

服务器未出现在MCP客户端中

症状： 服务器未显示在Claude Desktop或Cline中

解决：

1. 验证配置文件位置：

- 克劳德桌面：检查 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS） - Cline：检查 .vscode/mcp.json 在您的工作空间中

1. 验证JSON语法：

   # Test JSON validity
   Get-Content claude_desktop_config.json | ConvertFrom-Json

1. 检查文件路径：

   # Verify server script exists
   Test-Path "C:/path/to/mcp-server.ps1"

1. 完全重新启动客户端：

- Claude Desktop：完全退出应用程序，然后重新启动 - Cline：重新加载VSCode窗口

服务器启动，但工具不起作用

症状： 服务器已连接，但工具调用失败或超时

解决：

1. 启用调试日志记录：

   "env": {
     "MCP_DEBUG": "true"
   }

1. 检查stderr输出：

- 在调试日志中查找错误消息 - 常见问题：权限错误、缺少cmdlet

1. 手动测试服务器：

   # Send test request
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | pwsh ./mcp-server.ps1

1. 验证PowerShell版本：

   pwsh --version  # Should be 7.0 or later

权限错误

症状： “执行策略”或“拒绝访问”错误

解决：

1. 使用 -ExecutionPolicy Bypass:

   "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "path/to/mcp-server.ps1"]

1. 以管理员身份运行（如果需要）：

- 右键单击MCP客户端→ “以管理员身份运行”

1. 检查文件权限：

   Get-Acl ./mcp-server.ps1 | Format-List

交通/通讯问题

症状： 服务器启动但没有响应，或输出混乱

解决：

1. 力内容长度模式：

   "env": {
     "MCP_TRANSPORT_MODE": "content-length"
   }

1. 检查输出干扰：

- 确保没有配置文件脚本写入stdout - 使用 -NoProfile 标志（已在示例中）

1. 使用JSON行模式进行测试：

   "env": {
     "MCP_TRANSPORT_MODE": "jsonl"
   }

模块或服务查询返回空

症状： 工具执行但返回空数组

解决：

1. 验证是否安装了PowerShell模块：

   Get-Module -ListAvailable

1. 检查服务访问权限（仅限Windows）：

   Get-Service | Select-Object -First 5

1. 查看通配符模式：

- 使用 * 对于所有模块： namePattern: "*" - 请具体说明： namePattern: "Az*" 不 namePattern: "Az"

调试检查表

• \[\]PowerShell 7.0+已安装并可访问
• \[\]服务器脚本路径正确且绝对
• \[\]配置文件JSON有效
• \[\]MCP客户端已完全重新启动
• \[\]已启用调试日志记录(MCP_DEBUG=true)
• \[\]配置文件脚本不会干扰stdio
• \[\]执行策略允许执行脚本
• \[\]文件权限正确

获取帮助

如果您仍然遇到问题：

1. 启用调试日志 并捕获stderr输出
2. 手动测试服务器 使用echo命令
3. 检查MCP客户端日志 有关其他错误消息
4. 打开一个问题 在GitHub上使用：

- 您的配置文件（已清理） - 调试日志输出 - 重现步骤 - 预期行为与实际行为

贡献

欢迎投稿！该项目旨在具有教育性，易于修改。

如何做出贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/your-feature-name
3. 进行更改 带有明确的提交信息
4. 彻底测试 具有多个MCP客户端
5. 提交拉取请求 附有变更说明

贡献理念

• 🔧 添加新的PowerShell工具（注册表访问、进程管理等）
• 📚 用更多示例改进文档
• 🐛 修复错误或改进错误处理
• 🎨 添加可视化图表或屏幕截图
• 🧪 创建自动化测试
• 🌍 添加跨平台兼容性改进
• ⚡ 性能优化

代码风格指南

• 遵循PowerShell最佳实践
• 使用清晰、描述性的函数名称
• 为新功能添加基于注释的帮助
• 保持简单、有教育意义的设计
• 在Windows和跨平台场景下进行测试

报告问题

在报告问题时，请包括：

• 环境： 操作系统、PowerShell版本、MCP客户端
• 配置： 您的服务器配置（已清理）
• 复制步骤： 清晰、编号的步骤
• 预期行为： 应该发生什么
• 实际行为： 实际发生了什么
• 日志： 调试输出（如果可用）

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MIT许可证摘要

• ✅ 商业用途
• ✅ 修改
• ✅ 分布
• ✅ 私人使用
• ❌ 责任
• ❌ 保修

支持

文档

• MCP规范： 模型上下文协议
• PowerShell文档： Microsoft PowerShell文档
• JSON-RPC 2.0： JSON-RPC规范

社区

• GitHub问题： 报告存储库中的错误或请求功能
• GitHub讨论： 提出问题并分享想法

作者

由...创建 维奥雷尔·菲利克斯·丘库

致谢

• Anthropic -用于创建模型上下文协议
• PowerShell团队 -对于PowerShell核心
• MCP社区 -获取反馈和贡献

______________________________________________________________________

由以下材料制成❤️ PowerShell

_最后更新日期：2026年2月16日_