🤖 클로드 코드 MCP 서버
빠르게 시작하고 싶으신가요? QUICKSTART.md 가이드를 확인해 보세요!
이 프로젝트는 강화된 오케스트레이션 기능, 안정성 개선 및 추가 문서가 포함된 steipete/claude-code-mcp 의 포크입니다.
Claude Code를 원샷 모드로 실행할 수 있는 향상된 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 고급 작업 오케스트레이션 기능, 강력한 오류 처리, 그리고 복잡한 작업을 관리 가능한 하위 작업으로 분할하는 "부메랑 패턴"을 포함합니다.
일반적인 AI 비서가 복잡하고 여러 단계로 구성된 편집이나 작업에 어려움을 겪는 경우가 있다는 것을 알고 계셨나요? 강력한 통합 claude_code 도구와 향상된 안정성 기능을 갖춘 이 서버는 Claude를 코딩 작업에 더욱 직접적이고 유능한 에이전트로 만들어 줍니다.
🔍 개요
이 MCP 서버는 LLM이 Claude Code와 상호 작용하는 데 사용할 수 있는 강력한 도구를 제공합니다. Claude Desktop 또는 다른 MCP 클라이언트와 통합하면 LLM은 다음과 같은 작업을 수행할 수 있습니다.
--dangerously-skip-permissions 사용하여 모든 권한을 우회하여 Claude Code를 실행합니다.- 허가 없이 프롬프트에 따라 Claude 코드를 실행합니다.
- 파일 편집 기능에 직접 액세스
- 강력한 오류 처리 및 재시도를 통해 복잡한 다단계 작업을 실행합니다.
- 부메랑 패턴을 사용하여 전문화된 에이전트 역할을 통해 작업을 조율합니다.
- 시간 초과를 방지하기 위해 하트비트 메커니즘을 통해 안정적인 실행을 유지합니다.
✨ 혜택
- 향상된 안정성: 강력한 오류 처리, 자동 재시도, 정상적인 종료 및 요청 추적
- 작업 오케스트레이션: 복잡한 워크플로를 특수화된 하위 작업으로 세분화할 수 있습니다.
- 작업 자동화: 사람이 읽을 수 있는 마크다운 작업 목록을 실행 가능한 MCP 명령으로 자동 변환
- 성능 최적화: 구성 캐싱 및 리소스 효율성을 통해 실행이 개선되었습니다.
- 더 나은 모니터링: 상태 점검 API, 자세한 오류 보고 및 포괄적인 로깅
- 개발자 경험: 구성의 핫 리로딩, 유연한 환경 제어 및 간소화된 API
또한 Claude Code의 모든 표준 혜택이 제공됩니다.
- Claude/Windsurf는 파일 편집에 어려움을 겪는 경우가 많습니다. Claude Code는 더 빠르고 더 나은 편집 기능을 제공합니다.
- 직접 실행하는 대신 여러 명령을 대기열에 넣을 수 있습니다. 이렇게 하면 컨텍스트 공간이 절약되어 더 중요한 정보가 더 오래 유지됩니다.
- 파일 작업, Git 또는 기타 작업에는 값비싼 모델이 필요하지 않습니다. Anthropic Max에 가입하면 Claude Code를 비용 효율적으로 사용할 수 있습니다.
- 클로드는 시스템 접근 권한이 더 넓으므로 일반 도우미가 막혔을 때 "클로드 코드 사용"을 요청하여 진행을 막힘 없이 진행할 수 있습니다.
📝 필수 조건
- Node.js v20 이상(fnm 또는 nvm을 사용하여 설치)
- Claude CLI를 로컬에 설치(실행하고 /doctor를 호출)하고
-dangerously-skip-permissions 허용했습니다.
💾 설치 및 사용
이 MCP 서버는 세 가지 방법으로 설치하고 사용할 수 있습니다.
🚀 방법 1: GitHub URL을 통해 (권장)
가장 유연한 방법은 npx 사용하여 GitHub에서 직접 설치하는 것입니다. 이렇게 하면 항상 저장소에서 최신 버전을 가져옵니다.
.mcp.json 파일에 다음을 추가하세요.
지엑스피1
📦 방법 2: npm 패키지를 통해
패키지가 npm에 게시된 경우 npm 패키지 이름을 사용하여 설치할 수 있습니다.
{
"mcpServers": {
"claude-code-mcp-enhanced": {
"command": "npx",
"args": [
"-y",
"@grahama1970/claude-code-mcp-enhanced@latest"
],
"env": {
"MCP_CLAUDE_DEBUG": "false",
"MCP_HEARTBEAT_INTERVAL_MS": "15000",
"MCP_EXECUTION_TIMEOUT_MS": "1800000"
}
}
}
}
🔧 방법 3: 로컬 설치
개발이나 테스트 목적으로 로컬 설치에서 서버를 실행할 수 있습니다.
- 저장소를 복제합니다.
git clone https://github.com/grahama1970/claude-code-mcp-enhanced.git
cd claude-code-mcp-enhanced
- 종속성을 설치하고 빌드합니다.
npm install
npm run build
- 로컬 서버를 사용하도록
.mcp.json 파일을 구성합니다.
{
"mcpServers": {
"claude-code-mcp-enhanced": {
"command": "node",
"args": [
"/path/to/claude-code-mcp-enhanced/dist/server.js"
],
"env": {
"MCP_CLAUDE_DEBUG": "false",
"MCP_HEARTBEAT_INTERVAL_MS": "15000",
"MCP_EXECUTION_TIMEOUT_MS": "1800000"
}
}
}
}
🔑 중요한 첫 번째 설정: 권한 수락
MCP 서버가 claude_code 도구를 성공적으로 사용하려면 먼저 --dangerously-skip-permissions 플래그를 사용하여 Claude CLI를 수동으로 한 번 실행하고 로그인한 다음 약관에 동의해야 합니다.
이는 Claude CLI의 일회성 요구 사항입니다.
npm install -g @anthropic-ai/claude-code
claude --dangerously-skip-permissions
안내에 따라 수락하세요. 수락이 완료되면 MCP 서버가 비대화형으로 플래그를 사용할 수 있게 됩니다.
macOS에서 도구를 처음 실행할 때 다양한 폴더 권한을 요청할 수 있으며, 첫 번째 실행은 실패할 수 있습니다. 이후 실행은 정상적으로 작동합니다.
🔗 MCP 클라이언트에 연결
서버를 설정한 후에는 MCP 클라이언트(Cursor, Claude Desktop 또는 mcp.json 이나 mcp_config.json 사용하는 다른 클라이언트)를 구성해야 합니다.
MCP 구성 파일 예
다음은 .mcp.json 파일에 Claude Code MCP 서버를 추가하는 방법의 예입니다.
{
"mcpServers": {
"Local MCP Server": {
"type": "stdio",
"command": "node",
"args": [
"dist/server.js"
],
"env": {
"MCP_USE_ROOMODES": "true",
"MCP_WATCH_ROOMODES": "true",
"MCP_CLAUDE_DEBUG": "false"
}
},
"other-services": {
// Your other MCP services here
}
}
}
MCP 구성 위치
구성은 일반적으로 JSON 파일로 이루어집니다. 이름과 위치는 클라이언트에 따라 다를 수 있습니다.
커서
커서는 mcp.json 사용합니다.
- macOS:
~/.cursor/mcp.json - 윈도우:
%APPDATA%\\Cursor\\mcp.json - 리눅스:
~/.config/cursor/mcp.json
윈드서핑
Windsurf 사용자는 mcp_config.json 사용합니다.
- macOS:
~/.codeium/windsurf/mcp_config.json - 윈도우:
%APPDATA%\\Codeium\\windsurf\\mcp_config.json - 리눅스:
~/.config/.codeium/windsurf/mcp_config.json
(참고: 일부 혼합 설정에서 Cursor도 설치되어 있으면 이러한 클라이언트는 Cursor의 ~/.cursor/mcp.json 경로를 다시 사용할 수 있습니다. Codeium 확장 기능을 사용하는 경우 Codeium 관련 경로를 우선시하세요.)
이 파일이 없으면 만드세요.
🛠️ 제공되는 도구
이 서버는 세 가지 주요 도구를 제공합니다.
claude_code 💬
--dangerously-skip-permissions 옵션을 사용하여 Claude Code CLI를 직접 실행합니다.
인수:
prompt (문자열, 필수): Claude Code에게 보낼 프롬프트입니다.workFolder (문자열, 선택 사항): Claude CLI 실행을 위한 작업 디렉토리로, 파일 작업을 사용하거나 파일을 참조할 때 필요합니다.parentTaskId (문자열, 선택 사항): 이 작업을 생성한 부모 작업의 ID(작업 오케스트레이션/부메랑용).returnMode (문자열, 선택 사항): 결과 반환 방식: 'summary'(간략하게) 또는 'full'(상세하게). 기본값은 'full'입니다.taskDescription (문자열, 선택 사항): 조직된 워크플로에서 더 나은 구성 및 추적을 위한 작업에 대한 간략한 설명입니다.mode (문자열, 선택 사항): MCP_USE_ROOMODES=true인 경우 사용할 Roo 모드를 지정합니다(예: "boomerang-mode", "coder", "designer" 등).
health 🩺
Claude Code MCP 서버의 상태, 버전 정보 및 현재 구성을 반환합니다.
건강 검진 요청 예시:
{
"toolName": "claude_code:health",
"arguments": {}
}
응답 예시:
{
"status": "ok",
"version": "1.12.0",
"claudeCli": {
"path": "claude",
"status": "available"
},
"config": {
"debugMode": true,
"heartbeatIntervalMs": 15000,
"executionTimeoutMs": 1800000,
"useRooModes": true,
"maxRetries": 3,
"retryDelayMs": 1000
},
"system": {
"platform": "linux",
"release": "6.8.0-57-generic",
"arch": "x64",
"cpus": 16,
"memory": {
"total": "32097MB",
"free": "12501MB"
},
"uptime": "240 minutes"
},
"timestamp": "2025-05-15T18:30:00.000Z"
}
convert_task_markdown 📋
마크다운 작업 파일을 Claude Code MCP 호환 JSON 형식으로 변환합니다.
인수:
markdownPath (문자열, 필수): 변환할 마크다운 작업 파일의 경로입니다.outputPath (문자열, 선택 사항): JSON 출력을 저장할 경로입니다. 지정하지 않으면 JSON을 직접 반환합니다.
요청 예시:
{
"toolName": "claude_code:convert_task_markdown",
"arguments": {
"markdownPath": "/home/user/tasks/validation.md",
"outputPath": "/home/user/tasks/validation.json"
}
}
예시 사용 시나리오
1. 기본 코드 작업
MCP 요청 예시:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nRefactor the function foo in main.py to be async.",
"workFolder": "/path/to/project"
}
}
2. 작업 오케스트레이션(부메랑 패턴)
부모 과제 요청:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nOrchestrate the implementation of a new API endpoint with the following subtasks:\n1. Create database models\n2. Implement API route handlers\n3. Write unit tests\n4. Document the API",
"workFolder": "/path/to/project"
}
}
하위 작업 요청(부모가 생성):
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nCreate database models for the new API endpoint as specified in the requirements.",
"workFolder": "/path/to/project",
"parentTaskId": "task-123",
"returnMode": "summary",
"taskDescription": "Database model creation for API endpoint"
}
}
3. 특수 모드 요청
Roo 모드 사용 예:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
"workFolder": "/path/to/project",
"mode": "coder"
}
}
🔄 작업 변환기
MCP 서버에는 사람이 읽을 수 있는 마크다운 작업 목록을 완전히 실행 가능한 MCP 명령으로 자동 변환하는 강력한 작업 변환 도구가 포함되어 있습니다. 이 지능형 변환기는 사람이 작업에 대해 생각하는 방식과 기계가 작업을 실행하는 방식 사이의 간극을 메워줍니다.
전체 워크플로
워크플로 단계
- 사용자는 MCP를 구성 파일에 추가합니다.
- 사용자가 Claude에게 "convert_task_markdown을 사용하여 내 task.md 파일을 실행하세요"라고 묻습니다 .
- MCP는 자동으로 :
- 마크다운 파일을 로드합니다
- 형식을 검증합니다(섹션이 누락된 경우 오류를 반환합니다)
- 사람이 읽을 수 있는 작업을 정확한 실행 가능 명령으로 변환합니다.
- Claude Code가 순차적으로 실행할 수 있는 JSON을 반환합니다.
- Claude는 JSON을 수신 하고
claude_code 도구를 사용하여 각 작업을 실행할 수 있습니다.
주요 특징
- 자동 경로 확인: "프로젝트로 디렉토리 변경"과 같은 일반 명령어를 전체 경로가 포함된 정확한 실행 가능 명령어로 변환합니다.
- 스마트 명령 번역: 영어 명령어를 정확한 터미널 명령으로 변환합니다(예: "가상 환경 활성화" →
source .venv/bin/activate ) - MCP 프로토콜 준수: 모든 출력이 모델 컨텍스트 프로토콜과 100% 호환되는지 확인합니다.
- 모호성 없음: 생성된 모든 명령은 정확한 경로와 실행 가능한 구문을 사용합니다. 플레이스홀더나 일반 참조는 없습니다.
- 형식 검증: 적절한 마크다운 구조를 적용하고 잘못된 형식에 대한 유용한 오류 메시지를 제공합니다.
- 실시간 진행 상황 업데이트: 변환 중에 어떤 작업이 처리되고 있는지 보여주는 실시간 진행 상황 업데이트를 제공합니다.
마크다운 작업을 MCP 명령으로 변환
convert_task_markdown 도구는 구조화된 마크다운 파일을 처리하고 MCP 호환 JSON을 생성합니다.
요청 형식:
{
"tool": "convert_task_markdown",
"arguments": {
"markdownPath": "/path/to/tasks.md",
"outputPath": "/path/to/output.json" // optional
}
}
응답 형식:
{
"tasksCount": 5,
"outputPath": "/path/to/output.json",
"tasks": [
{
"tool": "claude_code",
"arguments": {
"command": "cd /project && source .venv/bin/activate\n\nTASK TYPE: Validation...",
"dangerously_skip_permissions": true,
"timeout_ms": 300000
}
}
// ... more tasks
]
}
마크다운 작업 파일 형식
작업 마크다운 파일은 다음 구조를 따라야 합니다.
# Task 001: Task Title
## Objective
Clear description of what needs to be accomplished.
## Requirements
1. [ ] First requirement
2. [ ] Second requirement
## Tasks
### Module or Component Name
- [ ] Validate `path/to/file.py`
- [ ] Step 1
- [ ] Step 2
- [ ] Step 3
변환기는 다음을 수행합니다.
- 마크다운 구조 분석
- 작업 메타데이터 및 요구 사항 추출
- 각 검증 작업에 대한 자세한 프롬프트를 생성합니다.
- 적절한 작업 디렉토리 설정을 포함합니다.
- 검증 및 완료 요약 추가
사용 예
- 작업 파일 (
tasks/api_validation.md )을 생성합니다.
# Task 001: API Endpoint Validation
## Objective
Validate all API endpoints work with real database connections.
## Requirements
1. [ ] All endpoints must use real database
2. [ ] No mock data in validation
## Core API Tasks
- [ ] Validate `api/users.py`
- [ ] Change directory to project and activate .venv
- [ ] Test user creation endpoint
- [ ] Test user retrieval endpoint
- [ ] Verify JSON responses
- MCP 작업으로 변환 :
{
"tool": "convert_task_markdown",
"arguments": {
"markdownPath": "/project/tasks/api_validation.md"
}
}
- 변환기는 실시간 진행 상황을 보여줍니다 :
[Progress] Loading task file...
[Progress] Validating markdown structure...
[Progress] Converting 27 validation tasks...
[Progress] Task 1/27: Converting core/constants.py
[Progress] Task 2/27: Converting core/arango_setup.py
...
[Progress] Conversion complete!
- 변환기는 일반적인 명령어를 정확한 명령으로 변환합니다 .
- "프로젝트로 디렉토리를 변경하고 .venv를 활성화하세요"는 다음과 같이 됩니다.
cd /home/user/project && source .venv/bin/activate
- 모든 경로는 절대 경로로 확인됩니다.
- 모든 명령은 모호함 없이 완벽하게 실행 가능합니다.
- 변환된 작업 실행 : 반환된 작업에는 정확하고 실행 가능한 명령이 포함되어 있으며
claude_code 도구를 사용하여 순차적으로 실행할 수 있습니다.
완전한 예: 마크다운에서 실행까지
1단계: 사용자가 마크다운 작업 파일 ( project_tasks.md )을 만듭니다.
# Task 001: Setup Development Environment
## Objective
Initialize the development environment with all dependencies.
## Requirements
1. [ ] Python 3.11+ installed
2. [ ] Virtual environment created
## Tasks
- [ ] Validate `setup.py`
- [ ] Change to project directory
- [ ] Create virtual environment
- [ ] Install dependencies
2단계: 사용자가 Claude에게 다음과 같이 묻습니다 .
Use convert_task_markdown to process /home/user/project_tasks.md
3단계: MCP가 다음을 변환하고 검증합니다 .
- 형식이 올바른 경우: 실행 가능한 JSON을 반환합니다.
- 형식이 잘못된 경우: 지침과 함께 오류를 반환합니다.
4단계: 결과(성공 시) :
[
{
"tool": "claude_code",
"arguments": {
"prompt": "cd /home/user/project && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt",
"workFolder": "/home/user/project"
}
}
]
5단계: Claude는 각 작업을 순차적으로 실행할 수 있습니다.
형식 검증 및 오류 처리
작업 변환기는 일관되고 안정적인 작업 변환을 위해 특정 마크다운 구조를 적용합니다. 마크다운 파일의 형식이 올바르지 않은 경우, 변환기는 다음과 같은 유용한 오류 메시지를 표시합니다.
오류 응답 예:
{
"status": "error",
"error": "Markdown format validation failed",
"details": "Markdown format validation failed:\n - Missing required title. Format: '# Task NNN: Title'\n - Missing or empty 'Requirements' section. Format: '## Requirements\\n1. [ ] Requirement'\n - No validation tasks found. Format: '- [ ] Validate `module.py`' with indented steps\n\nRequired markdown format:\n# Task NNN: Title\n## Objective\nClear description\n## Requirements\n1. [ ] First requirement\n## Task Section\n- [ ] Validate `file.py`\n - [ ] Step 1\n - [ ] Step 2",
"helpUrl": "https://github.com/grahama1970/claude-code-mcp-enhanced/blob/main/README.md#markdown-task-file-format"
}
검증을 통해 다음이 보장됩니다.
- 필수 섹션이 존재합니다(제목, 목표, 요구 사항)
- 작업은 적절한 체크박스 형식을 사용합니다.
- 각 작업에는 들여쓰기 단계가 있습니다.
- 요구 사항은 일관성을 위해 체크박스 형식을 사용합니다.
🦚 작업 오케스트레이션 패턴
이 MCP 서버는 복잡한 워크플로를 효율적으로 처리할 수 있는 강력한 작업 오케스트레이션 기능을 지원합니다.
부메랑 패턴(Claude Desktop ⟷ Claude Code)
Boomerang 패턴을 사용하면 Claude Desktop에서 작업을 조율하고 Claude Code에 위임할 수 있습니다. 이를 통해 다음과 같은 작업을 수행할 수 있습니다.
- 복잡한 워크플로를 더 작고 관리하기 쉬운 하위 작업으로 분할합니다.
- 상위 작업에서 하위 작업으로 컨텍스트 전달
- 하위 작업에서 상위 작업으로 결과를 다시 가져옵니다.
- 상세 결과 또는 요약 결과 중에서 선택하세요
- 구조화된 작업 목록을 통해 진행 상황을 추적하고 관리합니다.
부메랑 패턴 시각화
다음은 Claude가 레시피 작업을 여러 단계로 나누어 Claude Code에 위임하는 방식을 보여주는 간단한 다이어그램입니다.
이 예에서는:
- 사용자는 Claude에게 초콜릿 케이크 레시피를 만들어 달라고 요청합니다.
- Claude(부모)는 이를 별도의 작업으로 나눕니다.
- Claude는 부모 작업 ID를 사용하여 "레시피 찾기" 작업을 Claude Code에게 위임합니다.
- Claude Code는 Claude에게 레시피 정보를 반환합니다.
- Claude는 "측정값 변환" 작업을 Claude Code에게 위임합니다.
- Claude Code는 변환된 측정값을 반환합니다.
- Claude는 모든 결과를 결합하여 사용자에게 완전한 솔루션을 제시합니다.
간단한 작업 예:
과제 1 - 레시피 찾기:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Search for a classic chocolate cake recipe. Find one with good reviews.",
"parentTaskId": "cake-recipe-123",
"returnMode": "summary",
"taskDescription": "Find Chocolate Cake Recipe"
}
}
과제 2 - 측정값 변환:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Convert the measurements in this recipe from cups to grams:\n\n- 2 cups flour\n- 1.5 cups sugar\n- 3/4 cup cocoa powder",
"parentTaskId": "cake-recipe-123",
"returnMode": "summary",
"taskDescription": "Convert Recipe Measurements"
}
}
작동 원리
- 하위 작업 만들기:
- 부모 작업에서 고유한 작업 ID를 생성합니다.
- 다음을 사용하여
claude_code 도구에 요청을 보냅니다.- 귀하의 특정 프롬프트
- 부모 작업 ID
- 작업 설명
- 원하는 반환 모드('요약' 또는 '전체')
- 결과 수신:
- 하위 작업 결과에는 특수 마커가 포함됩니다:
<!-- BOOMERANG_RESULT {...} --> - 이 마커에는 작업 메타데이터가 포함된 JSON이 포함되어 있습니다.
- 부모 작업은 이를 구문 분석하여 완료된 하위 작업을 식별할 수 있습니다.
- Claude Desktop을 사용한 워크플로 예시:
You: I need to refactor this codebase. It's quite complex.
Claude Desktop: I'll help you with that. Let me break this down into smaller tasks for Claude Code to handle:
1. First, I'll have Claude Code analyze the codebase structure
2. Then, I'll have it identify problematic patterns
3. Finally, I'll ask it to generate a refactoring plan
[Claude Desktop sends a request to the claude_code tool with parentTaskId="task1" and returnMode="summary"]
[Claude Code analyzes the codebase and returns a summary with the BOOMERANG_RESULT marker]
Claude Desktop: Based on Claude Code's analysis, here are the key issues found:
- Duplicate code in modules X and Y
- Poor separation of concerns in module Z
- Inconsistent naming conventions
Now I'll ask Claude Code to suggest specific refactorings...
이러한 접근 방식은 심층 분석이나 여러 단계가 필요한 복잡한 작업에 특히 유용합니다.
포괄적인 작업 목록 관리 예
다음은 Claude Code MCP와 함께 Claude를 사용하여 구조화된 작업 목록을 관리하고 실행하는 자세한 예입니다.
1. 작업 목록 구조 설정
먼저, 다음 구조의 작업 목록 파일(예: tasks.md )을 만듭니다.
# Project Task List
## Parent Task: API Optimization Project
- [ ] Optimize API performance for high-traffic endpoints
- [ ] Analyze current API performance and identify bottlenecks
- [ ] Implement database query optimization for user endpoints
- [ ] Add Redis caching for frequently accessed data
- [ ] Set up performance monitoring
## Assumptions and Decisions
- [2025-05-15] Assumption: Redis is available in the infrastructure
- [2025-05-15] Decision: Focus on user endpoints first (Rationale: Highest traffic area)
## Relevant Files
- `src/controllers/userController.js`: User API endpoints
- `src/services/userService.js`: Business logic for user operations
## Improvement Notes
- Pattern identified: N+1 query issue in user listing endpoint
- Automation opportunity: Add caching automatically for all get-by-id endpoints
2. 작업 목록 실행
이제 Claude는 Claude Code를 사용하여 체계적으로 작업을 수행할 수 있습니다.
You: Please help me execute the task list in tasks.md, starting with the first subtask.
Claude: I'll help you work through your task list systematically. Let me first check the current task list to identify the next task to work on.
[Claude uses claude_code to read the task list]
I see the first subtask is "Analyze current API performance and identify bottlenecks". I'll execute this task now using Claude Code.
[Claude sends the following request to claude_code]:
{
"toolName": "claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Analysis\nTASK ID: api-perf-analysis\nCURRENT SUBTASK: Analyze current API performance and identify bottlenecks\n\nCONTEXT:\n- Parent task goal: Optimize API performance for high-traffic endpoints\n- This is the first step in our optimization process\n- Focus on user endpoints as noted in assumptions\n\nINSTRUCTIONS:\n1. Analyze the current API implementation in src/controllers/userController.js and src/services/userService.js\n2. Run performance tests on the user endpoints\n3. Identify specific bottlenecks and performance issues\n4. Document findings in a clear, structured format\n5. Update task list file after completion\n\nAfter completion, provide summary in this format:\n\nCOMPLETION SUMMARY:\n- What was done:\n- Results:\n- Files analyzed:\n- Issues identified:\n- Recommendations:\n- Next subtask in list:",
"workFolder": "/path/to/project"
}
}
[Claude Code executes the analysis task and returns results]
Great! Claude Code has completed the analysis. Here's what was found:
1. Main performance bottlenecks identified:
- N+1 query problem in the user listing endpoint
- Missing indexes on frequently queried fields
- No caching for repetitive data lookups
2. Recommendations:
- Add eager loading for user relationships
- Create database indexes for user_id and email fields
- Implement Redis caching with a 5-minute TTL
Let me update the task list to mark this task as complete and proceed to the next one.
[Claude uses claude_code to update the task list]:
{
"toolName": "claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Task List Update\n\n1. Read the current task list in tasks.md\n2. Mark the 'Analyze current API performance and identify bottlenecks' subtask as [x]\n3. Add new findings to the Improvement Notes section\n4. Add any new relevant files identified during analysis\n5. Write updated task list\n6. Return the updated task list",
"workFolder": "/path/to/project"
}
}
[Claude Code updates the task list and marks the first subtask complete]
I've updated the task list. The first subtask is now complete, and I've added the detailed findings to the Improvement Notes section. The next subtask is "Implement database query optimization for user endpoints".
Would you like me to proceed with this next subtask now?
3. 후속 작업 계속
확인을 받은 후, 클로드는 다음 하위 작업을 계속합니다.
You: Yes, please proceed with the next subtask.
Claude: I'll now execute the next subtask: "Implement database query optimization for user endpoints". This will involve fixing the N+1 query problem identified in the analysis and adding appropriate database indexes.
[Claude sends the following request to claude_code]:
{
"toolName": "claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Code Implementation\nTASK ID: db-query-optimization\nCURRENT SUBTASK: Implement database query optimization for user endpoints\n\nCONTEXT:\n- Parent task goal: Optimize API performance for high-traffic endpoints\n- Previous subtask identified N+1 query issues and missing indexes\n- Need to implement eager loading and proper indexes\n\nINSTRUCTIONS:\n1. Modify src/controllers/userController.js to implement eager loading for related data\n2. Add appropriate database indexes to user-related tables\n3. Refactor any inefficient database queries in userService.js\n4. Ensure changes maintain existing functionality\n5. Run tests to verify performance improvements\n6. Update task list file after completion\n\nAfter completion, provide summary in this format:\n\nCOMPLETION SUMMARY:\n- What was done:\n- Results:\n- Files modified:\n- Performance improvements:\n- Next subtask in list:",
"workFolder": "/path/to/project"
}
}
[Claude Code implements the optimizations and returns results]
Excellent! The database query optimizations have been successfully implemented. Here's a summary:
1. Changes made:
- Added eager loading in userController.js for user relationships
- Created new database indexes for user_id and email fields
- Refactored list query to use a single efficient JOIN statement
- Added pagination to prevent large result sets
2. Performance results:
- User listing endpoint response time reduced by 68%
- Database query count reduced from 25+ to 3 for typical requests
Let me update the task list again to reflect this progress.
[Claude uses claude_code to update the task list again]:
{
"toolName": "claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nTASK TYPE: Task List Update\n\n1. Read the current task list in tasks.md\n2. Mark the 'Implement database query optimization for user endpoints' subtask as [x]\n3. Add new files modified to the Relevant Files section\n4. Update Improvement Notes with performance metrics\n5. Write updated task list\n6. Return the updated task list",
"workFolder": "/path/to/project"
}
}
[Claude Code updates the task list and marks the second subtask complete]
I've updated the task list again. Two subtasks are now complete, and the next one is "Add Redis caching for frequently accessed data". Would you like me to continue with this subtask?
이러한 체계적인 접근 방식을 통해 클로드는 프로세스 전반에 걸쳐 진행 상황, 가정 및 관련 파일에 대한 명확한 문서를 유지하면서 복잡한 작업 목록을 체계적으로 처리할 수 있습니다.
🎭 셀프 오케스트레이션 패턴(오케스트레이터로서의 클로드 코드)
Claude Desktop은 종종 부모 에이전트로 사용되지만, Claude Code 자체를 오케스트레이터와 실행자로 모두 사용할 수 있습니다. 이 접근 방식을 사용하면 Claude Desktop 없이도 Claude Code가 자체 작업 오케스트레이션을 관리하는 독립형 시스템이 구축됩니다.
구현 단계
- 작업 구조를 초기화하고 Claude Code를 오케스트레이터로 시작하는 진입 스크립트를 만듭니다.
- 작업 상태 및 종속성을 추적하는 작업 데이터 구조(일반적으로 JSON 형식)를 설계합니다 .
- 개별 작업을 처리하고 작업 상태를 업데이트하기 위한 작업 실행자 스크립트를 만듭니다.
셀프 오케스트레이션의 주요 이점
- 독립형 : 외부 오케스트레이터(예: Claude Desktop)가 필요하지 않습니다.
- 지속 상태 : 모든 작업 정보는 JSON 파일에 저장됩니다.
- 오류 복구 : 중단된 경우 마지막으로 성공한 작업부터 다시 시작할 수 있습니다.
- 간소화된 종속성 관리 : 단일 시스템이 모든 Claude Code 상호 작용을 관리합니다.
- 셸 스크립트 자동화 : CI/CD 파이프라인이나 자동화된 워크플로에 쉽게 통합
예제 스크립트와 작업 구조가 포함된 자세한 구현 가이드는 Claude Code를 사용한 자체 오케스트레이션을 참조하세요.
👓 Roo 모드 통합
이 MCP 서버는 .roomodes 구성 파일을 통해 특수 모드와의 통합을 지원합니다. 활성화하면 각 작업에 사용할 모드를 지정하여 특수 동작을 구현할 수 있습니다.
Roo 모드 사용 방법
- Roo 모드 지원 활성화:
- MCP 구성에서 환경 변수
MCP_USE_ROOMODES=true 설정하세요. - MCP 서버의 루트 디렉토리에
.roomodes 파일을 만듭니다. - 파일이 변경될 때 구성을 자동으로 다시 로드하려면
MCP_WATCH_ROOMODES=true 로 핫 리로딩을 활성화하세요.
- 모드 구성:
.roomodes 파일에는 customModes 배열이 있는 JSON 개체가 포함되어야 합니다.- 각 모드에는
slug , name , roleDefinition 있어야 하며 선택적으로 modelId 있는 apiConfiguration 있어야 합니다.
- 모드 사용:
claude_code 도구에 요청을 할 때 원하는 모드의 슬러그와 함께 mode 매개변수를 포함합니다.- MCP 서버는 역할 정의와 모델 구성을 자동으로 적용합니다.
- 예시 .roomodes 파일:
{
"customModes": [
{
"slug": "coder",
"name": "💻 Coder",
"roleDefinition": "You are a coding specialist who writes clean, efficient code.",
"apiConfiguration": {
"modelId": "claude-3-sonnet-20240229"
}
},
{
"slug": "designer",
"name": "🎨 Designer",
"roleDefinition": "You are a design specialist focused on UI/UX solutions."
}
]
}
- 환경 구성 예:
{
"mcpServers": {
"claude-code-mcp-enhanced": {
"command": "npx",
"args": ["github:grahama1970/claude-code-mcp-enhanced"],
"env": {
"MCP_USE_ROOMODES": "true",
"MCP_WATCH_ROOMODES": "true",
"MCP_CLAUDE_DEBUG": "false"
}
}
}
}
- 모드를 사용하여 요청하기:
{
"toolName": "claude_code:claude_code",
"arguments": {
"prompt": "Your work folder is /path/to/project\n\nCreate unit tests for the user authentication module.",
"workFolder": "/path/to/project",
"mode": "coder"
}
}
Roo Modes의 주요 기능:
- 특수 동작 : 모드마다 시스템 프롬프트와 모델 구성이 다를 수 있습니다.
- 핫 리로딩 :
MCP_WATCH_ROOMODES=true 인 경우 서버는 .roomodes 파일이 변경될 때 구성을 자동으로 다시 로드합니다. - 성능 : 서버는 더 나은 성능을 위해 roomodes 구성을 캐시합니다.
- 폴백 : 모드를 찾을 수 없거나 룸모드가 비활성화된 경우 서버는 기본 동작을 계속합니다.
🛠️ 향상된 안정성 기능
이 서버에는 안정성과 성능을 향상시키기 위한 여러 가지 개선 사항이 포함되어 있습니다.
1. 하트비트 및 타임아웃 방지
장기 실행 작업 중 클라이언트 측 시간 초과를 방지하려면 다음을 수행하세요.
- 15초마다 진행 상황 업데이트를 보내는 구성 가능한 하트비트 메커니즘이 추가되었습니다.
- 실행 시간 추적 및 보고 구현
- 환경 변수를 통해 구성 가능한 시간 초과 매개변수가 추가되었습니다.
2. 재시도를 통한 강력한 오류 처리
일시적인 오류에 대한 지능형 재시도 논리가 추가되었습니다.
- 구성 가능한 매개변수를 사용하여 자동 재시도를 구현했습니다.
- 재시도 가능한 문제를 식별하기 위해 오류 분류가 추가되었습니다.
- 자세한 오류 보고 및 추적을 생성했습니다.
3. 요청 추적 시스템
포괄적인 요청 수명 주기 관리 구현:
- 각 요청에 대해 고유 ID가 추가되었습니다.
- 진행 중인 요청에 대한 추적을 생성했습니다.
- 완료 또는 실패 시 적절한 정리가 보장됨
4. 우아한 종료
적절한 프로세스 종료 처리가 추가되었습니다.
- SIGINT 및 SIGTERM에 대한 신호 처리기를 구현했습니다.
- 진행 중인 요청에 대한 추적이 추가되었습니다.
- 깨끗한 종료를 위한 대기 논리를 생성했습니다.
- 출구에서 적절한 청소가 이루어졌습니다.
5. 구성 캐싱 및 핫 리로딩
구성에 대한 성능 최적화가 추가되었습니다.
- roomodes 파일에 대한 캐싱 구현
- 파일 변경 사항에 따라 자동 무효화 기능이 추가되었습니다.
- 구성 가능한 파일 감시 메커니즘을 생성했습니다.
⚙️ 구성 옵션
다음 환경 변수를 사용하여 서버의 동작을 사용자 지정할 수 있습니다.
| 변하기 쉬운 | 설명 | 기본 |
|---|
CLAUDE_CLI_PATH | Claude CLI 실행 파일의 절대 경로 | 자동 감지 |
MCP_CLAUDE_DEBUG | 자세한 디버그 로깅 활성화 | false |
MCP_HEARTBEAT_INTERVAL_MS | 진행 상황 보고서 간 간격 | 15000(15초) |
MCP_EXECUTION_TIMEOUT_MS | CLI 실행 시간 초과 | 1800000(30m) |
MCP_MAX_RETRIES | 일시적 오류에 대한 최대 재시도 횟수 | 3 |
MCP_RETRY_DELAY_MS | 재시도 시도 사이의 지연 | 1000(1초) |
MCP_USE_ROOMODES | Roo 모드 통합 활성화 | false |
MCP_WATCH_ROOMODES | 변경 시 .roomodes를 자동으로 다시 로드합니다. | false |
이러한 설정은 셸 환경이나 mcp.json 서버 구성의 env 블록 내에서 설정할 수 있습니다.
📸 시각적 예시
서버가 실제로 작동하는 모습을 보여주는 몇 가지 시각적 예는 다음과 같습니다.
ESLint 설정 수정
다음은 Claude Code MCP 도구를 사용하여 기존 구성 파일을 삭제하고 새 구성 파일을 만들어 ESLint 설정을 대화형으로 수정하는 예입니다.
파일 목록 예제
다음은 Claude Code 도구가 디렉토리의 파일을 나열하는 예입니다.
복잡한 다단계 작업
이 예제는 claude_code 브랜치를 만들어 릴리스를 준비하고, 여러 파일( package.json , CHANGELOG.md )을 업데이트하고, 변경 사항을 커밋하고, 풀 리퀘스트를 시작하는 등 보다 복잡하고 여러 단계로 구성된 작업을 단일하고 일관된 작업으로 처리하는 방법을 보여줍니다.
GitHub Actions 워크플로 수정
🎯 주요 사용 사례
이 서버는 통합된 claude_code 도구를 통해 AI가 Claude Code CLI에 직접 접근할 수 있도록 하여 다양하고 강력한 기능을 제공합니다. 다음은 이러한 기능을 활용할 수 있는 몇 가지 예입니다.
- 코드 생성, 분석 및 리팩토링:
"Generate a Python script to parse CSV data and output JSON.""Analyze my_script.py for potential bugs and suggest improvements."
- 파일 시스템 작업(생성, 읽기, 편집, 관리):
- 파일 생성:
"Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db" - 파일 편집:
"Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'." - 이동/복사/삭제:
"Your work folder is /Users/steipete/my_project\n\nMove the file 'report.docx' from the 'drafts' folder to the 'final_reports' folder and rename it to 'Q1_Report_Final.docx'."
- 버전 제어(Git):
"Your work folder is /Users/steipete/my_project\n\n1. Stage the file 'src/main.java'.\n2. Commit the changes with the message 'feat: Implement user authentication'.\n3. Push the commit to the 'develop' branch on origin."
- 터미널 명령 실행:
"Your work folder is /Users/steipete/my_project/frontend\n\nRun the command 'npm run build'.""Open the URL https://developer.mozilla.org in my default web browser."
- 웹 검색 및 요약:
"Search the web for 'benefits of server-side rendering' and provide a concise summary."
- 복잡한 다단계 워크플로:
- 버전 범프 자동화, 변경 로그 업데이트, 릴리스 태그 지정:
"Your work folder is /Users/steipete/my_project\n\nFollow these steps: 1. Update the version in package.json to 2.5.0. 2. Add a new section to CHANGELOG.md for version 2.5.0 with the heading '### Added' and list 'New feature X'. 3. Stage package.json and CHANGELOG.md. 4. Commit with message 'release: version 2.5.0'. 5. Push the commit. 6. Create and push a git tag v2.5.0."
- 구문 오류가 있는 파일 복구:
"Your work folder is /path/to/project\n\nThe file 'src/utils/parser.js' has syntax errors after a recent complex edit that broke its structure. Please analyze it, identify the syntax errors, and correct the file to make it valid JavaScript again, ensuring the original logic is preserved as much as possible."
- GitHub와 상호 작용(예: 풀 리퀘스트 생성):
"Your work folder is /Users/steipete/my_project\n\nCreate a GitHub Pull Request in the repository 'owner/repo' from the 'feature-branch' to the 'main' branch. Title: 'feat: Implement new login flow'. Body: 'This PR adds a new and improved login experience for users.'"
- GitHub와 상호 작용(예: PR CI 상태 확인):
"Your work folder is /Users/steipete/my_project\n\nCheck the status of CI checks for Pull Request #42 in the GitHub repository 'owner/repo'. Report if they have passed, failed, or are still running."
중요: 파일 시스템이나 git 작업에 대한 프롬프트에서 현재 작업 디렉터리(CWD) 컨텍스트를 제공하는 것을 잊지 마세요(예: "Your work folder is /path/to/project\n\n...your command..." ).
🔧 문제 해결
- "명령을 찾을 수 없습니다"(claude-code-mcp): 전역으로 설치된 경우, npm 전역 bin 디렉터리가 시스템 PATH에 있는지 확인하세요.
npx 사용하는 경우, npx 자체가 작동하는지 확인하세요. - "명령을 찾을 수 없습니다"(claude 또는 ~/.claude/local/claude): Claude CLI가 올바르게 설치되었는지 확인하세요.
claude/doctor 실행하거나 관련 설명서를 확인하세요. - 권한 문제: "중요한 최초 설정" 단계를 실행했는지 확인하세요.
- 서버의 JSON 오류:
MCP_CLAUDE_DEBUG 가 true 이면 오류 메시지나 로그가 MCP의 JSON 파싱을 방해할 수 있습니다. 정상적인 작동을 위해서는 false 로 설정하세요. - ESM/가져오기 오류: Node.js v20 이상을 사용하고 있는지 확인하세요.
- 클라이언트 시간 초과: 장기 실행 작업의 경우, 서버는 클라이언트 시간 초과를 방지하기 위해 15초마다 하트비트 메시지를 전송합니다. 그래도 시간 초과가 발생하면
MCP_HEARTBEAT_INTERVAL_MS 환경 변수를 사용하여 하트비트 간격을 조정할 수 있습니다. - 네트워크/서버 오류: 서버에 일시적인 오류에 대한 자동 재시도 로직이 추가되었습니다. 문제가 지속되면
MCP_MAX_RETRIES 및 MCP_RETRY_DELAY_MS 값을 늘려 보세요. - Claude CLI 대체 경고: "~/.claude/local/claude에서 Claude CLI를 찾을 수 없습니다."라는 경고가 표시되는 것은 정상입니다. 서버가 PATH의
claude 명령으로 대체되고 있습니다. 필요한 경우 CLAUDE_CLI_PATH 환경 변수를 설정하여 Claude CLI 실행 파일의 정확한 경로를 지정할 수 있습니다.
👨💻 개발자를 위한: 로컬 설정 및 기여
이 서버를 개발하거나 이 서버에 기여하거나 테스트를 위해 복제된 저장소에서 실행하려면 로컬 설치 및 개발 설정 가이드를 참조하세요.
💪 기여
여러분의 참여를 환영합니다! 환경 설정에 대한 자세한 내용은 로컬 설치 및 개발 설정 가이드를 참조하세요.
GitHub 저장소 에 이슈와 풀 리퀘스트를 제출하세요.
⚖️ 라이센스
MIT
💬 피드백 및 지원
Claude Code MCP 서버 사용에 문제가 발생하거나 궁금한 사항이 있는 경우 다음을 수행하세요.
- 위의 문제 해결 섹션을 확인하세요
- GitHub 저장소 에 이슈를 제출하세요
- 저장소 토론 섹션에서 토론에 참여하세요
이 도구를 개선하기 위해 여러분의 피드백과 기여에 감사드립니다!