PowerShell MCP Assistant

Overview

• TypeScript/Node.js MCP server that assists with creating, updating, refactoring, explaining, and reviewing PowerShell scripts.
• The server never executes PowerShell scripts, external commands, or tests; it only analyzes and generates text.

Features & Modes

• Explain – Describe what an existing script does, its inputs/outputs, and side effects.
• Propose New Script – Generate a new script from a high-level task description.
• Refactor – Improve structure/readability of an existing script while preserving intent.
• Update – Add or change parameters/configuration in an existing script with a focus on compatibility.
• Safety Review – Analyze scripts for security/operational risk and policy violations.
• Unit/Pester Test – Propose Pester tests for scripts and explain how to run them.
• Repo List Files (repo.listFiles) – Enumerate files under configured read-only knowledge roots.
• Repo Read File (repo.readFile) – Read file content (optionally by line range) from knowledge roots.
• Repo Write File (repo.writeFile) – Create new files in a target write folder and update existing files only in version-history-backed roots.
• Repo Configure Session (repo.configureSession) – Override source/write roots at runtime for the current process session.
• Repo Set Credential Context (repo.setCredentialContext) – Set runtime signed-in corporate credential context for corporate-boundary writes.

All editing-related modes return a plan + conceptual diff and include metadata such as dependencies, risk summary, and usage guidance.

Architecture

• Implemented as a TypeScript/Node.js MCP server.

• Current components:

  • Config loader + runtime validation (src/config).
  • Tool handlers + invocation envelope (src/tools) for explain, safetyReview, propose, refactor, update, and pester.
  • MCP transport adapter (src/transport/mcpAdapter.ts) for JSON-RPC tools/list and tools/call handling.
  • Optional stdio host loop (src/transport/stdioHost.ts) for line-delimited JSON-RPC runtime I/O.
  • Static PowerShell summary analysis (src/powershell/analysis.ts).
  • Safety guardrails for dangerous cmdlets/inline secret patterns (src/safety/guardrails.ts).
  • Path policy checks for allowed/denied read/write operations (src/policies/pathPolicy.ts).

• Additional planned components:

  • Config loader and validator (JSON-based).
  • Mode registry and dispatch for the modes listed above.
  • PowerShell text analysis helpers (no script execution).
  • Safety/guardrail layer for secrets, dangerous patterns, and risk levels.

Configuration

• Configuration is stored in JSON files under config/ (for example, config/example.config.json).
• Key configuration concepts (planned):
  • Allowed read/write paths for scripts.
  • Repository policy settings:
    • knowledgeSourceReadRoots for read-only reference content.
    • targetWriteRoot for new file creation.
    • versionHistoryWriteRoots and versionHistoryProviders for controlled updates to existing files.
    • allowVersionHistoryEdits toggle for edit/update behavior.
    • corporateBoundaryWriteRoots, requireCorporateCredentialsForCorporateWrites, and allowedCorporateDomains for corporate-boundary enforcement.
  • Target PowerShell version and OS assumptions.
  • Risk tolerance and secrets-handling policies.
  • Enabled modes and their safety profiles.

Admin path setup

• To point the agent to repositories outside the agent folder, set absolute paths in:
  • paths.allowedReadRoots
  • paths.allowedWriteRoots
  • repository.knowledgeSourceReadRoots
  • repository.targetWriteRoot
  • repository.versionHistoryWriteRoots
• To use a different config file location entirely, set environment variable MCP_CONFIG_PATH before starting the server.
• Relative paths are resolved from the process working directory; use absolute paths for predictable admin deployments.

Runtime override option (no config edit needed)

• A user can call repo.configureSession during chat to set:
  • sourceReadRoot (for repo.listFiles / repo.readFile default source)
  • targetWriteRoot (for repo.writeFile new-file default policy root)
• Overrides are in-memory and apply to the current server process only.
• Overrides are still constrained by global paths.allowedReadRoots and paths.allowedWriteRoots policy.

Corporate boundary writes

• For OneDrive/SharePoint/GitHub corporate-boundary roots, enable requireCorporateCredentialsForCorporateWrites.
• Before writing in those roots, call repo.setCredentialContext with signed-in provider and corporate identity.
• Writes to configured corporate-boundary roots are blocked when credential context is missing or domain/provider checks fail.

Authentication options

• Session-only (simpler):
  • repository.authMode = "session"
  • repository.requireOAuthForCorporateWrites = false
• Hybrid (recommended for enterprise):
  • repository.authMode = "hybrid"
  • repository.requireOAuthForCorporateWrites = true
  • configure allowedOAuthIssuers, allowedOAuthAudiences, and allowedTenantIds

Enforce auth on first tool access

• Set repository.requireAuthenticationOnFirstAccess = true.
• The first call to repository access tools (repo.listFiles, repo.readFile, repo.writeFile) is blocked until authentication is established.
• Users can authenticate by setting session context (repo.setCredentialContext) and, in hybrid mode, setting OAuth context (repo.setOAuthTokenContext).
• Clients can use:
  • repo.getAuthStatus to check current status.
  • repo.requestAuthPrompt to display sign-in instructions.
  • repo.validateOAuthToken to validate OAuth claims before setting runtime token context.

Quick-start policy profiles

• Use one of these ready-made configs:
  • config/profiles/dev.session.config.json
  • config/profiles/corporate.hybrid.config.json
• Start with a profile by setting MCP_CONFIG_PATH to the chosen file.
• Profile guidance:
  • dev.session: easiest local setup, session auth only.
  • corporate.hybrid: enterprise setup with first-access auth gate and OAuth checks for corporate writes.
• Replace placeholder values in corporate profile (allowedTenantIds, issuer/audience, and domains) before production use.

Profile switcher helper

• Use scripts/use-config-profile.ps1 to create an active config quickly.
• Example usage:
  • pwsh -File ./scripts/use-config-profile.ps1 -Profile dev -ApplyToSession
  • pwsh -File ./scripts/use-config-profile.ps1 -Profile corporate -OutputPath ./config/active.config.json -ApplyToSession
• This copies a profile to config/active.config.json (or custom output path) and optionally sets MCP_CONFIG_PATH in the current shell session.

Running in VS Code (current focus)

• VS Code (recommended for development)
  • Keep server local (node dist/index.js), use MCP_CONFIG_PATH to point to your selected profile.
  • For enterprise use, select the corporate profile and replace placeholder tenant/domain/issuer/audience values.
• Cloud hosting notes (GitHub/Azure) are intentionally deferred while local VS Code experience is finalized.

Publishing recommendation (outside VS Code)

• Best default: containerize and publish as a private service (Azure Container Apps, AKS, or equivalent).
• Alternative for event-driven integrations: Azure Function host wrapper around stdio/HTTP adapter.
• Keep this order of preference:
  1. Private container service (most operationally consistent)
  2. Azure Functions wrapper (good for serverless/event-based workloads)
  3. Local-only process for dev/test

Recommended enterprise controls

• Use repository.allowedSaveLocations as the top-level allow-list for all writes.
• Use repository.allowedTenantIds to restrict corporate-boundary writes to approved tenant IDs.
• Keep paths.allowedWriteRoots as an infrastructure boundary and allowedSaveLocations as a business-policy boundary.
• Optional user-flow tools:
  • repo.getAuthStatus to detect whether runtime credentials are present.
  • repo.requestAuthPrompt to return user-facing sign-in instructions for GitHub or M365.

Safety & Limitations

• Scripts and commands are never executed by this server.
• Credentials and secrets must not be stored in scripts; use appropriate secret-storage mechanisms instead.
• Behavior is driven by JSON config and may be restricted by risk level and organizational policy.

Development

• Tech stack: Node.js (LTS), TypeScript.

• Basic structure (planned):

  • src/ – server entrypoint, config loader, modes, safety, logging, prompts.
  • config/ – JSON configuration files.
  • tests/ – automated tests for config, modes, and safety behavior.

• Local commands:

  • npm run build – compile source TypeScript.
  • npm test – compile tests and run Node built-in test runner.

MCP JSON-RPC Examples

• tools/list request:

  • method: tools/list
  • params: omitted

• tools/call request (enabled tool):

  • method: tools/call
  • params:
    • name: explain
    • arguments: { "scriptText": "Write-Host 'hello'" }

• tools/call request (disabled tool):

  • method: tools/call
  • params:
    • name: disabled mode id (for example update if disabled in config)
    • arguments: tool input object
  • expected behavior: response result.isError = true with policy message.

• common error responses:

  • -32600 invalid request envelope
  • -32601 method not found
  • -32602 invalid params for tools/call

Roadmap

• Add one-click install/onboarding option in repository README for VS Code users.
• Add instructions for connecting to a local instance from Copilot Studio.
• Consider expanded Azure publishing guidance after VS Code-first workflow is finalized.