@gleanwork/mcp-config-schema

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

用于 MCP 客户端配置的 类型安全策略和构建器

中文使用文档
文档目录29 节
  1. 问题
  2. 解决办法
  3. 安装
  4. 快速启动
  5. stdio 运输( 本地服务器)
  6. HTTP 传输( 远程服务器)
  7. HTTP 有信头的运输
  8. 有变量的 URL 模板
  9. 此套件会做什么
  10. 支持客户端
  11. 中央管理的客户
  12. 核心用途
  13. 查询客户端能力
  14. 客户类型
  15. 生成配置
  16. 验证配置
  17. 浏览器支持
  18. 反应示例
  19. 配置示例
  20. 原生 HTTP 客户端( Claude Code, VS Code)
  21. 仅限Stdio客户端(Claude桌面、Junie、JetBrains AI)
  22. 鹅 (YAML 有本地 HTTP 格式)
  23. API 参考
  24. 发展
  25. 文档
  26. 图标
  27. 商标
  28. 许可证
  29. 捐款

@gleanwork/mcp-config-schema (英语)

MCP(模式上下文协议)客户端的型式安全配置策略和构建器.

问题

MCP服务器需要跨越许多不同的AI编码助理——Claude Code, VS Code, Cursor, Claude Desktop, Windsurf, Goose, Codex, 等. 每个客户都有自己的:

  • 配置格式: JSON,YAML,或TOML (英语)
  • 文件位置: macOS、 Linux 和 Windows 的不同路径
  • 属性名称数字 : url 对 serverUrl 对 uri, (中文(简体) ), command 对 cmd, (中文(简体) ), mcpServers 对 servers 对 extensions
  • 运输支助:有些在本地支持HTTP,有些则要求 mcp-remote 桥
  • 认证模式: 页眉、环境变量或 OAuth

没有统一的解决方案,MCP服务器作者面临一个维护的噩梦:为每个客户编写和维护单独的配置逻辑,跟踪哪些客户支持哪些特性,并跟上整个生态系统的变化.

解决办法

此软件包提供了 单一真相来源 用于MCP客户端配置. 您一次描述您的连接, 它为任何支持的客户端生成正确的配置 :

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

软件包处理所有复杂之处:格式差异,属性映射,平台专用路径,传输桥接,和一击安装URL.

安装

npm install @gleanwork/mcp-config-schema

快速启动

stdio 运输( 本地服务器)

对于 stdio 传输, 以您的软件包名称提供注册选项, 然后直接通过环境变量 :

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 传输( 远程服务器)

为了连接到基于 HTTP 的 MCP 服务器,不需要额外的配置 :

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 有信头的运输

对于带有认证或自定义标题的 HTTP 运输 :

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 模板

对于带有模板变量的动态URL(与 MCP 登记册规格相匹配):

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

此套件会做什么

这个套装是 单一真相来源 用于MCP客户端配置. 它规定:

  • 书记官处 * 所有MCP客户及其能力
  • 配置构建器 为每个客户端生成正确的配置
  • 类型安全计划 有类型脚本和 Zod 验证
  • 浏览器支持 用于网络配置工具
  • 客户检测 确定哪些客户需要特殊处理

支持客户端

关于每个客户的详细配置实例和要求,见 (单位:千美元)。 。 。 .

中央管理的客户

  • 聊天游戏 - 需要网络用户界面配置
  • Claude代表团队/企业 - 由组织管理人员管理

核心用途

查询客户端能力

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

客户类型

每个客户端都声明一个或多个 types 描述它运行的地方。 一个客户端可以是一个以上(例如:鹅同时将一个桌面应用程序和一个CLI同时运送). 用于通过表面分组或过滤客户端——例如,用于构建一个可过滤的支持主机列表:

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

可安装性是一个单独的轴 (userConfigurable: 用户安装客户端与集中管理的客户端.

消费者可以为集中管理的客户提供设置目的地,而无需 在共享客户端元数据中添加供应商专用URL:

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

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

生成配置

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": "..." } } }

部分配置( 没有根对象)

这个 includeRootObject 选项允许您仅生成服务器配置条目,而不使用外包装( )mcpServers, (中文(简体) ), servers,或 extensions 视客户而定)。 当您需要将配置合并到一个已有的设置时,此功能是有用的 :

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

验证配置

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 导入路径 :

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

说明: 文件操作( E)writeConfiguration, (中文(简体) ), getConfigPath)在浏览器中不可用,会丢出清晰的错误消息.

反应示例

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

配置示例

有关所有客户端的完整配置示例,请参见 (单位:千美元)

原生 HTTP 客户端( Claude Code, VS Code)

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

仅限Stdio客户端(Claude桌面、Junie、JetBrains AI)

这些客户需要 mcp-remote hTTP 服务器的桥接 :

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

鹅 (YAML 有本地 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 参考

关于完整的 API 文档,请参见 TypeScript 定义 src/types.ts 财务报告和审定财务报表 src/registry.ts所有出口包括JSDoc的评论.

主要出口:

  • MCPConfigRegistry - 创建配置构建器的主要切入点
  • BaseConfigBuilder - 客户特定构建者的基础类
  • MCPConnectionOptions - 备选方案 buildConfiguration()
  • RegistryOptions - 登记处的自定义备选方案
  • ClientId - 所有支持客户身份识别的联盟类型

发展

# 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

文档

图标

每个客户端都传送一个 SVG 主机图标,作为内置字符串(没有捆绑/装入器设置)和下面的原始文件可用 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) ?? '' }} />

每个客户端可选图标; getClientIcon 返回时 undefined 当一个没有运出。 内部的 SVG ids 每个图标都有命名空间,因此多个图标可以在同页上被内嵌而不会相撞. 见 icons/README.md 要添加或更新一个.

商标

产品名称和客户端图标 icons/ 是各自所有者的商标。 列入这些软件只是为了识别该软件包所支持的MCP主机应用程序(命名使用);列入这些软件包并不意味着与这些所有者有隶属关系或得到他们的认可。 品牌图标来源于 视频, (中文(简体) ), 简单图标 (CC0),和官方品牌资产.

许可证

麻省理工学院-见 自由主义 详细文件

捐款

这个包是Glean MCP生态系统的一部分. 关于议题和贡献,请访问资料库.

版本与发布记录

@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 是什么?

用于 MCP 客户端配置的 类型安全策略和构建器

如何安装 @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 和提交记录判断。