Architecture Overview

The Glean PowerShell repository implements a three-layer architecture consisting of a Python-based code generator, a generated PowerShell module, and a PowerShell-based MCP server. The Python generator consumes OpenAPI specifications to produce the PowerShell cmdlets, which are then wrapped by a hand-written runtime for authentication and HTTP handling. The MCP server leverages this module to expose Glean capabilities to AI agents via JSON-RPC. The entire system is orchestrated by a PowerShell build script that manages regeneration, testing, and packaging.

Code Generation and Module Structure

The core of the module is generated from the gleanwork/open-api specification using a deterministic Python generator located in the generator/ directory ¹. This generator produces 111 operations (68 client and 43 indexing) as PowerShell cmdlets, ensuring every published operation is covered except those marked for removal. The generated code resides in Public/Client/ and Public/Indexing/, while a small hand-written runtime in Private/ handles HTTP, authentication, retry logic, and pagination. The module manifest Glean.psd1 and loader Glean.psm1 are also generated or managed to support import and alias registration.

MCP Server Integration

The mcp/ directory contains a Glean MCP server written entirely in PowerShell, which acts as a layer on top of the generated module. This server replicates the functionality of the official @gleanwork MCP server and speaks JSON-RPC 2.0 over stdio to expose Glean as tools to hosts like Claude Code. It maps specific tools such as glean_search and glean_chat to backing cmdlets like Search-GleanSearch and New-GleanChat. An opt-in glean_invoke tool allows calling any of the 111 cmdlets when GLEAN_MCP_ALLOW_INVOKE=1 is set. The server uses the module’s authentication mechanisms, supporting both token and cookie-based sessions, and ensures logging goes to stderr while protocol messages go to stdout.

Build and Test Workflows

Development and release workflows are orchestrated by build.ps1, which checks for prerequisites including PowerShell 7.2+, Pester, PSScriptAnalyzer, and Python 3 ². The script first runs the Python generator to create the module from vendored specs, then imports the module and runs the full Pester test suite. The test suite includes a “Contract” test that verifies the generated surface matches the spec by checking parameters, required flags, media types, and HTTP method/path/body for all 111 operations ¹. Additional tests cover naming uniqueness, module validity, runtime behavior (auth, retries, paging), and MCP protocol correctness. For packaging, Build-GleanPackage.ps1 creates a versioned, checksummed zip file, and install.ps1 verifies the SHA256 before installation.

README.md L1-120 (showing 40 of 120)

# Glean PowerShell Module

A complete, idiomatic PowerShell client for the **published Glean REST APIs** (the Client
API and the Indexing API) from the
[`gleanwork/open-api`](https://github.com/gleanwork/open-api) specification: **111 operations**
(68 client + 43 indexing), every published operation except the one the upstream overlay marks
for removal. Glean ships official SDKs for Python, TypeScript, Java, and Go; this fills the
PowerShell gap.

The module is **generated** from the OpenAPI specs by a deterministic Python generator and
layered over a small hand-written runtime, so it can be regenerated whenever the spec
changes. A data-driven test suite proves the generated surface matches the spec by contract
(parameters, required flags, media types, HTTP method/path/body), not just by file count.

## Getting started

### 1. Prerequisites

PowerShell 7.2 or newer (`pwsh`). Check with `pwsh -v`. If you do not have it:

- Windows: `winget install Microsoft.PowerShell`
- macOS: `brew install --cask powershell`
- Linux: see https://learn.microsoft.com/powershell/scripting/install/installing-powershell-on-linux

### 2. Install the module

Pick one.

**From a release package (for end users).** Download `Glean-<version>.zip` and `SHA256SUMS`, then:

```powershell
pwsh ./install.ps1 -PackagePath ./Glean-<version>.zip      # verifies the SHA256, then installs
```

This installs into your user module path so `Import-Module Glean` works from any session. Add
`-RegisterMcp` to also wire up the MCP server for Claude Code.

**From source (for development).** Run the test suite and import in place:

```bash

build.ps1 L1-46 (showing 40 of 46)

#!/usr/bin/env pwsh
# Regenerate the module from the vendored specs and run the full test suite.
# Fails fast with guidance if a prerequisite is missing.
[CmdletBinding()]
param(
    [switch] $SkipGenerate,
    [switch] $SkipTests
)
$ErrorActionPreference = 'Stop'
$root = $PSScriptRoot

function Assert-Tool {
    param([string] $Name, [scriptblock] $Check, [string] $Hint)
    if (-not (& $Check)) { throw "Prerequisite missing: $Name. $Hint" }
}

Write-Host '==> Checking prerequisites' -ForegroundColor Cyan
Assert-Tool 'PowerShell >= 7.2' { $PSVersionTable.PSVersion -ge [version]'7.2' } 'Install PowerShell 7 (see bootstrap.sh).'
Assert-Tool 'Pester >= 5.5' { (Get-Module Pester -ListAvailable | Where-Object Version -ge ([version]'5.5.0')) } 'Install-Module Pester -MinimumVersion 5.5.0 -Scope CurrentUser'
Assert-Tool 'PSScriptAnalyzer' { (Get-Module PSScriptAnalyzer -ListAvailable) } 'Install-Module PSScriptAnalyzer -Scope CurrentUser'
$python = (Get-Command python3 -ErrorAction SilentlyContinue) ?? (Get-Command python -ErrorAction SilentlyContinue)
Assert-Tool 'Python 3' { $null -ne $python } 'Install Python 3 and `pip install -r generator/requirements.txt`.'

if (-not $SkipGenerate) {
    Write-Host '==> Generating module from specs' -ForegroundColor Cyan
    & $python.Source (Join-Path $root 'generator' 'generate.py')
    if ($LASTEXITCODE -ne 0) { throw 'Generation failed.' }
}

Write-Host '==> Importing module' -ForegroundColor Cyan
Import-Module (Join-Path $root 'Glean' 'Glean.psd1') -Force
$count = (Get-Command -Module Glean -CommandType Function).Count
Write-Host "    Imported $count functions."

if (-not $SkipTests) {
    Write-Host '==> Running Pester' -ForegroundColor Cyan
    Import-Module Pester -MinimumVersion 5.5.0
    $cfg = New-PesterConfiguration
    $cfg.Run.Path = Join-Path $root 'tests'
    $cfg.Run.PassThru = $true