PowerShell MCP Server Development

Expert assistant for developing Model Context Protocol (MCP) servers using the PowerShell SDK (KevinMarquette/pwsh.mcp.sdk).

What This Skill Does

This skill provides expert guidance for working with the PowerShell MCP SDK, which enables PowerShell scripts to be exposed as MCP resources, tools, and prompts through a convention-based folder structure.

Key Principle

The SDK uses a folder-based convention where PowerShell scripts placed in specific directories (`tools/`, `prompts/`, `resources/`) are automatically discovered and exposed via the MCP protocol.

Instructions

1. Understanding the Module Structure

When working with this codebase, recognize:

2. Testing and Development Workflow

Use these commands for testing:

```powershell

Import the module for testing

Import-Module ./MCP.SDK/MCP.SDK.psd1 -Force

Test with the reference server example

Start-McpServer -MCPRoot ./Examples/reference-server

```

3. MCP Request Processing Flow

Understand the request lifecycle:

1. **Entry Point**: `Invoke-MCPRequest` receives JSON-RPC requests via stdin

2. **Method Routing**: Routes to handlers based on `method` field:

- `initialize` → `Get-Initialization` (server capabilities)

- `ping` → Empty object

- `tools/list` → `Get-ToolList` (scans `tools/` directory)

- `prompts/list` → `Get-PromptList` (scans `prompts/` directory)

- `resources/list` → `Get-ResourceList` (scans `resources/` directory)

3. **Response Formatting**: `ConvertTo-JsonRpcResponse` wraps results in JSON-RPC format

4. Convention-Based Discovery

The SDK discovers capabilities by scanning the MCPRoot directory:

**Tools** (`{MCPRoot}/tools/*.ps1`):

**Prompts** (`{MCPRoot}/prompts/*.ps1`):

**Resources** (`{MCPRoot}/resources/**/*`):

5. Type Conversion System

`ConvertTo-JsonType` maps PowerShell types to JSON schema:

6. Creating New MCP Servers

When helping users create MCP servers:

**Directory Structure:**

```

my-server/

├── tools/ # Executable PowerShell scripts

├── prompts/ # Template scripts with parameters

├── resources/ # Static files or dynamic .ps1 scripts

└── instructions.md # Optional: Server usage instructions

```

**Script Template:**

```powershell

<#

.SYNOPSIS

Brief description

.DESCRIPTION

Detailed description

.EXAMPLE

Example usage

#>

[CmdletBinding()]

param(

# Detailed description of the parameter

[Parameter(Mandatory)]

[ValidateSet('Option1', 'Option2')]

[string]$ParamName

)

```

**Best Practices:**

7. JSON-RPC Protocol Details

All requests/responses use:

8. Capability Detection

`Get-Initialization` checks directory contents:

9. Important Constraints

When working with this codebase:

10. Reference Implementation

Direct users to `Examples/reference-server` for:

Study these examples to understand expected script structure and return formats.

Examples

**Creating a new tool:**

```powershell

In tools/Get-Weather.ps1

<#

.SYNOPSIS

Gets current weather for a location

.DESCRIPTION

Retrieves weather data for the specified city

.EXAMPLE

Get-Weather -City "Seattle"

#>

[CmdletBinding()]

param(

[Parameter(Mandatory)]

[string]$City

)

return @{

city = $City

temperature = 72

condition = "Sunny"

}

```

**Creating a prompt:**

```powershell

In prompts/Email-Template.ps1

<#

.SYNOPSIS

Generates email template

.DESCRIPTION

Creates a formatted email for the specified purpose

#>

[CmdletBinding()]

param(

[Parameter(Mandatory)]

[ValidateSet('Welcome', 'Followup', 'Newsletter')]

[string]$Type

)

return "Email template for: $Type"

```

Constraints