PoshMCP

Servidor MCP do PowerShell

Um servidor Model Context Protocol (MCP) que expõe cmdlets do PowerShell como ferramentas para assistentes de IA como Claude ou Github Copilot. Construído com segurança em mente por meio de listas de permissões explícitas de cmdlets permitidos.

Visão Geral

Este servidor MCP carrega dinamicamente cmdlets do PowerShell a partir de módulos e scripts, gerando automaticamente esquemas de ferramentas a partir da documentação dos cmdlets. Diferente do remoting tradicional do PowerShell, este servidor usa uma abordagem de lista de permissões — apenas cmdlets explicitamente configurados são expostos, tornando-o mais seguro para interações com IA.

Principais Recursos

• Configuração Declarativa: Defina as ferramentas disponíveis em um arquivo de configuração JSON simples
• Geração Automática de Esquemas: Usa reflexão do PowerShell para gerar esquemas de ferramentas MCP a partir da documentação de ajuda dos cmdlets
• Segurança por Lista de Permissões: Apenas cmdlets explicitamente listados são expostos como ferramentas
• Carregamento Dinâmico: Suporta tanto módulos do PowerShell (.psm1) quanto arquivos de script (.ps1)
• Conversão de Tipos: Lida automaticamente com conversões de tipos de parâmetros (DateTime, parâmetros switch, etc.)

Como Funciona

1. Carregamento de Configuração: Lê mcp-config.json para determinar quais cmdlets expor
2. Importação de Módulos/Scripts: Carrega módulos do PowerShell especificados e faz dot-source de arquivos de script
3. Geração de Esquemas: Usa Get-Command e Get-Help para inspecionar cada cmdlet:
   • Extrai o resumo do cmdlet como descrição da ferramenta
   • Mapeia tipos de parâmetros do PowerShell para tipos de esquema JSON
   • Identifica parâmetros obrigatórios a partir de atributos [Parameter(Mandatory)]
   • Gera nomes de parâmetros em camelCase para JSON (ex.: StartDate → startDate)
4. Invocação de Ferramentas: Quando uma ferramenta é chamada, despacha dinamicamente para o cmdlet correspondente com mapeamento de parâmetros

Instalação

Da Galeria do PowerShell (Recomendado)

Install-Module -Name PoshMCP -Scope CurrentUser

A partir do Código-Fonte

1. Clone ou baixe este repositório para sua máquina local
2. Certifique-se de que o PowerShell 7+ esteja instalado (pwsh)

Configuração

Configuração do Servidor MCP

Adicione o seguinte ao seu arquivo de configuração MCP do VS Code (normalmente %APPDATA%\Code\User\mcp.json no Windows):

{
    "servers": {
        "posh-mcp": {
            "type": "stdio",
            "command": "pwsh",
            "args": [
                "-NoProfile",
                "-NoLogo",
                "-Command",
                "Import-Module PoshMCP;",
                "Start-PoshMcp -ConfigPath C:\\path\\to\\your\\mcp-config.json"
            ]
        }
    }
}

Configuração de Ferramentas

Edite mcp-config.json para definir quais cmdlets expor:

{
    "serverInfo": {
        "name": "posh-mcp",
        "version": "1.0.0"
    },
    "modules": [
        {
            "name": "ModuleName",
            "path": "./MyModule.psm1",
            "cmdlets": [
                "Get-MyData",
                "Set-MyConfig"
            ]
        }
    ],
    "scripts": [
        {
            "path": "./my-tools.ps1",
            "cmdlets": [
                "Get-CustomInfo",
                "Invoke-CustomTask"
            ]
        }
    ]
}

Estrutura de Configuração:

• serverInfo: Metadados sobre o servidor MCP

  • name: Nome do servidor exibido para clientes MCP
  • version: Versão do servidor

• modules: Módulos do PowerShell a importar

  • name: Nome do módulo (informativo)
  • path: Caminho relativo ou absoluto para o arquivo .psm1
  • cmdlets: Matriz de nomes de cmdlets a expor como ferramentas

• scripts: Arquivos de script do PowerShell para fazer dot-source

  • path: Caminho relativo ou absoluto para o arquivo .ps1
  • cmdlets: Matriz de nomes de funções a expor como ferramentas

Criando Ferramentas Personalizadas

Exemplo: Criando um Script Personalizado

Crie um arquivo de script (ex.: my-tools.ps1):

function Get-SystemUptime {
    <#
    .SYNOPSIS
        Returns the system uptime information.
    
    .DESCRIPTION
        Gets how long the system has been running since last boot.
    
    .EXAMPLE
        Get-SystemUptime
        Returns uptime information.
    
    .OUTPUTS
        Hashtable with uptime details.
    #>
    [CmdletBinding()]
    param()
    
    $os = Get-CimInstance Win32_OperatingSystem
    $uptime = (Get-Date) - $os.LastBootUpTime
    
    return @{
        LastBootTime = $os.LastBootUpTime.ToString("o")
        UptimeDays = $uptime.Days
        UptimeHours = $uptime.Hours
        UptimeMinutes = $uptime.Minutes
    }
}

Adicione ao mcp-config.json:

{
    "scripts": [
        {
            "path": "./my-tools.ps1",
            "cmdlets": [
                "Get-SystemUptime"
            ]
        }
    ]
}

A ferramenta será automaticamente exposta como getSystemUptime (camelCase) com esquema gerado a partir da ajuda baseada em comentários.

Boas Práticas de Documentação

Para melhores resultados, inclua ajuda completa baseada em comentários em seus cmdlets:

function Get-MyData {
    <#
    .SYNOPSIS
        Brief one-line description (becomes tool description)
    
    .PARAMETER Name
        Detailed parameter description (appears in tool schema)
    
    .PARAMETER StartDate
        Start date for filtering results
    
    .EXAMPLE
        Get-MyData -Name "Test" -StartDate "2025-01-01"
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]$Name,
        
        [Parameter(Mandatory = $false)]
        [DateTime]$StartDate = (Get-Date).AddDays(-7)
    )
    
    # Your implementation
}

Considerações de Segurança

Por Que Isso É Mais Seguro

1. Somente Lista de Permissões: Apenas cmdlets explicitamente listados em mcp-config.json são acessíveis
2. Sem Execução Dinâmica: O servidor não executa comandos arbitrários do PowerShell
3. Validação de Parâmetros: Todos os parâmetros passam pela validação nativa do PowerShell
4. Escopo Isolado: Cada cmdlet é executado em um contexto controlado