使用 Gemini CLI 扩展入门

使用 Gemini CLI 扩展入门

本指南将引导您创建第一个 Gemini CLI 扩展。您将学习如何设置新扩展，通过 MCP 服务器添加自定义工具，创建自定义命令，并通过 GEMINI.md 文件向模型提供上下文。

先决条件

在开始之前，请确保您已安装 Gemini CLI 并对 Node.js 和 TypeScript 有基本的了解。

步骤 1：创建新扩展

最简单的方法是使用其中一个内置模板。我们将使用 mcp-server 示例作为我们的基础。

运行以下命令以创建一个名为 my-first-extension 的新目录，其中包含模板文件：

gemini extensions new my-first-extension mcp-server

这将创建一个具有以下结构的新目录：

my-first-extension/
├── example.ts
├── gemini-extension.json
├── package.json
└── tsconfig.json

步骤 2：了解扩展文件

让我们看看您新扩展中的关键文件。

gemini-extension.json

这是您的扩展的清单文件。它告诉 Gemini CLI 如何加载和使用您的扩展。

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}dist${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

• name: 您扩展的唯一名称。
• version: 您扩展的版本。
• mcpServers: 此部分定义了一个或多个模型上下文协议（MCP）服务器。MCP 服务器是您可以为模型添加新工具的方式。
  • command, args, cwd: 这些字段指定如何启动您的服务器。注意使用 ${extensionPath} 变量，Gemini CLI 会将其替换为扩展安装目录的绝对路径。这使得您的扩展可以在任何安装位置正常工作。

example.ts

此文件包含您的 MCP 服务器的源代码。它是一个使用 @modelcontextprotocol/sdk 的简单 Node.js 服务器。

/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

// Registers a new tool named 'fetch_posts'
server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches a list of posts from a public API.',
    inputSchema: z.object({}).shape,
  },
  async () => {
    const apiResponse = await fetch(
      'https://jsonplaceholder.typicode.com/posts',
    );
    const posts = await apiResponse.json();
    const response = { posts: posts.slice(0, 5) };
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response),
        },
      ],
    };
  },
);

// ... (prompt registration omitted for brevity)

const transport = new StdioServerTransport();
await server.connect(transport);

此服务器定义了一个名为 fetch_posts 的单一工具，它从公共 API 获取数据。

package.json 和 tsconfig.json

这些是 TypeScript 项目的标准配置文件。package.json 文件定义了依赖项和一个 build 脚本，而 tsconfig.json 配置了 TypeScript 编译器。

步骤 3：构建并链接你的扩展

在使用扩展之前，你需要编译 TypeScript 代码，并将扩展链接到你的 Gemini CLI 安装以进行本地开发。

1. 安装依赖项：

   cd my-first-extension
   npm install

2. 构建服务器：

   npm run build

   这将编译 example.ts 成 dist/example.js，这是在你的 gemini-extension.json 中引用的文件。

3. 链接扩展：

   link 命令从 Gemini CLI 扩展目录创建一个符号链接到你的开发目录。这意味着你做的任何更改都会立即反映出来，无需重新安装。

   gemini extensions link .

现在，重启你的 Gemini CLI 会话。新的 fetch_posts 工具将可用。你可以通过询问 “fetch posts” 来测试它。

步骤 4：添加自定义命令

自定义命令提供了一种创建复杂提示快捷方式的方法。让我们添加一个在代码中搜索模式的命令。

1. 创建一个 commands 目录和用于你的命令组的子目录：

   mkdir -p commands/fs

2. 创建一个名为 commands/fs/grep-code.toml 的文件：

   prompt = """
   Please summarize the findings for the pattern `{{args}}`.
   
   Search Results:
   !{grep -r {{args}} .}
   """

   这个命令，/fs:grep-code，将接收一个参数，使用它运行 grep Shell 命令，并将结果输出到提示中以便总结。

保存文件后，重启 Gemini CLI。你现在可以运行 /fs:grep-code "some pattern" 来使用你的新命令。

步骤 5：添加一个自定义 GEMINI.md

您可以通过向扩展中添加一个GEMINI.md文件，为模型提供持久上下文。这对于向模型提供如何行为或有关扩展工具的信息非常有用。请注意，对于旨在暴露命令和提示的扩展，您可能并不总是需要此功能。

1. 在扩展目录的根目录下创建一个名为GEMINI.md的文件：

   # My First Extension Instructions
   
   You are an expert developer assistant. When the user asks you to fetch
   posts, use the `fetch_posts` tool. Be concise in your responses.

2. 更新您的gemini-extension.json，告诉CLI加载这个文件：

   {
     "name": "my-first-extension",
     "version": "1.0.0",
     "contextFileName": "GEMINI.md",
     "mcpServers": {
       "nodeServer": {
         "command": "node",
         "args": ["${extensionPath}${/}dist${/}example.js"],
         "cwd": "${extensionPath}"
       }
     }
   }

重新启动CLI。现在，在扩展激活的每个会话中，模型都将拥有来自您的GEMINI.md文件的上下文。

步骤6：发布您的扩展

一旦您对扩展感到满意，可以与其他人分享。发布扩展的两种主要方式是通过Git仓库或通过GitHub发布。使用公共Git仓库是最简单的方法。

有关这两种方法的详细说明，请参考扩展发布指南。

结论

您已成功创建了一个Gemini CLI扩展！您学习了如何：

• 从模板启动新扩展。
• 使用MCP服务器添加自定义工具。
• 创建便捷的自定义命令。
• 为模型提供持久上下文。
• 链接扩展进行本地开发。

从这里开始，您可以探索更高级的功能，并在Gemini CLI中构建强大的新功能。