@gleanwork/mcp-config-schema

中文文档
5.4.1发布于 2026/07/30MITTypeScriptESM + CJS近 30 天下载 7.1万

Type-safe schemas and builders for MCP client configurations

原始使用文档
文档目录29 节
  1. The Problem
  2. The Solution
  3. Installation
  4. Quick Start
  5. stdio Transport (Local Server)
  6. HTTP Transport (Remote Server)
  7. HTTP Transport with Headers
  8. URL Templates with Variables
  9. What This Package Does
  10. Supported Clients
  11. Centrally Managed Clients
  12. Core Usage
  13. Query Client Capabilities
  14. Client Types
  15. Generate Configurations
  16. Validate Configurations
  17. Browser Support
  18. React Example
  19. Configuration Examples
  20. Native HTTP Client (Claude Code, VS Code)
  21. stdio-only Clients (Claude Desktop, Junie, JetBrains AI)
  22. Goose (YAML format with native HTTP)
  23. API Reference
  24. Development
  25. Documentation
  26. Icons
  27. Trademarks
  28. License
  29. Contributing

@gleanwork/mcp-config-schema

Type-safe configuration schemas and builders for MCP (Model Context Protocol) clients.

The Problem

MCP servers need to work across many different AI coding assistants—Claude Code, VS Code, Cursor, Claude Desktop, Windsurf, Goose, Codex, and more. Each client has its own:

  • Configuration format: JSON, YAML, or TOML
  • File location: Different paths on macOS, Linux, and Windows
  • Property names: url vs serverUrl vs uri, command vs cmd, mcpServers vs servers vs extensions
  • Transport support: Some support HTTP natively, others require the mcp-remote bridge
  • Authentication patterns: Headers, environment variables, or OAuth

Without a unified solution, MCP server authors face a maintenance nightmare: writing and maintaining separate configuration logic for each client, tracking which clients support which features, and keeping up with changes across the ecosystem.

The Solution

This package provides a single source of truth for MCP client configurations. You describe your connection once, and it generates the correct configuration for any supported client:

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

const registry = new MCPConfigRegistry();

// Same options work for any client
const options = {
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer token' },
};

// Generate correct config for each client
registry.createBuilder('cursor').buildConfiguration(options);      // → JSON with mcpServers
registry.createBuilder('vscode').buildConfiguration(options);      // → JSON with servers
registry.createBuilder('goose').buildConfiguration(options);       // → YAML with extensions
registry.createBuilder('claude-desktop').buildConfiguration(options); // → JSON with mcp-remote bridge

The package handles all the complexity: format differences, property mapping, platform-specific paths, transport bridging, and one-click installation URLs.

Installation

npm install @gleanwork/mcp-config-schema

Quick Start

stdio Transport (Local Server)

For stdio transport, provide registry options with your package names, then pass environment variables directly:

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',
  },
});

HTTP Transport (Remote Server)

For connecting to HTTP-based MCP servers, no additional configuration is needed:

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

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

// Generate configuration for HTTP transport
const config = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://your-server.com/mcp/default',
  serverName: 'my-server',
});

// Write configuration to the client's config file (Node.js only)
await builder.writeConfiguration({
  transport: 'http',
  serverUrl: 'https://your-server.com/mcp/default',
  serverName: 'my-server',
});

// Generate one-click install URL for supported clients (Cursor, VS Code)
const oneClickUrl = builder.buildOneClickUrl({
  transport: 'http',
  serverUrl: 'https://your-server.com/mcp/default',
  serverName: 'my-server',
});
// Returns: cursor://anysphere.cursor-deeplink/mcp/install?name=my-server&config=...

HTTP Transport with Headers

For HTTP transport with authentication or custom headers:

const config = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: {
    Authorization: 'Bearer my-api-token',
    'X-Custom-Header': 'custom-value',
  },
});

URL Templates with Variables

For dynamic URLs with template variables (aligned with MCP registry specification):

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

What This Package Does

This package serves as the Single Source of Truth for MCP client configurations. It provides:

  • Registry of all MCP clients and their capabilities
  • Configuration builders that generate correct configs for each client
  • Type-safe schemas with TypeScript types and Zod validation
  • Browser support for web-based configuration tools
  • Client detection to identify which clients need special handling

Supported Clients

For detailed configuration examples and requirements for each client, see CLIENTS.md.

Centrally Managed Clients

  • ChatGPT - Requires web UI configuration
  • Claude for Teams/Enterprise - Managed by organization admins

Core Usage

Query Client Capabilities

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

const registry = new MCPConfigRegistry();

// Get client configuration
const cursorConfig = registry.getConfig('cursor');
console.log(cursorConfig.displayName); // "Cursor"
console.log(cursorConfig.userConfigurable); // true
console.log(cursorConfig.transports); // ['stdio', 'http']
console.log(cursorConfig.types); // ['ide']

// Query different client groups
const httpClients = registry.getNativeHttpClients();
const bridgeClients = registry.getBridgeRequiredClients();
const macClients = registry.getClientsByPlatform('darwin');

Client Types

Every client declares one or more types describing where it runs. A client can be more than one (e.g. Goose ships both a desktop app and a CLI). Use these to group or filter clients by surface — for example, to build a filterable list of supported hosts:

import {
  MCPConfigRegistry,
  CLIENT_TYPES, // readonly ['cli', 'desktop', 'ide', 'web']
  TYPE_LABELS, // { cli: 'CLI', desktop: 'Desktop', ide: 'IDE', web: 'Web' }
  type ClientType,
} from '@gleanwork/mcp-config-schema';

const registry = new MCPConfigRegistry();
const all = registry.getAllConfigs();

// Filter by type
const cliClients = all.filter((c) => c.types.includes('cli'));

// Group by type, with display labels (a client may appear under several)
for (const type of CLIENT_TYPES) {
  const inType = all.filter((c) => c.types.includes(type));
  console.log(`${TYPE_LABELS[type]}: ${inType.map((c) => c.displayName).join(', ')}`);
}

Installability is a separate axis (userConfigurable): user-installable clients vs. centrally managed ones.

Consumers can provide setup destinations for centrally managed clients without adding vendor-specific URLs to the shared client metadata:

const registry = new MCPConfigRegistry({
  managedSetupUrls: {
    'cursor-team': 'https://example.com/admin/mcp',
  },
});

registry.getManagedSetupUrl('cursor-team'); // https://example.com/admin/mcp

Generate Configurations

const builder = registry.createBuilder('claude-code');

// HTTP transport (remote server) configuration
const remoteConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  headers: { Authorization: 'Bearer your-token' }, // Optional headers
});

// HTTP transport with URL template variables
const dynamicConfig = 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) configuration
// Note: Requires registry options with serverPackage
const localConfig = builder.buildConfiguration({
  transport: 'stdio',
  env: {
    YOUR_INSTANCE: 'your-instance',
    YOUR_API_TOKEN: 'your-api-token',
  },
});

// Generate partial configuration (without root object)
const partialConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my-server',
  includeRootObject: false, // Returns just the server entry without mcpServers wrapper
});
// Returns: { "my-server": { "type": "http", "url": "..." } }
// Instead of: { "mcpServers": { "my-server": { "type": "http", "url": "..." } } }

Partial Configuration (without root object)

The includeRootObject option allows you to generate just the server configuration entry without the outer wrapper (mcpServers, servers, or extensions depending on the client). This is useful when you need to merge configurations into an existing setup:

// Generate partial config for merging into existing configuration
const partialConfig = builder.buildConfiguration({
  transport: 'http',
  serverUrl: 'https://api.example.com/mcp/default',
  serverName: 'my_server',
  includeRootObject: false,
});

// Now you can easily merge it into an existing config
const existingConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
existingConfig.mcpServers = {
  ...existingConfig.mcpServers,
  ...partialConfig,
};
fs.writeFileSync(configPath, JSON.stringify(existingConfig, null, 2));

Validate Configurations

import {
  validateConnectionOptions,
  safeValidateConnectionOptions,
} from '@gleanwork/mcp-config-schema';

// Validate connection options
const result = safeValidateConnectionOptions({
  transport: 'http',
  serverUrl: 'https://your-server.com/mcp/default',
});

if (!result.success) {
  console.error('Validation errors:', result.error.issues);
}

Browser Support

This package works in browsers! Use the /browser import path:

// 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
navigator.clipboard.writeText(JSON.stringify(config, null, 2));

Note: File operations (writeConfiguration, getConfigPath) are not available in browsers and will throw clear error messages.

React Example

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>
  );
}

Configuration Examples

📖 For complete configuration examples for all clients, see CLIENTS.md

Native HTTP Client (Claude Code, VS Code)

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://your-server.com/mcp/default"
    }
  }
}

stdio-only Clients (Claude Desktop, Junie, JetBrains AI)

These clients require mcp-remote bridge for HTTP servers:

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

Goose (YAML format with native HTTP)

extensions:
  my-server:
    enabled: true
    name: my-server
    type: streamable_http
    uri: https://your-server.com/mcp/default
    envs: {}
    env_keys: []
    headers: {}
    description: ''
    timeout: 300
    bundled: null
    available_tools: []

API Reference

For complete API documentation, see the TypeScript definitions in src/types.ts and src/registry.ts. All exports include JSDoc comments.

Key exports:

  • MCPConfigRegistry - Main entry point for creating configuration builders
  • BaseConfigBuilder - Base class for client-specific builders
  • MCPConnectionOptions - Options for buildConfiguration()
  • RegistryOptions - Options for customizing the registry
  • ClientId - Union type of all supported client identifiers

Development

# 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

Documentation

  • CLIENTS.md - Comprehensive client compatibility matrix with detailed configuration examples
  • API Reference - Complete API documentation

Icons

Each client ships an SVG host icon, available as an inline string (no bundler/loader setup) and as a raw file under icons/:

import { CLIENT, CLIENT_ICONS, getClientIcon } from '@gleanwork/mcp-config-schema';

getClientIcon(CLIENT.CURSOR); // '<svg …>…</svg>' (or undefined if none)

// React (icons inherit text color via the surrounding `color`)
<span style={{ color: '#111' }} dangerouslySetInnerHTML={{ __html: getClientIcon(clientId) ?? '' }} />

Icons are optional per client; getClientIcon returns undefined when one isn't shipped. Internal SVG ids are namespaced per icon, so multiple icons can be inlined on the same page without collisions. See icons/README.md to add or update one.

Trademarks

Product names and the client icons under icons/ are trademarks of their respective owners. They are included only to identify the MCP host applications this package supports (nominative use); their inclusion does not imply affiliation with or endorsement by those owners. Brand icons are sourced from svgl, Simple Icons (CC0), and official brand assets.

License

MIT - See LICENSE file for details

Contributing

This package is part of the Glean MCP ecosystem. For issues and contributions, please visit the repository.

版本与发布记录

@gleanwork/mcp-config-schema 共发布 41 个版本,首次发布于 2025/08/19;过去 12 个月发布了 20 个版本。

版本发布日期距今
5.4.1latest2026/07/303 个月前
5.4.02026/07/164 个月前
5.3.02026/07/154 个月前
5.2.02026/06/075 个月前
5.1.02026/06/075 个月前
5.0.02026/05/036 个月前

其他发布通道:beta → 3.0.0-beta.0。

关于 @gleanwork/mcp-config-schema 的常见问题

@gleanwork/mcp-config-schema 是什么?

Type-safe schemas and builders for MCP client configurations

如何安装 @gleanwork/mcp-config-schema?

在项目目录运行 npm install @gleanwork/mcp-config-schema,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^3.25.0 || ^4.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gleanwork/mcp-config-schema 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gleanwork/mcp-config-schema 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gleanwork/mcp-config-schema 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gleanwork/mcp-config-schema 可以商用吗?

@gleanwork/mcp-config-schema 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gleanwork/mcp-config-schema 的下载量有多少?

根据 npm 官方下载统计,@gleanwork/mcp-config-schema 在 2026/10/17 – 2026/11/15 这 30 天内被下载 70,547 次,日均约 2,352 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gleanwork/mcp-config-schema 还在维护吗?

最新版本 5.4.1 发布于 2026/07/30(3 个月前);至今共发布 41 个版本,其中过去 12 个月发布了 20 个;首次发布于 2025/08/19。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。