Vertex AI MCP Server

Vertex AI MCP 서버

이 프로젝트는 Google Cloud의 Vertex AI Gemini 모델과 상호 작용하기 위한 포괄적인 도구 모음을 제공하는 MCP(Model Context Protocol) 서버를 구현하며, 코딩 지원과 일반적인 쿼리 답변에 중점을 둡니다.

특징

• 다양한 MCP 도구를 통해 Vertex AI Gemini 모델에 대한 액세스를 제공합니다.
• 웹 검색 기반( answer_query_websearch )과 직접 지식 답변( answer_query_direct )을 지원합니다.
• 환경 변수를 통해 구성 가능한 모델 ID, 온도, 스트리밍 동작, 최대 출력 토큰 및 재시도 설정.
• 기본적으로 스트리밍 API를 사용하여 응답성을 높일 수 있습니다.
• 일시적인 API 오류에 대한 기본 재시도 논리가 포함되어 있습니다.
• 잠재적인 차단을 줄이기 위해 최소한의 안전 필터( BLOCK_NONE )가 적용되었습니다(신중하게 사용하세요).

제공된 도구

쿼리 및 생성(AI 중심)

• answer_query_websearch : Google 검색 결과로 강화된 구성된 Vertex AI 모델을 사용하여 자연어 쿼리에 답변합니다.
• answer_query_direct : 구성된 Vertex AI 모델의 내부 지식만을 사용하여 자연어 쿼리에 답변합니다.
• explain_topic_with_docs : 웹 검색을 통해 찾은 공식 문서의 정보를 종합하여 특정 소프트웨어 주제에 대한 질의에 대한 자세한 설명을 제공합니다.
• get_doc_snippets : 공식 문서를 검색하여 정확하고 권위 있는 코드 조각이나 기술적 질문에 대한 간결한 답변을 제공합니다.
• generate_project_guidelines : 웹 검색을 통해 모범 사례를 찾아 지정된 기술 목록(선택적으로 버전 포함)을 기반으로 구조화된 프로젝트 가이드라인 문서(마크다운)를 생성합니다.

파일 시스템 작업

• read_file_content : 단일 파일의 전체 내용을 읽습니다.
• read_multiple_files_content : 여러 파일의 내용을 동시에 읽습니다.
• write_file_content : 새 파일을 만들거나 기존 파일을 새 내용으로 완전히 덮어씁니다.
• edit_file_content : 텍스트 파일에 줄 기반 편집을 수행하여 차이점 미리 보기를 반환하거나 변경 사항을 적용합니다.
• create_directory : 새로운 디렉토리(중첩된 디렉토리 포함)를 생성합니다.
• list_directory_contents : 지정된 경로 내에 있는 파일과 디렉토리를 직접 나열합니다(비재귀적).
• get_directory_tree : 파일과 디렉토리의 재귀적 트리 뷰를 JSON으로 가져옵니다.
• move_file_or_directory : 파일과 디렉토리를 이동하거나 이름을 바꿉니다.
• search_filesystem : 선택적으로 제외 항목을 포함하여 이름 패턴과 일치하는 파일/디렉토리를 재귀적으로 검색합니다.
• get_filesystem_info : 파일이나 디렉토리에 대한 자세한 메타데이터(크기, 날짜, 유형, 권한)를 검색합니다.

AI + 파일 시스템 작업 결합

• save_generate_project_guidelines : 기술 스택을 기반으로 프로젝트 가이드라인을 생성하고 결과를 지정된 파일 경로에 저장합니다.
• save_doc_snippet : 문서에서 코드 조각을 찾아 지정된 파일 경로에 결과를 저장합니다.
• save_topic_explanation : 문서를 기반으로 주제에 대한 자세한 설명을 생성하고 결과를 지정된 파일 경로에 저장합니다.
• save_answer_query_direct : 내부 지식만을 사용하여 쿼리에 답변하고 지정된 파일 경로에 답변을 저장합니다.
• save_answer_query_websearch : 웹 검색 결과를 사용하여 쿼리에 답변하고 지정된 파일 경로에 답변을 저장합니다.

(참고: 각 도구의 입출력 스키마는 src/tools/ 내의 해당 파일에 정의되어 있으며 MCP 서버를 통해 공개됩니다.)

필수 조건

• Node.js(v18+)
• Bun ( npm install -g bun )
• 결제가 활성화된 Google Cloud 프로젝트입니다.
• GCP 프로젝트에서 Vertex AI API가 활성화되었습니다.
• 사용자 환경에 구성된 Google Cloud 인증( gcloud auth application-default login 통한 애플리케이션 기본 자격 증명 또는 서비스 계정 키가 권장됨).

설정 및 설치

1. 프로젝트 복제/배치: 프로젝트 파일이 원하는 위치에 있는지 확인하세요.
2. 종속성 설치:지엑스피1
3. 환경 구성:
   • 프로젝트 루트에 .env 파일을 만듭니다(복사 .env.example ).
   • .env.example 에 설명된 대로 필수 및 선택 환경 변수를 설정합니다.
     • AI_PROVIDER``"vertex" 또는 "gemini" 로 설정합니다.
     • AI_PROVIDER="vertex" 인 경우 GOOGLE_CLOUD_PROJECT 가 필요합니다.
     • AI_PROVIDER="gemini" 이면 GEMINI_API_KEY 가 필요합니다.
4. 서버 구축:
   bun run build
   이렇게 하면 TypeScript 코드가 build/index.js 로 컴파일됩니다.

사용법(독립형/NPX)

npm에 게시한 후 npx 사용하여 이 서버를 직접 실행할 수 있습니다.

또는 전역적으로 설치하세요.

참고: 독립 실행형으로 실행하려면 명령을 실행하기 전에 셸 환경에서 필요한 환경 변수(예: GOOGLE_CLOUD_PROJECT , GOOGLE_CLOUD_LOCATION , ADC를 사용하지 않는 경우 인증 자격 증명)를 설정해야 합니다.

Smithery를 통해 설치

Smithery 를 통해 Claude Desktop에 Vertex AI Server를 자동으로 설치하는 방법:

클라인과 함께 달리기

1. MCP 설정 구성: Cline MCP 설정 파일(예: .roo/mcp.json )에 구성을 추가/업데이트합니다. 명령을 구성하는 주요 방법은 두 가지입니다.옵션 A: 노드 사용(직접 경로 - 개발에 권장)이 방법은 node 사용하여 컴파일된 스크립트를 직접 실행합니다. 개발 중에 코드를 로컬에 복제할 때 유용합니다.
   { "mcpServers": { "vertex-ai-mcp-server": { "command": "node", "args": [ "/full/path/to/your/vertex-ai-mcp-server/build/index.js" // Use absolute path or ensure it's relative to where Cline runs node ], "env": { // --- General AI Configuration --- "AI_PROVIDER": "vertex", // "vertex" or "gemini" // --- Required (Conditional) --- "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex" // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini" // --- Optional Model Selection --- "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override) "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini" // --- Optional AI Parameters --- "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI "AI_TEMPERATURE": "0.0", "AI_USE_STREAMING": "true", "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example "AI_MAX_RETRIES": "3", "AI_RETRY_DELAY_MS": "1000", // --- Optional Vertex Authentication --- // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex }, "disabled": false, "alwaysAllow": [ // Add tool names here if you don't want confirmation prompts // e.g., "answer_query_websearch" ], "timeout": 3600 // Optional: Timeout in seconds } // Add other servers here... } }
   • 중요: args 경로가 build/index.js 파일을 올바르게 가리키는지 확인하세요. 절대 경로를 사용하는 것이 더 안전할 수 있습니다.

   옵션 B: NPX 사용(npm에 게시된 패키지 필요)

   이 방법은 npx 사용하여 npm 레지스트리에서 서버 패키지를 자동으로 다운로드하고 실행합니다. 저장소를 복제하지 않으려는 경우 편리합니다.

   { "mcpServers": { "vertex-ai-mcp-server": { "command": "bunx", // Use bunx "args": [ "-y", // Auto-confirm installation "vertex-ai-mcp-server" // The npm package name ], "env": { // --- General AI Configuration --- "AI_PROVIDER": "vertex", // "vertex" or "gemini" // --- Required (Conditional) --- "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex" // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini" // --- Optional Model Selection --- "VERTEX_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="vertex" (Example override) "GEMINI_MODEL_ID": "gemini-2.5-pro-exp-03-25", // If AI_PROVIDER="gemini" // --- Optional AI Parameters --- "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI "AI_TEMPERATURE": "0.0", "AI_USE_STREAMING": "true", "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example "AI_MAX_RETRIES": "3", "AI_RETRY_DELAY_MS": "1000", // --- Optional Vertex Authentication --- // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex }, "disabled": false, "alwaysAllow": [ // Add tool names here if you don't want confirmation prompts // e.g., "answer_query_websearch" ], "timeout": 3600 // Optional: Timeout in seconds } // Add other servers here... } }
   • env 블록의 환경 변수가 .env 와 일치하거나 여기에 명시적으로 정의되어 올바르게 설정되었는지 확인하세요. 실제 JSON 파일에서 주석을 제거하세요.
2. Cline 재시작/다시 로드: Cline은 구성 변경을 감지하고 서버를 시작해야 합니다.
3. 도구 사용: 이제 Cline을 통해 광범위한 도구 목록을 사용할 수 있습니다.

개발

• 시계 모드: bun run watch
• 린팅: bun run lint
• 포맷: bun run format

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.