Gemini CLI 확장 시작하기

이 가이드는 첫 번째 Gemini CLI 확장을 만드는 과정을 안내합니다. 새 확장을 설정하고, MCP 서버를 통해 사용자 지정 도구를 추가하고, 사용자 지정 명령을 만들고, GEMINI.md 파일을 통해 모델에 컨텍스트를 제공하는 방법을 배우게 됩니다.

사전 준비 사항

시작하기 전에 Gemini CLI가 설치되어 있고 Node.js에 대한 기본적인 이해가 있는지 확인하세요.

무엇을 언제 사용해야 할까요?

확장은 Gemini CLI를 사용자 지정하는 다양한 방법을 제공합니다.

1단계: 새 확장 만들기

가장 쉬운 시작 방법은 내장 템플릿 중 하나를 사용하는 것입니다. mcp-server 예제를 기반으로 사용하겠습니다.

다음 명령을 실행하여 템플릿 파일이 포함된 my-first-extension이라는 새 디렉터리를 만듭니다:

gemini extensions new my-first-extension mcp-server

이렇게 하면 다음과 같은 구조의 새 디렉터리가 생성됩니다:

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

2단계: 확장 파일 이해하기

새 확장의 주요 파일을 살펴보겠습니다.

gemini-extension.json

이것은 확장의 매니페스트 파일입니다. Gemini CLI에 확장을 로드하고 사용하는 방법을 알려줍니다.

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

• name: 확장의 고유 이름입니다.
• version: 확장의 버전입니다.
• mcpServers: 이 섹션은 하나 이상의 Model Context Protocol (MCP) 서버를 정의합니다. MCP 서버는 모델이 사용할 새로운 도구를 추가하는 방법입니다.
  • command, args, cwd: 이 필드들은 서버를 시작하는 방법을 지정합니다. ${extensionPath} 변수를 사용하는 것에 주목하세요. Gemini CLI는 이를 확장의 설치 디렉터리에 대한 절대 경로로 대체합니다. 이를 통해 확장이 어디에 설치되든 작동할 수 있습니다.

example.js

이 파일에는 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);

이 서버는 공개 API에서 데이터를 가져오는 fetch_posts라는 단일 도구를 정의합니다.

package.json

이것은 Node.js 프로젝트의 표준 구성 파일입니다. 종속성과 스크립트를 정의합니다.

3단계: 확장 연결하기

확장을 사용하기 전에 로컬 개발을 위해 Gemini CLI 설치에 연결해야 합니다.

1. 종속성 설치:

   cd my-first-extension
   npm install

2. 확장 연결:

   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 쉘 명령을 실행하고 결과를 요약을 위한 프롬프트로 파이프합니다.

파일을 저장한 후 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을 업데이트하세요:

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

CLI를 다시 시작하세요. 이제 모델은 확장이 활성화된 모든 세션에서 GEMINI.md 파일의 컨텍스트를 갖게 됩니다.

(선택 사항) 6단계: 에이전트 기술(Skill) 추가하기

에이전트 기술을 사용하면 전문 지식과 절차적 워크플로를 묶을 수 있습니다. 지속적인 컨텍스트를 제공하는 GEMINI.md와 달리 기술은 필요할 때만 활성화되어 컨텍스트 토큰을 절약합니다.

1. skills 디렉터리와 기술을 위한 하위 디렉터리를 만듭니다:

   mkdir -p skills/security-audit

2. skills/security-audit/SKILL.md 파일을 만듭니다:

   ---
   name: security-audit
   description:
     Expertise in auditing code for security vulnerabilities. Use when the user
     asks to "check for security issues" or "audit" their changes.
   ---
    
   # Security Auditor
    
   You are an expert security researcher. When auditing code:
    
   1. Look for common vulnerabilities (OWASP Top 10).
   2. Check for hardcoded secrets or API keys.
   3. Suggest remediation steps for any findings.

확장에 포함된 기술은 자동으로 발견되며 세션 중에 모델이 관련 작업을 식별할 때 활성화할 수 있습니다.

7단계: 확장 배포하기

확장이 마음에 들면 다른 사람들과 공유할 수 있습니다. 확장을 배포하는 두 가지 주요 방법은 Git 저장소를 통하거나 GitHub Releases를 통하는 것입니다. 공개 Git 저장소를 사용하는 것이 가장 간단한 방법입니다.

두 가지 방법에 대한 자세한 지침은 확장 배포 가이드를 참조하세요.

결론

Gemini CLI 확장을 성공적으로 만들었습니다! 다음을 배웠습니다:

• 템플릿에서 새 확장 부트스트랩하기.
• MCP 서버로 사용자 지정 도구 추가하기.
• 편리한 사용자 지정 명령 만들기.
• 모델에 지속적인 컨텍스트 제공하기.
• 전문 에이전트 기술 번들링하기.
• 로컬 개발을 위해 확장 연결하기.

여기서 더 고급 기능을 탐색하고 Gemini CLI에 강력한 새 기능을 구축할 수 있습니다.