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 에 설명된 대로 필수 및 선택 환경 변수를 설정합니다. GOOGLE_CLOUD_PROJECT 설정되어 있는지 확인하세요.
4. 서버 구축:
   bun run build
   이렇게 하면 TypeScript 코드가 build/index.js 로 컴파일됩니다.

클라인과 함께 달리기

1. MCP 설정 구성: Cline MCP 설정 파일(예: .roo/mcp.json )에 구성을 추가/업데이트합니다.
   { "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": { // Required: Ensure these match your .env or are set here "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", "GOOGLE_CLOUD_LOCATION": "us-central1", // Required if not using ADC: // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json", // Optional overrides: "VERTEX_AI_MODEL_ID": "gemini-2.5-pro-exp-03-25", "VERTEX_AI_TEMPERATURE": "0.0", "VERTEX_AI_USE_STREAMING": "true", "VERTEX_AI_MAX_OUTPUT_TOKENS": "65535", "VERTEX_AI_MAX_RETRIES": "3", "VERTEX_AI_RETRY_DELAY_MS": "1000" }, "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 파일을 올바르게 가리키는지 확인하세요. 절대 경로를 사용하는 것이 더 안전할 수 있습니다.
   • env 블록의 환경 변수가 .env 와 일치하거나 여기에 명시적으로 정의되어 올바르게 설정되었는지 확인하세요. 실제 JSON 파일에서 주석을 제거하세요.
2. Cline 재시작/다시 로드: Cline은 구성 변경을 감지하고 서버를 시작해야 합니다.
3. 도구 사용: 이제 Cline을 통해 광범위한 도구 목록을 사용할 수 있습니다.

개발

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