# @github/mcp-registry 中文文档

规范地址：https://npmcn.com/package/%40github/mcp-registry/

版本：0\.1\.7
npm 元数据更新时间：2026-10-15T16:20:51.440Z
中文译文更新时间：2026-11-16T11:02:54.628Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：113 kB，38 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：1 个
- 首次发布：2026-04-01T11:39:33.821Z
- 最新版本发布：2026-09-07T13:05:53.181Z
- 近 30 天下载量：32690（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

用于MCP Register API的TypeScript SDK——包括类型,即用即用客户端,以及用于企业许可列表执行的确定指纹计算.

## 安装

```sh
npm install @github/mcp-registry
```

也可以使用：`pnpm add @github/mcp-registry`、`yarn add @github/mcp-registry`、`bun add @github/mcp-registry`

## README

# @github/mcp-注册

脚本 SDK 类型 [MCP 书记官处](https://github.com/mcp) ——包括注册API客户端,生成类型,以及用于企业许可名单执行的决定性指纹计算.

## 安装

```bash
npm install @github/mcp-registry
```

## 注册客户端

```typescript
import { RegistryClient } from '@github/mcp-registry';

const client = new RegistryClient();

// Search for servers
const servers = await client.searchServers({ query: 'github', limit: 5 });
for (const s of servers) {
  console.log(`${s.server.name}@${s.server.version}`);
}

// Get a specific server
const server = await client.getServer({ name: 'io.github.user/repo' });

// Get a specific version
const pinned = await client.getServer({
  name: 'io.github.user/repo',
  version: '1.2.0',
});

// Parse "name@version" format
const entry = await client.getDsl('io.github.user/repo@1.2.0');
```

### 配置

```typescript
const client = new RegistryClient({
  baseUrl: 'https://api.mcp.github.com/v0.1', // default
  cacheTtlMs: 5 * 60 * 1000,                  // 5 minutes (default)
  timeoutMs: 30_000,                           // 30 seconds (default)
  fetch: customFetch,                          // optional custom fetch
});
```

### 处理错误

客户端返回 `null` 404和掷出 `RegistryError` 用于其他 HTTP 错误 :

```typescript
import { RegistryClient, RegistryError } from '@github/mcp-registry';

const server = await client.getServer({ name: 'example/server' });
if (!server) {
  console.log('Not found');
}
```

## 指纹计算

用于企业许可列表执行的定型SHA-256指纹——计算出与注册后端相同的指纹.

```typescript
import { computeFingerprint, verifyFingerprint, commandToRegistryType } from '@github/mcp-registry';

// Remote server
const fp = computeFingerprint({
  remotes: [{ url: 'https://mcp.example.com/sse' }],
});

// Local package
const registryType = commandToRegistryType('npx'); // → "npm"
const fp2 = computeFingerprint({
  packages: [{ registryType: registryType!, identifier: '@playwright/mcp' }],
});

// Verify against the enterprise allowlist
const matches = verifyFingerprint(
  { packages: [{ registryType: 'npm', identifier: '@playwright/mcp' }] },
  allowlistEntry.server.fingerprints ?? {},
);
```

### 命令绘图

| 命令 | 登记类型 |
| --- | --- |
| `npx`, (中文(简体) ), `npm` | `npm` |
| `uvx`, (中文(简体) ), `pip` | `pypi` |
| `dotnet` | `nuget` |
| `docker` | `docker` |
| `brew` | `homebrew` |

## DSL 引擎

DSL引擎从服务器定义中提取可配置字段,验证用户提供的配置,并计算出发射计划(启动服务器所需的命令+env+头).

### 快速启动——注册客户端+DSL引擎

```typescript
import { RegistryClient, DslEngine } from '@github/mcp-registry';

// 1. Fetch a server definition from the registry
const client = new RegistryClient();
const response = await client.getServer({ name: 'io.github.user/repo' });
if (!response) throw new Error('Server not found');

// 2. Create a DSL engine from the response
const engine = DslEngine.fromServerResponse(response);

// 3. Discover what configuration the server needs
const requiredFields = engine.getRequiredFields();
for (const field of requiredFields) {
  console.log(`${field.key} (${field.type})${field.isSecret ? ' [secret]' : ''}`);
}

// 4. Validate user-provided configuration
const validation = engine.validate({
  environmentVariables: { API_KEY: 'sk-...' },
});
if (!validation.valid) {
  console.log('Missing:', validation.missingFields.map(f => f.key));
}

// 5. Resolve a launch plan
const result = engine.resolve({
  environmentVariables: { API_KEY: 'sk-...' },
});

if (result.complete && result.plan) {
  if (result.plan.type === 'package') {
    // Start a local process
    console.log('Command:', result.plan.command.join(' '));
    console.log('Env:', result.plan.env);
  } else {
    // Connect to a remote server
    console.log('Endpoint:', result.plan.endpoint);
    console.log('Headers:', result.plan.headers);
  }
}
```

### 提取字段

使用 `extractConfigurableFields` 当您不需要全引擎时:

```typescript
import { extractConfigurableFields } from '@github/mcp-registry';
import type { ServerDetail } from '@github/mcp-registry';

const fields = extractConfigurableFields(server);
// fields: FieldSpec[] — key, type, required, isSecret, enumValues, etc.

// Extract fields for a specific remote instead of the default package
const remoteFields = extractConfigurableFields(server, { remoteIndex: 0 });
```

### 解决发射计划

```typescript
import { resolveLaunchPlan } from '@github/mcp-registry';

// Package-based (local process)
const plan = resolveLaunchPlan({
  spec: server,
  config: { environmentVariables: { API_KEY: 'sk-...' } },
});
// plan.type === 'package'
// plan.command → ['npx', '-y', '@scope/mcp-server@1.0.0']
// plan.env → { API_KEY: 'sk-...' }

// Remote-based (HTTP connection)
const remotePlan = resolveLaunchPlan({
  spec: server,
  config: { headers: { Authorization: 'Bearer token' } },
  remoteIndex: 0,
});
// remotePlan.type === 'remote'
// remotePlan.endpoint → 'https://api.example.com/mcp'
// remotePlan.headers → { Authorization: 'Bearer token' }
```

### 假设安装选择

用一个引擎呼叫来检查每个广告包和遥控器 为每个阵列索引构建一个引擎 :

```typescript
const result = engine.enumerateInstallChoices(
  { headers: { Authorization: 'Bearer ...' } },
  {
    policy: choice => choice.transport === 'sse'
      ? { decision: 'denied', code: 'sse-disabled', reason: 'SSE is disabled by policy' }
      : { decision: 'allowed' },
  },
);

// Packages first, then remotes, preserving each source array's order.
for (const choice of result.advertisedChoices) {
  console.log(choice.choiceId, choice.transport, choice.validation, choice.policy);
  if (choice.eligible) {
    console.log(choice.configurableFields, choice.launchPlan);
  } else {
    console.log(choice.ineligibility);
  }
}

console.log(result.eligibleChoices);
```

准确的方法签名是:

```typescript
enumerateInstallChoices(
  config?: ConfigValues,
  options?: EnumerateInstallChoicesOptions,
): InstallChoicesResult
```

选择ID对描述者具有决定性意义: `package:<index>` 财务报告和审定财务报表 `remote:<index>`通过提供远程 URL 模板值 `ConfigValues.urlVariables`。配置错误不会在结构上隐藏 因此,呼叫者可以在保留 惰性发射计划. 无效、不支持和拒绝政策的广告 保留在 `advertisedChoices` 有打字解释.

## 许可证

麻省理工学院

## 常见问题

### @github/mcp-registry 是什么？

用于MCP Register API的TypeScript SDK——包括类型,即用即用客户端,以及用于企业许可列表执行的确定指纹计算\.

### 如何安装 @github/mcp-registry？

在项目目录运行 npm install @github/mcp-registry，或使用 pnpm add / yarn add / bun add。

### @github/mcp-registry 支持 TypeScript 吗？

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

### @github/mcp-registry 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @github/mcp-registry 需要什么版本的 Node\.js？

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

### @github/mcp-registry 可以商用吗？

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

### @github/mcp-registry 的下载量有多少？

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

### @github/mcp-registry 还在维护吗？

最新版本 0\.1\.7 发布于 2026/09/07（2 个月前）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/04/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

