Smithery Registry API

下文将 Smithery Registry API 的英文文档完整翻译为中文，并保持原有的小节层次、代码示例及格式，以方便中文读者快速上手。
（代码示例中的 URL、字段名、示例值与语言标识均保持不变）

---

概述

Smithery Registry API 为开发者提供一套通过编程方式检索 MCP 服务器（Model Context Protocol Server）的接口。使用本 API，您可以：

• 搜索并分页浏览可用服务器
• 查看每台服务器的详细信息、连接方式及工具列表
• 依据连接信息，按照 Connect to MCPs 指南与服务器建立连接

---

核心概念

Smithery Registry 存储 MCP 服务器索引。每台服务器在注册时都会声明一份 配置模式（configuration schema） —— 这是一个 JSON Schema，用于描述连接该服务器时所需的配置结构体。

---

认证

所有端点均需通过 Bearer Token 进行身份验证。
前往 Smithery 控制台创建 API Key 后，在每个 HTTP 请求头中添加：

headers: {
  'Authorization': 'Bearer smithery-api-token'
}

---

列出服务器

GET https://registry.smithery.ai/servers

检索分页后的服务器列表。

查询参数	是否必填	说明
q	可选	搜索关键字，支持语义搜索，可直接当作提示语输入
page	可选	页码（默认 1）
pageSize	可选	每页条数（默认 10）

过滤规则

• 文本搜索：直接输入任意文本（例：machine learning）
• 所有者过滤：owner:用户名（例：owner:smithery-ai）
• 仓库过滤：repo:仓库名（例：repo:fetch）
• 部署状态：is:deployed → 仅展示已部署服务器
• 验证状态：is:verified → 仅展示已验证服务器

过滤器可组合使用，例如：

owner:mem0ai is:verified memory

示例（JavaScript fetch）

const apiKey = 'your-smithery-api-token';
const query = 'owner:mem0ai is:verified memory';
const encodedQuery = encodeURIComponent(query);

const response = await fetch(
  `https://registry.smithery.ai/servers?q=${encodedQuery}&page=1&pageSize=10`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);

响应格式

{
  servers: Array<{
    qualifiedName: string;
    displayName: string;
    description: string;
    homepage: string;     // 指向 Smithery 服务器页面
    useCount: string;     // 被工具调用次数
    isDeployed: boolean;  // 是否已部署为 HTTP 服务
    createdAt: string;
  }>;
  pagination: {
    currentPage: number;
    pageSize: number;
    totalPages: number;
    totalCount: number;
  };
}

---

获取单台服务器详情

GET https://registry.smithery.ai/servers/{qualifiedName}

通过 qualified name（唯一的人类可读标识，见页面 URL）获取服务器详细信息。

示例（JavaScript fetch）

const apiKey = 'your-smithery-api-token';
const qualifiedName = 'exa';

const response = await fetch(
  `https://registry.smithery.ai/servers/${qualifiedName}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Accept': 'application/json'
    }
  }
);

const data = await response.json();
console.log(data);

响应格式

{
  qualifiedName: string;
  displayName: string;
  iconUrl: string | null;
  deploymentUrl: string;
  connections: Array<{
    type: string;          // "http" 或 "stdio"
    url?: string;          // HTTP 连接地址（type 为 http 时存在）
    configSchema: JSONSchema;
  }>;
  security: {
    scanPassed: boolean;
  } | null;
  tools: Array<{
    name: string;
    description: string | null;
    inputSchema: {
      type: "object";
      properties?: object;
    };
  }> | null;
}

---

字段说明

字段	类型	说明
name / qualifiedName	string	MCP 服务器的限定名称，格式 owner/repository
displayName	string	服务器的可读名称
iconUrl	`string	null`	服务器图标 URL，无则为 null
connections	array	连接方式列表
• type	string	连接类型：http / stdio
• url	string	HTTP 连接地址（type="http" 时提供）
• configSchema	object	连接所需配置的 JSON Schema
security	`object	null`	服务器安全扫描结果
• scanPassed	`boolean	null`	是否通过 Invariant 安全扫描
tools	`array	null`	服务器暴露的工具列表（缓存自最近一次部署）
• name	string	工具名称
• description	`string	null`	工具描述
• inputSchema	object	工具入参的 JSON Schema

安全说明
Smithery 使用 Invariant 扫描服务器，检测工具投毒、项目抽逃、跨域升级与提示注入等风险。

---

下一步

完成服务器信息检索后，请参考 “Connect to MCPs” 指南，结合 connections 字段中提供的连接方式与配置模式，即可与目标 MCP 服务器建立连接并开始使用其工具。