@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生态系统的一部分. 关于议题和贡献,请访问资料库.