# @gleanwork/mcp-config-schema 中文文档

规范地址：https://npmcn.com/package/%40gleanwork/mcp-config-schema/

版本：5\.4\.1
npm 元数据更新时间：2026-07-29T20:49:42.929Z
中文译文更新时间：2026-11-16T15:40:44.610Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gleanwork/mcp-config-schema
原文对照：https://npmcn.com/package/%40gleanwork/mcp-config-schema/?lang=original
项目主页：https://github.com/gleanwork/mcp-config#readme
源码仓库：https://github.com/gleanwork/mcp-config

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.6 MB，59 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：4 个
- peer 依赖：zod ^3\.25\.0 \|\| ^4\.0\.0
- 首次发布：2025-08-19T01:17:19.702Z
- 最新版本发布：2026-07-29T20:49:42.434Z
- 近 30 天下载量：70547（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 20 个）

## 中文简介

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

## 安装

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

也可以使用：`pnpm add @gleanwork/mcp-config-schema`、`yarn add @gleanwork/mcp-config-schema`、`bun add @gleanwork/mcp-config-schema`

## README

# @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客户端配置. 您一次描述您的连接, 它为任何支持的客户端生成正确的配置 :

```typescript
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.

## 安装

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

## 快速启动

### stdio 运输( 本地服务器)

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

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

### HTTP 传输( 远程服务器)

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

```typescript
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 运输 :

```typescript
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 登记册规格相匹配):

```typescript
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 验证
-   **浏览器支持** 用于网络配置工具
-   **客户检测** 确定哪些客户需要特殊处理

## 支持客户端

关于每个客户的详细配置实例和要求,见 **[(单位:千美元)](https://npmcn.com/package/%40gleanwork/mcp-config-schema/CLIENTS.md)**。 。 。 .

### 中央管理的客户

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

## 核心用途

### 查询客户端能力

```typescript
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同时运送). 用于通过表面分组或过滤客户端——例如,用于构建一个可过滤的支持主机列表:

```typescript
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:

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

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

### 生成配置

```typescript
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` 视客户而定)。 当您需要将配置合并到一个已有的设置时,此功能是有用的 :

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

### 验证配置

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

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

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

### 反应示例

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

## 配置示例

> **有关所有客户端的完整配置示例,请参见 [(单位:千美元)](https://npmcn.com/package/%40gleanwork/mcp-config-schema/CLIENTS.md)**

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

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

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

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

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

### 鹅 (YAML 有本地 HTTP 格式)

```yaml
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`](https://npmcn.com/package/%40gleanwork/mcp-config-schema/src/types.ts) 财务报告和审定财务报表 [`src/registry.ts`](https://npmcn.com/package/%40gleanwork/mcp-config-schema/src/registry.ts)所有出口包括JSDoc的评论.

主要出口:

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

## 发展

```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
```

## 文档

-   **[(单位:千美元)](https://npmcn.com/package/%40gleanwork/mcp-config-schema/CLIENTS.md)** - 有详细配置实例的综合客户兼容矩阵
-   **[API 参考](https://npmcn.com/package/%40gleanwork/mcp-config-schema/#readme-api-reference)** - 完成API文档

## 图标

每个客户端都传送一个 SVG 主机图标,作为内置字符串(没有捆绑/装入器设置)和下面的原始文件可用 `icons/`数字 :

```typescript
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`](https://npmcn.com/package/%40gleanwork/mcp-config-schema/icons/README.md) 要添加或更新一个.

## 商标

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

## 许可证

麻省理工学院-见 [自由主义](https://npmcn.com/package/%40gleanwork/mcp-config-schema/LICENSE) 详细文件

## 捐款

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

## 常见问题

### @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 和提交记录判断。

