Lightweight PowerShell MCP framework

Módulo PowerShell para implementar um servidor MCP

PWSH MCP — Crie e exponha automação PowerShell como ferramentas MCP sob demanda.

Sumário

• Descrição
• Recursos
• Visão Geral da Arquitetura
• Casos de Uso
• Requisitos
• Compatibilidade
• Primeiros Passos
• Documentação
• Licença
• Referências

Descrição

O módulo PowerShell MCP permite criar servidores Model Context Protocol (MCP) diretamente a partir de funções PowerShell.

Em vez de escrever um servidor do zero, você define a funcionalidade como funções PowerShell e a expõe a clientes MCP por meio de JSON-RPC 2.0 sobre transporte stdio.

Escopo atual da implementação: ferramentas MCP sobre transporte stdio. Recursos, prompts e transportes baseados em HTTP não são implementados.

Esta abordagem é útil para desenvolvimento, gerenciamento de infraestrutura e cenários de automação CI/CD onde scripts PowerShell já existem e precisam ser expostos como ferramentas estruturadas para assistentes de IA.

Por que PowerShell para servidores MCP:

O PowerShell combina um ecossistema de automação maduro com suporte multiplataforma.

• Reutilize automação existente – exponha scripts estabelecidos e módulos como Azure, AWS, VMware, Active Directory e ferramentas Exchange sem reescrevê-los.
• Integração multiplataforma – execute o mesmo servidor MCP no Windows, Linux e macOS.
• Ferramentas testáveis e validadas – teste funções de forma independente com Pester e use atributos de parâmetro nativos para validação declarativa de entrada.
• Esquemas orientados por metadados – use Ajuda Baseada em Comentários e atributos de parâmetro para manter a documentação alinhada com o JSON Schema gerado automaticamente.

Recursos

• Implementação pura em PowerShell – sem dependências de runtime externas, aproveita os recursos nativos do PowerShell.
• Servidor MCP baseado em stdio – implementação de transporte stdio para integração com clientes MCP como GitHub Copilot e Gemini CLI.
• Suporte multiplataforma – comportamento consistente entre plataformas (Windows, Linux, macOS) com o mesmo código-fonte.
• Geração automática de esquemas – converte tipos de parâmetros de funções PowerShell suportados e Ajuda Baseada em Comentários em definições JSON Schema para ferramentas MCP.
• Validação de parâmetros – aproveita os atributos declarativos de validação do PowerShell para entradas de ferramentas MCP com segurança de tipos.

Visão Geral da Arquitetura

O módulo implementa o ciclo de vida do MCP sobre stdio e JSON-RPC 2.0:

• Transporte stdio – a comunicação ocorre exclusivamente por stdin/stdout; nenhum endpoint HTTP é necessário.
• JSON-RPC 2.0 – solicitações e respostas seguem a especificação JSON-RPC 2.0 com validação rigorosa e códigos de erro previsíveis.
• Descoberta de ferramentas (tools/list) – descobre e exporta funções PowerShell selecionadas como ferramentas MCP, incluindo seus esquemas e metadados.
• Execução de ferramentas (tools/call) – chamadas de ferramentas MCP recebidas são mapeadas para invocações de funções PowerShell, com vinculação e validação automática de parâmetros.
• Inicialização e encerramento – suporta os métodos principais do MCP.

Considerações de segurança:

• Sanitização de solicitações recebidas para evitar execução não intencional de comandos acionada por entradas geradas por IA.
• A validação de parâmetros de funções garante que as entradas correspondam aos tipos, intervalos e padrões esperados.
• Aproveita recursos nativos de segurança do PowerShell, como assinatura de scripts e políticas de execução.
• O servidor MCP pode ser executado dentro de um contêiner Docker para isolamento adicional ao expor capacidades de automação.

Casos de Uso

Cenários típicos incluem:

• Desenvolvimento rápido de ferramentas – converta scripts administrativos existentes em ferramentas MCP reutilizáveis ou prototipe utilitários específicos da equipe.
• Automação DevOps e CI/CD – exponha pipelines de implantação, fluxos de trabalho de infraestrutura como código, artefatos de build, portões de liberação e etapas de validação.
• Gerenciamento de infraestrutura – gerencie recursos em nuvem e locais, ou crie fluxos de trabalho de monitoramento e alertas com módulos PowerShell existentes.
• Automação empresarial – integre sistemas baseados em REST ou SDK, verificações de conformidade, pipelines de auditoria, relatórios e análises.

Requisitos

• PowerShell 7.5 ou posterior (multiplataforma)
• Cliente MCP que suporte transporte stdio (Visual Studio Code com GitHub Copilot, Gemini CLI, Copilot CLI).

Compatibilidade

Qualquer cliente compatível com MCP que implemente o transporte stdio do MCP e os métodos principais do MCP deve conseguir se conectar a um servidor PowerShell MCP com a configuração apropriada.

O repositório atualmente inclui documentação e exemplos para os seguintes clientes MCP:

• GitHub Copilot – assistente de codificação com IA.
• GitHub Copilot CLI – configuração do servidor MCP.
• Gemini CLI – assistente de IA de linha de comando com suporte a MCP.
• Claude Desktop – configuração local do servidor MCP.

Primeiros Passos

O projeto inclui exemplos prontos para uso e modelos de configuração para um início rápido. Para uso detalhado e configuração avançada, consulte o guia do usuário e o guia do desenvolvedor.

1. Garanta que os pré-requisitos estejam instalados (consulte Requisitos).
2. Crie um servidor MCP baseado em PowerShell.
3. Adicione uma entrada de configuração do servidor MCP ao seu cliente MCP.
4. Chame as ferramentas MCP a partir do cliente MCP.

Install-Module -Name pwsh.mcp

# Import the MCP server module
Import-Module pwsh.mcp -Force -ErrorAction Stop

# Define a simple echo function
function get_echo {
    [CmdletBinding()]
    param (
      [Parameter(Mandatory = $false, HelpMessage = "Text to echo")]
      [string] $text = "Lorem Ipsum"
    )
    return "Echo, $text!"
}

# Start the MCP server and pass the functions to expose.
New-MCPServer -FunctionInfo (Get-Item Function:get_echo)

{
  "servers": {
    "mcp-pwsh-server": {
      "type": "stdio",
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-NoLogo",
        "-File",
        "${workspaceFolder}/path/to/your/script.ps1"
      ]
    }
  }
}

#get_echo text="Hello, MCP!"

Documentação

• Guia do Usuário – documentação detalhada de uso, incluindo configuração avançada, geração de esquemas e melhores práticas.
• Guia do Desenvolvedor – orientações para contribuição, incluindo padrões de codificação, testes e processos de CI/CD.

Referências

• Especificação do Model Context Protocol
• PowerShell
• Documentação do PowerShell
• Diretrizes de Desenvolvimento de Cmdlets PowerShell
• Visual Studio Code
• Configuração MCP do GitHub Copilot CLI
• Gemini CLI

Licença

Este projeto está licenciado sob a Licença MIT.