### Example Client Configuration Structure (Cursor)

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLAUDE.md

Defines the structure for a client's JSON configuration file, including ID, display name, transport types, supported platforms, and how server properties are mapped for HTTP and stdio connections. Also specifies the protocol handler for one-click installation.

```json
{
  "id": "cursor",
  "displayName": "Cursor",
  "userConfigurable": true,
  "transports": ["stdio", "http"],
  "supportedPlatforms": ["darwin", "linux", "win32"],
  "configStructure": {
    "serversPropertyName": "mcpServers",
    "httpPropertyMapping": { "typeProperty": "type", "urlProperty": "url", "headersProperty": "headers" },
    "stdioPropertyMapping": { "typeProperty": "type", "commandProperty": "command", "argsProperty": "args", "envProperty": "env" }
  },
  "protocolHandler": {
    "protocol": "cursor://",
    "urlTemplate": "cursor://anysphere.cursor-deeplink/mcp/install?name={{name}}&config={{config}}",
    "configFormat": "base64-json"
  }
}
```

--------------------------------

### Install Dependencies with npm

Source: https://github.com/gleanwork/mcp-config/blob/main/README.md

Use this command to install all project dependencies.

```bash
npm install
```

--------------------------------

### Check CLI Install Support with builder.supportsCliInstallation

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Use `supportsCliInstallation` to get a `CliInstallationStatus` object indicating CLI availability and the reason. Use `CLI_INSTALL_REASON` constants for checking reasons.

```typescript
import { MCPConfigRegistry, CLI_INSTALL_REASON } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });

// Native CLI client
const claudeStatus = registry.createBuilder('claude-code').supportsCliInstallation();
// { supported: true, reason: 'native_cli' }

// Client with no CLI (no commandBuilder provided)
const gooseStatus = registry.createBuilder('goose').supportsCliInstallation();
// { supported: false, reason: 'no_cli_available', message: 'No CLI command available for Goose.' }

// Client configured via IDE UI (no configPath)
const jbStatus = registry.createBuilder('jetbrains').supportsCliInstallation();
// { supported: false, reason: 'no_config_path', message: 'JetBrains AI Assistant is configured through IDE settings, not via CLI.' }
```

```typescript
// Conditional UI rendering
const builder = registry.createBuilder('cursor');
const status = builder.supportsCliInstallation();
if (status.supported) {
  if (status.reason === CLI_INSTALL_REASON.NATIVE_CLI) {
    console.log('Has native CLI');
  } else {
    console.log('CLI via commandBuilder callback');
  }
} else {
  if (status.reason === CLI_INSTALL_REASON.NO_CONFIG_PATH) {
    console.log('Use IDE settings:', status.message);
  } else {
    console.log('No CLI available:', status.message);
  }
}
```

--------------------------------

### OpenCode stdio Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example of configuring OpenCode for stdio transport, including command, arguments, and environment variables.

```json
{
  "mcp": {
    "example": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@example/mcp-server"
      ],
      "environment": {
        "EXAMPLE_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Codex stdio Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example TOML configuration for setting up a stdio server for OpenAI Codex, including environment variables.

```toml
[mcp_servers.example]
command = "npx"
args = [ "-y", "@example/mcp-server" ]

[mcp_servers.example.env]
EXAMPLE_API_KEY = "your-api-key"
```

--------------------------------

### Codex HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example TOML configuration for setting up an HTTP server for OpenAI Codex.

```toml
[mcp_servers.example]
url = "https://api.example.com/mcp"
```

--------------------------------

### `builder.supportsCliInstallation()`

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Checks if CLI installation is supported for the current client configuration and returns a status object with the reason.

```APIDOC
## `builder.supportsCliInstallation()` — Check CLI install support

Returns a `CliInstallationStatus` object indicating whether CLI installation is available and the reason. Use `CLI_INSTALL_REASON` constants to check the reason without string literals.

### Returns

* `CliInstallationStatus` - An object with `supported` (boolean) and `reason` (string) properties.
  * `supported` (boolean) - True if CLI installation is supported, false otherwise.
  * `reason` (string) - The reason for the support status (e.g., 'native_cli', 'no_cli_available', 'no_config_path').
  * `message` (string) - An optional message providing more details.
```

--------------------------------

### Install Package

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

Install the @gleanwork/mcp-config-schema package using npm.

```bash
npm install @gleanwork/mcp-config-schema
```

--------------------------------

### Install @gleanwork/mcp-config-glean

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-glean/README.md

Install the package using npm.

```bash
npm install @gleanwork/mcp-config-glean
```

--------------------------------

### OpenCode HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example of configuring OpenCode for HTTP transport, specifying the server URL and type.

```json
{
  "mcp": {
    "example": {
      "type": "remote",
      "url": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### Claude for Desktop HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for Claude for Desktop when using the mcp-remote bridge for HTTP servers.

```json
{
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.example.com/mcp"
      ]
    }
  }
}
```

--------------------------------

### Quick Start: Create Glean Registry and Configurations

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-glean/README.md

Demonstrates how to create a pre-configured Glean registry and generate both stdio and HTTP configurations using helper functions.

```typescript
import {
  createGleanRegistry,
  createGleanServerUrlEnv,
  createGleanHeaders,
  buildGleanMcpUrl,
} from '@gleanwork/mcp-config-glean';

// Create a pre-configured registry
const registry = createGleanRegistry();
const builder = registry.createBuilder('cursor');

// Generate stdio configuration
const stdioConfig = builder.buildConfiguration({
  transport: 'stdio',
  env: createGleanServerUrlEnv('https://my-company-be.glean.com', 'my-api-token'),
});

// Generate HTTP configuration
const httpConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: buildGleanMcpUrl('https://my-company-be.glean.com'),
  headers: createGleanHeaders('my-api-token'),
});
```

--------------------------------

### Claude Code stdio Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for connecting to Claude Code via stdio. Specify the 'command', 'args', and any necessary 'env' variables.

```json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": [
        "-y",
        "@example/mcp-server"
      ],
      "type": "stdio",
      "env": {
        "EXAMPLE_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Antigravity stdio Server Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for setting up an Antigravity client to use stdio, including the command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": [
        "-y",
        "@example/mcp-server"
      ],
      "env": {
        "EXAMPLE_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Goose stdio Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

An example of configuring the Goose client for stdio transport. Specify the command and arguments to execute the MCP server.

```yaml
extensions:
  example:
    name: example
    cmd: npx
    args:
      - '-y'
      - '@example/mcp-server'
    type: stdio
    timeout: 300
    enabled: true
    bundled: null
    description: null
    env_keys: []
    envs:
      EXAMPLE_API_KEY: your-api-key
```

--------------------------------

### Generate stdio One-Click URL for Cursor

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Generates a one-click install URL for Cursor when using the stdio transport, suitable for local server setups.

```typescript
// stdio one-click for Cursor
const stdioUrl = cursorBuilder.buildOneClickUrl!({
  transport: 'stdio',
  env: { MY_API_TOKEN: 'token123' },
});
```

--------------------------------

### Junie (JetBrains) HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example of configuring Junie for HTTP transport, specifying the server URL.

```json
{
  "mcpServers": {
    "example": {
      "url": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### Gemini CLI HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for connecting to an MCP server via HTTP using the Gemini CLI. This demonstrates how to specify the HTTP URL for the MCP server.

```json
{
  "mcpServers": {
    "example": {
      "httpUrl": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### Generate Cursor One-Click Install URL

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Creates a deep-link URL for Cursor that automatically installs the MCP server. Configuration is base64-encoded.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });

// Cursor one-click URL
const cursorBuilder = registry.createBuilder('cursor');
const cursorUrl = cursorBuilder.buildOneClickUrl!({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer my-token' },
});
```

--------------------------------

### Server Name Generation and Normalization

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-glean/README.md

Examples of using helper functions to normalize product names, build server names with Glean prefixes, and normalize existing server names.

```typescript
import {
  normalizeGleanProductName,
  buildGleanServerName,
  normalizeGleanServerName,
} from '@gleanwork/mcp-config-glean';

// Normalize product names for white-labeling
normalizeGleanProductName();              // 'glean'
normalizeGleanProductName('Acme Corp');   // 'acme_corp'

// Build server names with glean_ prefix
buildGleanServerName({ transport: 'stdio' });                              // 'glean_local'
buildGleanServerName({ transport: 'http' });                               // 'glean_default'
buildGleanServerName({ transport: 'http', serverUrl: '.../mcp/analytics' }); // 'glean_analytics'
buildGleanServerName({ serverName: 'custom' });                            // 'glean_custom'
buildGleanServerName({ agents: true });                                    // 'glean_agents'

// Normalize existing server names
normalizeGleanServerName('custom');        // 'glean_custom'
normalizeGleanServerName('glean_custom');  // 'glean_custom' (no double prefix)
```

--------------------------------

### `builder.buildCommand(options)`

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Generates a CLI command string for installing the MCP server. This method is used by native CLI clients and can be configured for other clients via `RegistryOptions`.

```APIDOC
## `builder.buildCommand(options)` — Generate CLI install command

Returns a CLI command string for installing the MCP server, or `null` if not supported. Native CLI clients (Claude Code, VS Code, Codex) generate built-in commands. Other clients use the `commandBuilder` callbacks from `RegistryOptions` if provided.

### Parameters

* `options` (object) - Configuration options for the command.
  * `transport` (string) - The transport protocol ('http' or 'stdio').
  * `serverUrl` (string) - The URL of the MCP server (required for 'http' transport).
  * `serverName` (string) - The name of the MCP server.
  * `headers` (object) - Optional headers for the HTTP request.
  * `env` (object) - Environment variables for the 'stdio' transport.

### Returns

* `string | null` - The generated CLI command string or null if not supported.
```

--------------------------------

### Generate CLI Install Command with builder.buildCommand

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Use `buildCommand` to generate a CLI command string for installing the MCP server. Returns `null` if not supported. Native clients generate built-in commands, while others use `commandBuilder` callbacks.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });

// Claude Code — native CLI
const claudeBuilder = registry.createBuilder('claude-code');

const httpCmd = claudeBuilder.buildCommand({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer my-token' },
});
// 'claude mcp add my-server https://api.example.com/mcp/default --transport http --scope user --header "Authorization: Bearer my-token"'

const stdioCmd = claudeBuilder.buildCommand({
  transport: 'stdio',
  env: { MY_API_TOKEN: 'token123' },
});
// 'claude mcp add local --scope user --env MY_API_TOKEN=token123 -- npx -y @my-org/mcp-server'
```

```typescript
// VS Code — native CLI
const vscodeBuilder = registry.createBuilder('vscode');
const vsCmd = vscodeBuilder.buildCommand({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});
// "code --add-mcp '{\"name\":\"my-server\",\"type\":\"http\",\"url\":\"https://api.example.com/mcp/default\"}'"
```

```typescript
// Codex — native CLI
const codexBuilder = registry.createBuilder('codex');
const codexCmd = codexBuilder.buildCommand({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  headers: { Authorization: 'Bearer my-token' },
});
// "codex mcp add --url https://api.example.com/mcp/default --bearer-token-env-var MY_API_TOKEN my-server"
```

```typescript
// JetBrains — no config path, returns null
const jbBuilder = registry.createBuilder('jetbrains');
const jbCmd = jbBuilder.buildCommand({ transport: 'http', serverUrl: '...' });
// null
```

--------------------------------

### Antigravity HTTP Server Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for setting up an Antigravity client to use an HTTP server, specifying the server URL.

```json
{
  "mcpServers": {
    "example": {
      "serverUrl": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### Goose HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

An example of how to configure the Goose client for HTTP transport. Ensure the 'type' is set to 'streamable_http' and provide a valid 'uri'.

```yaml
extensions:
  example:
    enabled: true
    name: example
    type: streamable_http
    uri: https://api.example.com/mcp
    envs: {}
    env_keys: []
    headers: {}
    description: ''
    timeout: 300
    bundled: null
    available_tools: []
```

--------------------------------

### Build HTTP Configuration with URL Templates

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Supports URL template variables for dynamic server URLs. The example shows how the URL is resolved.

```typescript
// HTTP transport with URL template variables
const templateConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/{region}/mcp/{endpoint}',
  urlVariables: { region: 'us-east-1', endpoint: 'default' },
  serverName: 'my-server',
});
```

--------------------------------

### Generate VS Code One-Click Install URL

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Creates a deep-link URL for VS Code that automatically installs the MCP server. Configuration is URL-encoded JSON.

```typescript
// VS Code one-click URL
const vscodeBuilder = registry.createBuilder('vscode');
const vscodeUrl = vscodeBuilder.buildOneClickUrl!({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});
```

--------------------------------

### VS Code HTTP Server Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for setting up an HTTP transport for an MCP server within VS Code.

```json
{
  "servers": {
    "example": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### CLI Command Generation Example

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Illustrates the CLI commands generated by GLEAN_REGISTRY_OPTIONS.commandBuilder for HTTP and stdio transports.

```typescript
// CLI command generated by GLEAN_REGISTRY_OPTIONS.commandBuilder
// HTTP: npx -y @gleanwork/configure-mcp-server remote --url <url> --client <clientId> --token <token>
// stdio: npx -y @gleanwork/configure-mcp-server local --client <clientId> --env GLEAN_SERVER_URL=<url>
```

--------------------------------

### Claude Code HTTP Configuration Example

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for connecting to Claude Code via HTTP. Ensure the 'type' is set to 'http' and provide the correct 'url'.

```json
{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}
```

--------------------------------

### VS Code stdio Server Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/CLIENTS.md

Example configuration for setting up a stdio transport for an MCP server within VS Code, including command, arguments, and environment variables.

```json
{
  "servers": {
    "example": {
      "command": "npx",
      "args": [
        "-y",
        "@example/mcp-server"
      ],
      "type": "stdio",
      "env": {
        "EXAMPLE_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### Development Commands

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

Common npm commands for developing the MCP Config package, including installation, building, testing, and documentation generation.

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm run test

# Run all checks (lint, typecheck, test)
npm run test:all

# Generate documentation
npm run generate:docs
```

--------------------------------

### builder.buildOneClickUrl(options)

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Generates a deep-link URL for one-click installation of the MCP server in supported clients like Cursor and VS Code. The URL format varies between clients (base64-encoded JSON for Cursor, URL-encoded JSON for VS Code).

```APIDOC
## `builder.buildOneClickUrl(options)` — One-click install URL

Available on `CursorConfigBuilder` and `VSCodeConfigBuilder`. Generates a deep-link URL that, when opened in the browser, automatically installs the MCP server in the client. Cursor uses base64-encoded JSON in the URL; VS Code uses URL-encoded JSON.

### Parameters
#### Request Body
- **transport** (string) - Required - Specifies the transport type, either 'http' or 'stdio'.
- **serverUrl** (string) - Optional - The URL of the MCP server (for http transport).
- **serverName** (string) - Required - The name of the server configuration.
- **headers** (object) - Optional - Key-value pairs for HTTP headers (for http transport).
- **env** (object) - Optional - Environment variables for stdio transport.

### Request Example
```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });

// Cursor one-click URL
const cursorBuilder = registry.createBuilder('cursor');
const cursorUrl = cursorBuilder.buildOneClickUrl!({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer my-token' },
});

// VS Code one-click URL
const vscodeBuilder = registry.createBuilder('vscode');
const vscodeUrl = vscodeBuilder.buildOneClickUrl!({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});

// stdio one-click for Cursor
const stdioUrl = cursorBuilder.buildOneClickUrl!({
  transport: 'stdio',
  env: { MY_API_TOKEN: 'token123' },
  serverName: 'local', // serverName is required for stdio transport
});
```

### Response
#### Success Response (200)
- **url** (string) - The generated deep-link URL.

### Response Example
```
cursor://anysphere.cursor-deeplink/mcp/install?name=my-server&config=<base64>
```

```
vscode:mcp/install?<url-encoded-json>
```

```
cursor://anysphere.cursor-deeplink/mcp/install?name=local&config=<base64>
```
```

--------------------------------

### LLM Migration: Update Property Access

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v1-to-v2-semantic-renaming.md

Globally find and replace property accessors to match the new naming conventions, for example, changing `.serverKey` to `.serversPropertyName`.

```text
Action: Find and replace globally
Patterns:
  - \.serverKey → \.serversPropertyName
  - \.httpConfig → \.httpPropertyMapping
  - \.stdioConfig → \.stdioPropertyMapping
  - \.oneClick → \.protocolHandler
  - \.typeField → \.typeProperty
  - \.urlField → \.urlProperty
  - \.commandField → \.commandProperty
  - \.argsField → \.argsProperty
  - \.envField → \.envProperty
  - \.headersField → \.headersProperty
```

--------------------------------

### Get Platform Config File Path with `getConfigPath()`

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Retrieves the platform-specific configuration file path for a given client builder. This function is only available in Node.js environments and automatically expands environment variables like $HOME, %USERPROFILE%, and %APPDATA%.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry();

// On macOS
registry.createBuilder('cursor').getConfigPath();
// '/Users/alice/.cursor/mcp.json'

registry.createBuilder('vscode').getConfigPath();
// '/Users/alice/Library/Application Support/Code/User/mcp.json'

registry.createBuilder('goose').getConfigPath();
// '/Users/alice/.config/goose/config.yaml'

registry.createBuilder('claude-desktop').getConfigPath();
// '/Users/alice/Library/Application Support/Claude/claude_desktop_config.json'

// On Windows, %APPDATA% and %USERPROFILE% are expanded automatically
// registry.createBuilder('cursor').getConfigPath()
// → 'C:/Users/alice/.cursor/mcp.json'
```

--------------------------------

### Build stdio Client Configuration

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Use for local server instances launched via `npx`. Environment variables can be passed to the server process.

```typescript
// stdio transport (local server via npx)
const stdioConfig = builder.buildConfiguration({
  transport: 'stdio',
  env: { MY_INSTANCE: 'my-instance', MY_API_TOKEN: 'token123' },
});
```

--------------------------------

### Merge Partial Configuration into Existing File

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Demonstrates how to read an existing configuration file, merge a partial configuration into it, and write the updated configuration back.

```typescript
// Merging partial config into existing file
import * as fs from 'fs';
const configPath = builder.getConfigPath();
const existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
existing.mcpServers = { ...existing.mcpServers, ...partial };
fs.writeFileSync(configPath, JSON.stringify(existing, null, 2));
```

--------------------------------

### Build All Packages with npm

Source: https://github.com/gleanwork/mcp-config/blob/main/README.md

Execute this command to build all packages within the monorepo.

```bash
npm run build
```

--------------------------------

### Replace buildConfiguration with registry.createBuilder().buildConfiguration()

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

Use the `MCPConfigRegistry` to create a builder and then call `buildConfiguration` on the builder.

```typescript
// BEFORE (v2.x)
import { buildConfiguration } from '@gleanwork/mcp-config-schema'

const config = buildConfiguration('cursor', {
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
```

```typescript
// AFTER (v3.0)
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema'

const registry = new MCPConfigRegistry()
const builder = registry.createBuilder('cursor')
const config = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
```

--------------------------------

### Execute Release with release-it

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/RELEASE.md

Run the release-it command to automate the release process, including versioning, changelog generation, tagging, and pushing.

```sh
npx release-it
```

--------------------------------

### builder.buildConfiguration(options)

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Generates a client configuration object based on the provided options. Supports HTTP and stdio transports, server URLs, headers, environment variables, and URL template variables. An option `includeRootObject: false` can be used to exclude the outer wrapper key.

```APIDOC
## `builder.buildConfiguration(options)` — Generate client config

The primary builder method. Accepts `MCPConnectionOptions` specifying transport (`'http'` or `'stdio'`), server URL, headers, environment variables, and URL template variables. Returns the correct typed config object for the client. Pass `includeRootObject: false` to get just the flat server entry without the outer wrapper key.

### Parameters
#### Request Body
- **transport** (string) - Required - Specifies the transport type, either 'http' or 'stdio'.
- **serverUrl** (string) - Optional - The URL of the MCP server.
- **serverName** (string) - Optional - The name of the server configuration.
- **headers** (object) - Optional - Key-value pairs for HTTP headers.
- **env** (object) - Optional - Environment variables for stdio transport.
- **urlVariables** (object) - Optional - Variables to substitute into the `serverUrl` template.
- **includeRootObject** (boolean) - Optional - If false, excludes the outer wrapper key from the configuration.

### Request Example
```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });
const builder = registry.createBuilder('cursor');

// HTTP transport — native client (Cursor, Claude Code, VS Code, etc.)
const httpConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer my-token' },
});

// HTTP transport with URL template variables
const templateConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/{region}/mcp/{endpoint}',
  urlVariables: { region: 'us-east-1', endpoint: 'default' },
  serverName: 'my-server',
});

// stdio transport (local server via npx)
const stdioConfig = builder.buildConfiguration({
  transport: 'stdio',
  env: { MY_INSTANCE: 'my-instance', MY_API_TOKEN: 'token123' },
});

// Partial config (no root wrapper) — useful for merging
const partial = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my_server',
  includeRootObject: false,
});
```

### Response
#### Success Response (200)
- **mcpServers** (object) - An object containing server configurations.
  - **serverName** (object) - Configuration for a specific server.
    - **type** (string) - The transport type ('http' or 'stdio').
    - **url** (string) - The server URL (for http transport).
    - **command** (string) - The command to run (for stdio transport).
    - **args** (array) - Arguments for the command (for stdio transport).
    - **env** (object) - Environment variables for the command.
    - **headers** (object) - HTTP headers (for http transport).

### Response Example
```json
{
  "mcpServers": {
    "my-server": { "type": "http", "url": "https://api.example.com/mcp/default", "headers": { "Authorization": "Bearer my-token" } }
  }
}
```

```json
{
  "mcpServers": {
    "local": { "type": "stdio", "command": "npx", "args": ["-y", "@my-org/mcp-server"], "env": { "MY_INSTANCE": "my-instance", "MY_API_TOKEN": "token123" } }
  }
}
```

```json
{ "my_server": { "type": "http", "url": "https://api.example.com/mcp/default" } }
```
```

--------------------------------

### React Component for MCP Configuration Generation

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

A React component that generates MCP configuration for supported clients and copies it to the clipboard. It utilizes MCPConfigRegistry to get client information and create configuration builders.

```tsx
import React from 'react';
import { MCPConfigRegistry, ClientId } from '@gleanwork/mcp-config-schema/browser';

function MCPConfigGenerator() {
  const registry = new MCPConfigRegistry();

  const handleGenerateConfig = (clientId: ClientId, serverUrl: string) => {
    const builder = registry.createBuilder(clientId);
    const config = builder.buildConfiguration({
      transport: 'http',
      serverUrl,
      serverName: 'my-server',
    });

    navigator.clipboard.writeText(JSON.stringify(config, null, 2));
  };

  const clients = registry.getSupportedClients();

  return (
    <div>
      {clients.map((client) => (
        <button
          key={client.id}
          onClick={() => handleGenerateConfig(client.id, 'https://api.example.com/mcp')}
        >
          Configure {client.displayName}
        </button>
      ))}
    </div>
  );
}
```

--------------------------------

### Replace buildCommand with builder.buildCommand()

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

Instantiate `MCPConfigRegistry`, create a builder, and then use `builder.buildCommand()`.

```typescript
// BEFORE (v2.x)
import { buildCommand } from '@gleanwork/mcp-config-schema'

const command = buildCommand('cursor', {
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
```

```typescript
// AFTER (v3.0)
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema'

const registry = new MCPConfigRegistry()
const builder = registry.createBuilder('cursor')
const command = builder.buildCommand({
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
```

--------------------------------

### Validate Connection Options with Zod

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Provides Zod-based validation functions for connection options and server configurations. Use the safe variants (`safeValidate...`) to get a result object instead of throwing an error on validation failure.

```typescript
import {
  validateConnectionOptions,
  safeValidateConnectionOptions,
  safeValidateClientConfig,
  validateMcpServersConfig,
  safeValidateGooseConfig,
} from '@gleanwork/mcp-config-schema';

// Throws ZodError on failure
const opts = validateConnectionOptions({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});

// Safe variant — returns success/error object
const result = safeValidateConnectionOptions({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
});
if (!result.success) {
  console.error('Validation failed:', result.error.issues);
  // [{ path: ['serverUrl'], message: '...' }]
} else {
  console.log('Valid options:', result.data);
}

// Validate a generated config object
const mcpConfig = { mcpServers: { 'my-server': { type: 'http', url: 'https://...' } } };
const configResult = validateMcpServersConfig(mcpConfig);

// Validate a Goose config
const gooseResult = safeValidateGooseConfig({
  extensions: { 'my-server': { type: 'streamable_http', uri: 'https://...', enabled: true, name: 'my-server', envs: {}, env_keys: [], headers: {}, description: '', timeout: 300, bundled: null, available_tools: [] } },
});
```

--------------------------------

### Monorepo Build and Test Commands

Source: https://github.com/gleanwork/mcp-config/blob/main/CLAUDE.md

Standard npm scripts for building, testing, linting, and formatting all packages within the monorepo. Use `npx vitest run` for specific test files or `npm run test:watch` for continuous testing.

```bash
npm run build              # Build all packages (schema first, then glean)
npm run test               # Run all tests
npm run test:all           # Lint, typecheck, and test
npm run lint               # ESLint with auto-fix
npm run typecheck          # TypeScript type checking
npm run format             # Prettier formatting

# Run single test file
npx vitest run packages/mcp-config-schema/test/builder.test.ts

# Run tests in watch mode
npm run test:watch

# Package-specific commands
npm run build -w @gleanwork/mcp-config-schema
npm run test -w @gleanwork/mcp-config-glean
```

--------------------------------

### Run Project Tests

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v1-to-v2-semantic-renaming.md

Execute the project's test suite to ensure the migrated code functions as expected and that no runtime errors have been introduced.

```bash
npm test
```

--------------------------------

### stdio Configuration: API Token and Instance to Environment Variables

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

For stdio transport in v3.0, `instance` and `apiToken` are now configured via the `env` object, mapping to `GLEAN_INSTANCE` and `GLEAN_API_TOKEN` environment variables respectively.

```typescript
// BEFORE (v2.x)
import { MCPConfigRegistry, type MCPServerConfig } from '@gleanwork/mcp-config-schema'

const registry = new MCPConfigRegistry({
  serverPackage: '@gleanwork/local-mcp-server',
})
const builder = registry.createBuilder('claude-code')

const serverData: MCPServerConfig = {
  transport: 'stdio',
  instance: 'my-company',
  apiToken: 'my-token',
  serverName: 'glean_local',
}

const config = builder.buildConfiguration(serverData)
```

```typescript
// AFTER (v3.0)
import { MCPConfigRegistry, type MCPConnectionOptions } from '@gleanwork/mcp-config-schema'

const registry = new MCPConfigRegistry({
  serverPackage: '@gleanwork/local-mcp-server',
})
const builder = registry.createBuilder('claude-code')

const serverData: MCPConnectionOptions = {
  transport: 'stdio',
  env: {
    GLEAN_INSTANCE: 'my-company',
    GLEAN_API_TOKEN: 'my-token',
  },
  serverName: 'glean_local',
}

const config = builder.buildConfiguration(serverData)
```

--------------------------------

### Build HTTP Client Configuration

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Use for native clients like Cursor, Claude Code, and VS Code. Specify server URL, headers, and other options.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });
const builder = registry.createBuilder('cursor');

// HTTP transport — native client (Cursor, Claude Code, VS Code, etc.)
const httpConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer my-token' },
});
```

--------------------------------

### Initialize MCPConfigRegistry

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Instantiate MCPConfigRegistry to load and validate client definitions. Pass RegistryOptions to inject vendor-specific behavior like server package names, environment variable names, and command builders for HTTP and stdio transports.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

// Vendor-neutral registry (no serverPackage = stdio not supported)
const registry = new MCPConfigRegistry();

// Vendor-specific registry (enables stdio transport + CLI commands)
const vendorRegistry = new MCPConfigRegistry({
  serverPackage: '@my-org/mcp-server',
  tokenEnvVarName: 'MY_API_TOKEN',
  commandBuilder: {
    http: (clientId, options) =>
      `npx my-cli install --client ${clientId} --url ${options.serverUrl}`,
    stdio: (clientId, options) => {
      const envFlags = Object.entries(options.env || {})
        .map(([k, v]) => `--env ${k}=${v}`)
        .join(' ');
      return `npx my-cli install --client ${clientId} ${envFlags}`;
    },
  },
  serverNameBuilder: (options) => {
    const base = options.serverName || (options.transport === 'stdio' ? 'local' : 'default');
    return `myvendor_${base}`;
  },
});

// Query registry metadata
const cursorConfig = registry.getConfig('cursor');
console.log(cursorConfig?.displayName);   // "Cursor"
console.log(cursorConfig?.transports);    // ['stdio', 'http']

const allClients = registry.getAllConfigs();
const httpNative = registry.getNativeHttpClients();    // clients with native HTTP
const bridgeOnly = registry.getBridgeRequiredClients(); // clients needing mcp-remote
const macClients = registry.getClientsByPlatform('darwin');
const oneClick   = registry.getClientsWithOneClick();  // Cursor, VS Code
const supported  = registry.getSupportedClients();     // userConfigurable: true
```

--------------------------------

### Browser Support for MCP Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

Utilize the `/browser` import path for browser environments. This allows you to generate MCP configurations directly in the browser and copy them to the clipboard. Note that file operations are not available in browsers.

```javascript
// Browser-safe import
import { MCPConfigRegistry, ConfigBuilder } from '@gleanwork/mcp-config-schema/browser';

const registry = new MCPConfigRegistry();
const builder = registry.createBuilder('cursor');

// Generate configuration (works in browser)
const config = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://your-server.com/mcp/default',
});

// Copy to clipboard
avigator.clipboard.writeText(JSON.stringify(config, null, 2));
```

--------------------------------

### MCPConfigRegistry: Before v3.0 (cliPackage)

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

Illustrates the usage of the `cliPackage` option in v2.x for configuring vendor-specific CLI commands.

```typescript
// BEFORE (v2.x) - with cliPackage
const registry = new MCPConfigRegistry({
  serverPackage: '@my-org/mcp-server',
  cliPackage: '@my-org/configure-mcp',
})

const builder = registry.createBuilder('cursor')
const command = builder.buildCommand({
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
// Result: "npx -y @my-org/configure-mcp remote --url https://example.com/mcp --client cursor"
```

--------------------------------

### Stdio-only Client Configuration

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

JSON configuration for stdio-only clients like Claude Desktop, Junie, and JetBrains AI. Requires the `mcp-remote` bridge for HTTP servers.

```json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-server.com/mcp/default"]
    }
  }
}
```

--------------------------------

### Build Partial Configuration (No Root Wrapper)

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Generates a configuration object without the outer wrapper key, useful for merging into existing configuration files.

```typescript
// Partial config (no root wrapper) — useful for merging
const partial = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my_server',
  includeRootObject: false,
});
```

--------------------------------

### Configure stdio Transport

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/README.md

Configure the MCPConfigRegistry for stdio transport by providing your server package name. Then, create a builder and generate configuration with custom environment variables.

```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({
  serverPackage: '@your-org/mcp-server', // Your stdio server package
});

const builder = registry.createBuilder('cursor');

// Generate configuration for stdio transport with custom environment variables
const config = builder.buildConfiguration({
  transport: 'stdio',
  env: {
    MY_INSTANCE: 'my-instance',
    MY_API_TOKEN: 'my-api-token',
  },
});
```

--------------------------------

### Run All Checks (Lint, Typecheck, Test) with npm

Source: https://github.com/gleanwork/mcp-config/blob/main/README.md

This command runs a comprehensive suite of checks including linting, type checking, and tests for all packages.

```bash
npm run test:all
```

--------------------------------

### Create Glean Registry and Builder

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Initializes a pre-configured registry with Glean defaults and creates a builder for a specific client.

```typescript
import {
  createGleanRegistry,
  createGleanServerUrlEnv,
  createGleanHeaders,
  buildGleanMcpUrl,
  buildGleanServerName,
  normalizeGleanServerName,
  normalizeGleanProductName,
  GLEAN_ENV,
  GLEAN_REGISTRY_OPTIONS,
} from '@gleanwork/mcp-config-glean';

// Pre-configured registry with Glean defaults
const registry = createGleanRegistry();
const builder = registry.createBuilder('cursor');
```

--------------------------------

### Build One-Click URL: Handling Authentication Token

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

The `buildOneClickUrl` method in v3.0 now expects the authentication token to be provided within the `headers` object, similar to other configuration updates.

```typescript
// BEFORE (v2.x)
const url = builder.buildOneClickUrl({
  transport: 'http',
  serverUrl: 'https://example.com/mcp/default',
  serverName: 'my-server',
  apiToken: authToken,
})
```

```typescript
// AFTER (v3.0)
const url = builder.buildOneClickUrl({
  transport: 'http',
  serverUrl: 'https://example.com/mcp/default',
  serverName: 'my-server',
  headers: authToken ? { Authorization: `Bearer ${authToken}` } : undefined,
})
```

--------------------------------

### Run Tests Across All Packages with npm

Source: https://github.com/gleanwork/mcp-config/blob/main/README.md

Use this command to run all tests across all packages in the monorepo.

```bash
npm run test
```

--------------------------------

### builder.toString(config)

Source: https://context7.com/gleanwork/mcp-config/llms.txt

Serializes a configuration object into its client-specific string format. Most clients use JSON, while Goose uses YAML and Codex uses TOML.

```APIDOC
## `builder.toString(config)`

### Description
Serializes a config object to its client-specific format string: JSON for most clients, YAML for Goose, TOML for Codex.

### Usage
```typescript
import { MCPConfigRegistry } from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry({ serverPackage: '@my-org/mcp-server' });

// JSON output (Cursor, Claude Code, VS Code, etc.)
const cursorBuilder = registry.createBuilder('cursor');
const config = cursorBuilder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});
console.log(cursorBuilder.toString(config));
// {
//   "mcpServers": {
//     "my-server": { "type": "http", "url": "https://api.example.com/mcp/default" }
//   }
// }

// YAML output (Goose)
const gooseBuilder = registry.createBuilder('goose');
const gooseConfig = gooseBuilder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});
console.log(gooseBuilder.toString(gooseConfig));
// extensions:
//   my-server:
//     enabled: true
//     name: my-server
//     type: streamable_http
//     uri: https://api.example.com/mcp/default
//     ...

// TOML output (Codex)
const codexBuilder = registry.createBuilder('codex');
const codexConfig = codexBuilder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
});
console.log(codexBuilder.toString(codexConfig));
// [mcp_servers.my-server]
// url = "https://api.example.com/mcp/default"
```
```

--------------------------------

### MCPConfigRegistry: After v3.0 (with commandBuilder)

Source: https://github.com/gleanwork/mcp-config/blob/main/packages/mcp-config-schema/docs/migrations/v2-to-v3-vendor-neutral.md

Shows how to use a custom `commandBuilder` callback in v3.0 to generate CLI commands for non-native clients.

```typescript
// AFTER (v3.0) - with commandBuilder callback
const registry = new MCPConfigRegistry({
  serverPackage: '@my-org/mcp-server',
  commandBuilder: {
    http: (clientId, options) => {
      return `npx -y @my-org/cli install --url ${options.serverUrl} --client ${clientId}`;
    },
    stdio: (clientId, options) => {
      const envFlags = Object.entries(options.env || {})
        .map(([k, v]) => `--env ${k}=${v}`)
        .join(' ');
      return `npx -y @my-org/cli install --client ${clientId} ${envFlags}`;
    },
  },
})

const builder = registry.createBuilder('cursor')
const command = builder.buildCommand({
  transport: 'http',
  serverUrl: 'https://example.com/mcp',
})
// Result: "npx -y @my-org/cli install --url https://example.com/mcp --client cursor"
```