Vibe Coder MCP

Vibe Coder MCP 서버

Vibe Coder는 Cursor, Cline AI, Claude Desktop과 같은 AI 비서에 강력한 소프트웨어 개발 도구를 제공하도록 설계된 MCP(모델 컨텍스트 프로토콜) 서버입니다. 조사, 계획, 요구사항 생성, 초기 프로젝트 생성 등 다양한 작업에 도움을 줍니다!

개요 및 기능

Vibe Coder MCP는 MCP 호환 클라이언트와 통합되어 다음과 같은 기능을 제공합니다.

• 의미론적 요청 라우팅 : 순차적 사고 폴백과 함께 임베딩 기반 의미론적 매칭을 사용하여 요청을 지능적으로 라우팅합니다.
• 도구 등록 아키텍처 : 도구를 자동으로 등록하여 중앙에서 도구를 관리합니다.
• 직접 LLM 호출 : 생성기 도구는 이제 향상된 안정성과 체계적인 출력 제어를 위해 직접 LLM 호출을 사용합니다.
• 워크플로 실행 : workflows.json 에 정의된 도구 호출의 사전 정의된 시퀀스를 실행합니다.
• 코드 생성 : 코드 스텁과 보일러플레이트를 생성합니다( generate-code-stub ).
• 코드 리팩토링 : 기존 코드 조각을 개선하고 수정합니다( refactor-code ).
• 종속성 분석 : 매니페스트 파일( analyze-dependencies )에서 종속성을 나열합니다.
• Git 통합 : 현재 Git 변경 사항을 요약합니다( git-summary ).
• 연구 및 계획 : 심층 연구를 수행하고( research-manager ) PRD( generate-prd ), 사용자 스토리( generate-user-stories ), 작업 목록( generate-task-list ), 개발 규칙( generate-rules )과 같은 계획 문서를 생성합니다.
• 프로젝트 스캐폴딩 : 풀스택 스타터 키트를 생성합니다( generate-fullstack-starter-kit ).
• 비동기 실행 : 오랫동안 사용되어 온 많은 도구(생성기, 연구, 워크플로)가 이제 비동기 방식으로 실행됩니다. 이러한 도구는 작업 ID를 즉시 반환하며, 최종 결과는 get-job-result 도구를 사용하여 가져옵니다.
• 세션 상태 관리 : 세션 내(메모리 내)의 모든 요청에 대한 기본 상태를 유지합니다.
• 표준화된 오류 처리 : 모든 도구에서 일관된 오류 패턴이 적용됩니다.

(자세한 내용은 아래의 "자세한 도구 설명서" 및 "기능 세부 정보" 섹션을 참조하세요)

설정 가이드

다음의 간단한 단계를 따라 Vibe Coder MCP 서버를 실행하고 AI 어시스턴트에 연결하세요.

1단계: 전제 조건

1. Node.js 버전 확인:
   • 터미널이나 명령 프롬프트를 엽니다.
   • node -v 실행하세요
   • 출력에 v18.0.0 이상이 표시되는지 확인하세요(필수).
   • 설치되지 않았거나 오래된 경우: nodejs.org 에서 다운로드하세요.
2. Git 설치 확인:
   • 터미널이나 명령 프롬프트를 엽니다.
   • git --version 실행하세요
   • 설치되지 않은 경우: git-scm.com 에서 다운로드하세요.
3. OpenRouter API 키 받기:
   • openrouter.ai를 방문하세요
   • 계정이 없으시면 계정을 만드세요.
   • API 키 섹션으로 이동합니다.
   • 새로운 API 키를 생성하여 복사합니다.
   • 4단계를 위해 이 열쇠를 가까이에 두세요.

2단계: 코드 받기

1. 프로젝트 디렉토리 만들기 (선택 사항):
   • 터미널이나 명령 프롬프트를 엽니다.
   • 프로젝트를 저장할 위치로 이동합니다.지엑스피1
2. 저장소 복제:
   • 달리다:
     git clone https://github.com/freshtechbro/vibe-coder-mcp.git
     (또는 해당되는 경우 포크의 URL을 사용하세요)
3. 프로젝트 디렉토리로 이동:
   • 달리다:
     cd vibe-coder-mcp

3단계: 설치 스크립트 실행

운영 체제에 맞는 스크립트를 선택하세요.

Windows의 경우:

1. 터미널(여전히 vibe-coder-mcp 디렉토리에 있음)에서 다음을 실행하세요.
   setup.bat
2. 스크립트가 완료될 때까지 기다리세요(종속성을 설치하고, 프로젝트를 빌드하고, 필요한 디렉토리를 생성합니다).
3. 오류 메시지가 표시되면 아래의 문제 해결 섹션을 참조하세요.

macOS 또는 Linux의 경우:

1. 스크립트를 실행 가능하게 만드세요:
   chmod +x setup.sh
2. 스크립트를 실행합니다:
   ./setup.sh
3. 스크립트가 완료될 때까지 기다리세요.
4. 오류 메시지가 표시되면 아래의 문제 해결 섹션을 참조하세요.

스크립트는 다음 작업을 수행합니다.

• Node.js 버전 확인(v18+)
• npm을 통해 모든 종속성을 설치합니다.
• 스크립트에 정의된 대로 필요한 VibeCoderOutput/ 하위 디렉토리를 생성합니다.
• TypeScript 프로젝트를 빌드합니다.
• .env 파일이 없으면 .env.example 파일을 .env 로 복사합니다. 이 파일을 편집해야 합니다.
• 실행 권한을 설정합니다(Unix 시스템에서).

4단계: 환경 변수( .env ) 구성

3단계의 설치 스크립트는 .env 아직 없는 경우에만 .env.example 템플릿을 복사하여 프로젝트의 루트 디렉토리에 .env 파일을 자동으로 생성합니다.

1. .env 찾아 엽니다. vibe-coder-mcp 디렉토리에서 .env 파일을 찾아 텍스트 편집기로 엽니다.
2. OpenRouter API 키를 추가하세요(필수):
   • 이 파일에는 .env.example 을 기반으로 한 템플릿이 포함되어 있습니다.
     # OpenRouter Configuration ## Specifies your unique API key for accessing OpenRouter services. ## Replace "Your OPENROUTER_API_KEY here" with your actual key obtained from OpenRouter.ai. OPENROUTER_API_KEY="Your OPENROUTER_API_KEY here" ## Defines the base URL for the OpenRouter API endpoints. ## The default value is usually correct and should not need changing unless instructed otherwise. OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 ## Sets the specific Gemini model to be used via OpenRouter for certain AI tasks. ## ':free' indicates potential usage of a free tier model if available and supported by your key. GEMINI_MODEL=google/gemini-2.0-flash-thinking-exp:free
   • 중요한 것은 "Your OPENROUTER_API_KEY here" 실제 OpenRouter API 키로 바꾸는 것입니다. 키에 따옴표가 필요하지 않으면 제거하세요.
3. 출력 디렉토리 구성(선택 사항):
   • 생성된 파일이 저장되는 위치를 변경하려면(기본값은 프로젝트 내부의 VibeCoderOutput/ 입니다) .env 파일에 다음 줄을 추가하세요.
     VIBE_CODER_OUTPUT_DIR=/path/to/your/desired/output/directory
   • 경로를 원하는 절대 경로 로 바꾸세요. 경로에는 슬래시( / )를 사용하세요. 이 변수가 설정되지 않으면 기본 디렉터리( VibeCoderOutput/ )가 사용됩니다.
4. 다른 설정 검토(선택 사항):
   • LOG_LEVEL (예: LOG_LEVEL=debug ) 또는 NODE_ENV (예: NODE_ENV=development )와 같이 서버에서 지원하는 다른 환경 변수를 추가할 수 있습니다.
5. .env 파일을 저장합니다.

5단계: AI Assistant와 통합(MCP 설정)

이 중요한 단계에서는 클라이언트의 MCP 설정 파일에 구성을 추가하여 Vibe Coder를 AI 어시스턴트에 연결합니다.

5.1: 클라이언트의 MCP 설정 파일 찾기

위치는 AI 비서에 따라 다릅니다.

• 커서 AI / Windsurf / RooCode(VS Code 기반):
  1. 애플리케이션을 엽니다.
  2. 명령 팔레트를 엽니다( Ctrl+Shift+P 또는 Cmd+Shift+P ).
  3. Preferences: Open User Settings (JSON) 입력하고 선택합니다.
  4. 이렇게 하면 mcpServers 개체가 있어야 하는 settings.json 파일이 열립니다.
• Cline AI(VS 코드 확장):
  • Windows : %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • macOS : ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • 리눅스 : ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • (참고: Cursor 대신 표준 VS Code를 사용하는 경우 경로에서 Cursor``Code 로 바꾸세요)
• 클로드 데스크탑:
  • 윈도우 : %APPDATA%\Claude\claude_desktop_config.json
  • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
  • 리눅스 : ~/.config/Claude/claude_desktop_config.json

5.2: Vibe Coder 구성 추가

1. 위에 명시된 설정 파일을 텍스트 편집기에서 엽니다.
2. "mcpServers": { ... } JSON 객체를 찾으세요. 존재하지 않는 경우 새로 생성해야 할 수 있습니다(파일 전체가 유효한 JSON으로 유지되도록 해야 합니다). 예를 들어, 빈 파일은 {"mcpServers": {}} 가 될 수 있습니다.
3. mcpServers 객체의 중괄호 {}안에 다음 구성 블록을 추가합니다. 다른 서버가 이미 나열되어 있는 경우, 이 블록을 붙여넣기 전에 이전 서버의 닫는 중괄호 } 뒤에 쉼표 , 를 추가합니다.
   ## This is the unique identifier for this MCP server instance within your client's settings. You can name it descriptively. "vibe-coder-mcp": { ## Specifies the command used to execute the server. Should be 'node' if Node.js is in your system's PATH. "command": "node", ## Provides the arguments to the 'command'. The primary argument is the absolute path to the compiled server entry point (`build/index.js`). ## !! IMPORTANT: Replace the placeholder path below with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows. !! "args": ["/path/to/your/vibe-coder-mcp/build/index.js"], ## Sets the current working directory for the server process when it runs. Should be the absolute path to the root of the vibe-coder-mcp project directory. ## !! IMPORTANT: Replace the placeholder path below with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows. !! "cwd": "/path/to/your/vibe-coder-mcp", ## Defines the communication transport protocol between the client and server. 'stdio' (standard input/output) is typical for local servers. "transport": "stdio", ## An object containing environment variables to be passed specifically to the Vibe Coder server process when it starts. ## API Keys should be in the .env file, NOT here. "env": { ## Absolute path to the LLM configuration file used by Vibe Coder. This file defines model preferences. ## !! IMPORTANT: Replace the placeholder path below with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows. !! "LLM_CONFIG_PATH": "/path/to/your/vibe-coder-mcp/llm_config.json", ## Sets the logging level for the server. Options typically include 'debug', 'info', 'warn', 'error'. 'debug' provides the most detailed logs. "LOG_LEVEL": "debug", ## Specifies the runtime environment. 'production' is recommended for stable use, 'development' may enable more verbose logging or different behaviors. "NODE_ENV": "production", ## Absolute path to the directory where Vibe Coder tools will save their output files (e.g., generated documents, code). Ensure this directory exists or the server has permission to create it. ## This can also be set in the .env file (which takes precedence if both are set). ## !! IMPORTANT: Replace the placeholder path below with the actual absolute path on YOUR system. Use forward slashes (/) even on Windows. !! "VIBE_CODER_OUTPUT_DIR": "/path/to/your/VibeCoderOutput" }, ## A boolean flag to enable (false) or disable (true) this server configuration without deleting it. Set to 'false' to use the server. "disabled": false, ## A list of tool names provided by this server that the MCP client is allowed to execute automatically without requiring explicit user approval for each use. Add or remove tool names based on your trust and workflow preferences. "autoApprove": [ "research", "generate-rules", "generate-prd", "generate-user-stories", "generate-task-list", "generate-fullstack-starter-kit", "generate-code-stub", "refactor-code", "analyze-dependencies", "git-summary", // Note: Corrected from 'git-summary' if the tool name is indeed 'git-summary' "run-workflow" ] }
4. 중요: 모든 플레이스홀더 경로 (예: /path/to/your/vibe-coder-mcp/... )를 저장소를 복제한 시스템의 올바른 절대 경로 로 바꾸세요. 경로에는 슬래시 / 를 사용하세요(Windows에서도 마찬가지입니다(예: C:/Users/YourName/Projects/vibe-coder-mcp/build/index.js ). 잘못된 경로는 서버 연결 실패의 가장 흔한 원인입니다.
5. 설정 파일을 저장합니다.
6. 변경 사항을 적용하려면 AI 어시스턴트 애플리케이션(Cursor, VS Code, Claude Desktop 등)을 완전히 닫았다가 다시 시작하세요 .

6단계: 구성 테스트

1. AI 도우미 시작하기:
   • AI 어시스턴트 애플리케이션을 완전히 다시 시작하세요.
2. 간단한 명령 테스트:
   • 다음과 같은 테스트 명령을 입력하세요: Research modern JavaScript frameworks
3. 적절한 대응을 확인하세요:
   • 정상적으로 작동하면 조사에 대한 응답을 받게 됩니다.
   • 그렇지 않은 경우 아래의 문제 해결 섹션을 확인하세요.

프로젝트 아키텍처

Vibe Coder MCP 서버는 도구 레지스트리 패턴을 중심으로 한 모듈식 아키텍처를 따릅니다.

디렉토리 구조

의미론적 라우팅 시스템

Vibe Coder는 정교한 라우팅 방식을 사용하여 각 요청에 맞는 적절한 도구를 선택합니다.

도구 레지스트리 패턴

도구 레지스트리는 도구 정의와 실행을 관리하는 핵심 구성 요소입니다.

순차적 사고 과정

순차적 사고 메커니즘은 LLM 기반 폴백 라우팅을 제공합니다.

세션 상태 관리

워크플로 실행 엔진

Workflow 시스템은 여러 단계의 시퀀스를 가능하게 합니다.

워크플로 구성

워크플로는 프로젝트 루트 디렉터리에 있는 workflows.json 파일에 정의되어 있습니다. 이 파일에는 단일 명령으로 실행할 수 있는 미리 정의된 도구 호출 시퀀스가 포함되어 있습니다.

파일 위치 및 구조

• workflows.json 파일은 프로젝트 루트 디렉토리(package.json과 같은 수준)에 있어야 합니다.
• 이 파일은 다음 구조를 따릅니다.
  { "workflows": { "workflowName1": { "description": "Description of what this workflow does", "inputSchema": { "param1": "string", "param2": "string" }, "steps": [ { "id": "step1_id", "toolName": "tool-name", "params": { "param1": "{workflow.input.param1}" } }, { "id": "step2_id", "toolName": "another-tool", "params": { "paramA": "{workflow.input.param2}", "paramB": "{steps.step1_id.output.content[0].text}" } } ], "output": { "summary": "Workflow completed message", "details": ["Output line 1", "Output line 2"] } } } }

매개변수 템플릿

워크플로 단계 매개변수는 다음을 참조할 수 있는 템플릿 문자열을 지원합니다.

• 워크플로 입력: {workflow.input.paramName}
• 이전 단계 출력: {steps.stepId.output.content[0].text}

워크플로 트리거

다음과 함께 run-workflow 도구를 사용하세요.

자세한 도구 설명서

src/tools/ 디렉터리의 각 도구는 자체 README.md 파일에 포괄적인 설명서를 포함하고 있습니다. 이 파일에는 다음 내용이 포함되어 있습니다.

• 도구 개요 및 목적
• 입력/출력 사양
• 워크플로 다이어그램(Mermaid)
• 사용 예
• 사용된 시스템 프롬프트
• 오류 처리 세부 정보

자세한 내용은 다음 개별 README를 참조하세요.

• src/tools/code-refactor-generator/README.md
• src/tools/code-stub-generator/README.md
• src/tools/dependency-analyzer/README.md
• src/tools/fullstack-starter-kit-generator/README.md
• src/tools/git-summary-generator/README.md
• src/tools/prd-generator/README.md
• src/tools/research-manager/README.md
• src/tools/rules-generator/README.md
• src/tools/task-list-generator/README.md
• src/tools/user-stories-generator/README.md
• src/tools/workflow-runner/README.md

도구 카테고리

코드 생성 및 리팩토링 도구

• 코드 스텁 생성기( generate-code-stub ) : 설명과 대상 언어를 기반으로 보일러플레이트 코드(함수, 클래스 등)를 생성합니다. 새 컴포넌트를 빠르게 스캐폴딩하는 데 유용합니다.
• 코드 리팩터링 생성기( refactor-code ) : 기존 코드 조각과 리팩터링 지침(예: "async/await로 변환", "가독성 향상", "오류 처리 추가")을 가져와 수정된 코드를 반환합니다.

분석 및 정보 도구

• 종속성 분석기( analyze-dependencies ) : package.json 이나 requirements.txt 와 같은 매니페스트 파일을 구문 분석하여 프로젝트 종속성을 나열합니다.
• Git 요약 생성기( git-summary ) : 현재 Git 상태 요약을 제공하며, 스테이징된 변경 사항과 스테이징되지 않은 변경 사항(diff)을 보여줍니다. 커밋하기 전에 빠르게 확인하는 데 유용합니다.
• 연구 관리자( research-manager ) : Perplexity Sonar를 사용하여 기술 주제에 대한 심층 연구를 수행하고 요약과 출처를 제공합니다.

계획 및 문서화 도구

• 규칙 생성기( generate-rules ): 프로젝트별 개발 규칙과 가이드라인을 생성합니다.
• PRD 생성기( generate-prd ): 포괄적인 제품 요구 사항 문서를 생성합니다.
• 사용자 스토리 생성기( generate-user-stories ): 수용 기준이 포함된 자세한 사용자 스토리를 생성합니다.
• 작업 목록 생성기( generate-task-list ): 종속성을 포함한 구조화된 개발 작업 목록을 작성합니다.

프로젝트 스캐폴딩 도구

• Fullstack Starter Kit Generator( generate-fullstack-starter-kit ): 기본 설정 스크립트 및 구성을 포함하여 지정된 프런트엔드/백엔드 기술을 사용하여 맞춤형 프로젝트 스타터 키트를 생성합니다.

워크플로 및 오케스트레이션

• 워크플로우 러너( run-workflow ): 일반적인 개발 작업을 위해 미리 정의된 도구 호출 시퀀스를 실행합니다.

생성된 파일 저장소

기본적으로 생성기 도구의 출력은 프로젝트 내의 VibeCoderOutput/ 디렉터리에 기록 참조용으로 저장됩니다. 이 위치는 .env 파일 또는 AI Assistant 구성에서 VIBE_CODER_OUTPUT_DIR 환경 변수를 설정하여 재정의할 수 있습니다.

구조 예시(기본 위치):

사용 예

연결된 AI 도우미를 통해 도구와 상호 작용하세요.

• 연구: Research modern JavaScript frameworks
• 규칙 생성: Create development rules for a mobile banking application
• PRD 생성: Generate a PRD for a task management application
• 사용자 스토리 생성: Generate user stories for an e-commerce website
• 작업 목록 생성: Create a task list for a weather app based on [user stories]
• 순차적 사고: Think through the architecture for a microservices-based e-commerce platform
• Fullstack Starter Kit: Create a starter kit for a React/Node.js blog application with user authentication
• 코드 스텁 생성: Generate a python function stub named 'calculate_discount' that takes price and percentage
• 코드 리팩터링: Refactor this code to use async/await: [paste code snippet]
• 종속성 분석: Analyze dependencies in package.json
• Git 요약: Show unstaged git changes
• 워크플로 실행: Run workflow newProjectSetup with input { "projectName": "my-new-app", "description": "A simple task manager" }

로컬에서 실행(선택 사항)

주된 용도는 AI 어시스턴트(stdio 사용)와의 통합이지만, 테스트를 위해 서버를 직접 실행할 수도 있습니다.

실행 모드

• 프로덕션 모드(Stdio):
  npm start
  • 로그가 stderr로 전송됩니다(AI 어시스턴트 실행을 모방함)
  • NODE_ENV=production을 사용하세요
• 개발 모드(Stdio, Pretty Logs):
  npm run dev
  • 로그는 보기 좋은 포맷으로 stdout으로 전송됩니다.
  • nodemon 과 pino-pretty 필요합니다
  • NODE_ENV=development를 사용하세요
• SSE 모드(HTTP 인터페이스):
  # Production mode over HTTP npm run start:sse # Development mode over HTTP npm run dev:sse
  • stdio 대신 HTTP를 사용합니다
  • .env의 PORT를 통해 구성됨(기본값: 3000)
  • http://localhost:3000 에서 접속하세요

자세한 문제 해결

연결 문제

AI Assistant에서 MCP 서버가 감지되지 않음

1. 구성 경로 확인:
   • args 배열의 절대 경로가 올바른지 확인하세요
   • 모든 슬래시가 정방향 슬래시인지 확인하십시오 / Windows에서도 마찬가지입니다.
   • Node에서 찾을 수 있는지 테스트하려면 node <path-to-build/index.js> 직접 실행하세요.
2. 구성 형식 확인:
   • JSON이 구문 오류 없이 유효한지 확인하세요.
   • 속성 사이의 쉼표가 올바른지 확인하세요
   • mcpServers 개체에 서버가 포함되어 있는지 확인하세요.
3. 어시스턴트를 다시 시작합니다.
   • 응용 프로그램을 완전히 닫으세요(단순히 최소화하는 것이 아니라)
   • 다시 열어서 다시 시도하세요

서버는 시작되지만 도구가 작동하지 않습니다

1. 비활성화된 플래그 확인:
   • "disabled": false 설정되어 있는지 확인하세요.
   • JSON이 지원하지 않으므로 // 주석을 제거하세요.
2. autoApprove 배열 확인:
   • autoApprove 배열의 도구 이름이 정확히 일치하는지 확인하세요.
   • 하이브리드 라우팅을 사용하는 경우 배열에 "process-request" 를 추가해 보세요.

API 키 문제

1. OpenRouter 주요 문제:
   • 키가 올바르게 복사되었는지 다시 한번 확인하세요
   • OpenRouter 대시보드에서 키가 활성화되어 있는지 확인하세요.
   • 충분한 크레딧이 있는지 확인하세요
2. 환경 변수 문제:
   • 다음 두 가지 모두에서 키가 올바른지 확인하세요.
     • .env 파일(로컬 실행용)
     • AI 어시스턴트의 구성 환경 블록

경로 및 권한 문제

1. 빌드 디렉토리를 찾을 수 없습니다:
   • npm run build 실행하여 빌드 디렉토리가 있는지 확인하세요.
   • 빌드 출력이 다른 디렉토리로 이동하는지 확인하세요(tsconfig.json 확인)
2. 파일 권한 오류:
   • 사용자에게 workflow-agent-files 디렉토리에 대한 쓰기 액세스 권한이 있는지 확인하세요.
   • Unix 시스템에서 build/index.js에 실행 권한이 있는지 확인하세요.

로그 디버깅

1. 지역 실행의 경우:
   • 오류 메시지에 대한 콘솔 출력을 확인하세요.
   • .env 파일에서 LOG_LEVEL=debug 로 실행해보세요.
2. AI Assistant 실행의 경우:
   • env 구성에서 "NODE_ENV": "production" 설정합니다.
   • 어시스턴트에 로깅 콘솔이나 출력 창이 있는지 확인하세요.

도구별 문제

1. 의미적 라우팅이 작동하지 않음:
   • 첫 번째 실행은 내장 모델을 다운로드할 수 있습니다. 다운로드 메시지를 확인하세요.
   • 도구 이름을 언급하는 보다 명확한 요청을 시도하세요.
2. **Git 요약 도구