director-shell-mcp

director-shell-mcp는 director 모드 에이전트를 위한 소형 MCP 서버입니다. MCP stdio 전송을 사용하여 파일 쓰기, Python 데이터 탐색 코드 실행, 셸 명령 실행, 그리고 분리된 백그라운드 작업 감독을 위한 통제된 탈출구를 제공합니다. 명령은 에이전트가 도구를 명시적으로 호출할 때만 시작되며, 서버는 자체적으로 셸을 실행하지 않습니다.

설치

Node.js 18 이상이 필요합니다. 이 디렉터리에서:

npm install

다음과 같이 서버를 직접 실행합니다:

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

OMP 등록(기본)

기본 클라이언트는 Oh My Pi(OMP) 하네스입니다. 사용자 수준의 ~/.omp/agent/mcp.json(또는 프로젝트 수준의 .omp/mcp.json)에 다음 정확한 구성을 추가하세요:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

stdio 서버의 경우 type은 생략할 수 있습니다. 구성을 편집한 후 OMP에서 /mcp reload를 실행하고 이어서 /mcp test director-shell을 실행하세요.

일반 MCP 클라이언트 등록

다른 MCP 클라이언트는 일반적으로 동등한 stdio 등록을 허용합니다:

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

도구 참조

모든 도구는 MCP 텍스트 콘텐츠에 JSON 객체를 반환합니다. 오류는 문장 형태의 error 필드와 함께 MCP 도구 오류로 반환됩니다.

shell_run

명령을 완료까지 실행합니다. 매개변수:

• command(문자열, 필수): 명령 텍스트.

• cwd(문자열, 선택): 작업 디렉터리.

• timeout_ms(정수, 선택): 기본값 60,000, 최대 600,000.

• shell(powershell, cmd 또는 bash, 선택): Windows에서는 PowerShell, 그 외 시스템에서는 Bash가 기본값입니다.

결과에는 exit_code, duration_ms, 그리고 stdout/stderr 객체가 포함됩니다. 각 스트림에는 최대 약 50KiB의 미리보기 텍스트가 포함됩니다. 스트림이 해당 상한을 초과하면 해당 객체에는 truncated: true와 전체 스트림이 포함된 임시 파일을 가리키는 full_output_path도 포함됩니다. 시간 초과 시 명확한 메시지와 부분 결과가 포함된 MCP 도구 오류가 반환됩니다.

write_file

절대 파일 경로에 UTF-8 텍스트를 씁니다. 매개변수:

• path(문자열, 필수): 절대 파일 경로.

• content(문자열, 필수): 쓸 텍스트.

• append(부울, 선택): 덮어쓰는 대신 추가합니다. 기본값은 false입니다.

• create_dirs(부울, 선택): 누락된 상위 디렉터리를 생성합니다. 기본값은 true입니다.

결과에는 path, bytes_written, created(호출 전에 파일이 존재하지 않았는지 여부), appended가 포함됩니다.

edit_file

절대 경로의 UTF-8 파일에서 텍스트를 교체합니다. 매개변수:

• path(문자열, 필수): 절대 파일 경로.

• old_text(문자열, 필수): 찾을 비어 있지 않은 텍스트.

• new_text(문자열, 필수): 교체 텍스트.

• replace_all(부울, 선택): 모든 항목을 교체합니다. 기본값은 false입니다.

replace_all 없이 old_text는 정확히 한 번만 나타나야 합니다. 일치 항목이 없거나 여러 번 일치하면 MCP 도구 오류가 반환되고 파일은 변경되지 않습니다. 결과에는 path와 replacements가 포함됩니다.

run_python

Python 소스 코드를 출력 제한과 시간 초과와 함께 완료까지 실행합니다. Windows에서는 서버가 먼저 py 런처를 시도한 다음 python을 시도하고, 다른 시스템에서는 먼저 python3을 시도한 다음 python을 시도하며, 첫 번째 사용 가능한 실행 파일을 캐시합니다. 매개변수:

• code(문자열, 필수): Python 소스 코드.

• cwd(문자열, 선택): Python 프로세스의 작업 디렉터리.

• timeout_ms(정수, 선택): 기본값 60,000, 최대 600,000.

• args(문자열 배열, 선택): sys.argv[1:]로 전달되는 값.

결과에는 exit_code, duration_ms, stdout/stderr 객체, python_executable이 포함됩니다. 출력 스트림은 상한이 적용되며 shell_run과 동일한 방식으로 임시 파일에 넘쳐 기록됩니다. 시간 초과 시 명확한 메시지와 부분 결과가 포함된 MCP 도구 오류가 반환됩니다.

job_start

도구 호출이 반환된 후에도 계속 실행되는 분리된 명령을 시작합니다. 매개변수:

• command(문자열, 필수)

• cwd(문자열, 선택)

• shell(powershell, cmd 또는 bash, 선택)

• name(문자열, 선택, 사람이 읽을 수 있는 레이블)

결과에는 job_id, pid, log_paths(stdout, stderr, combined), exit_marker 경로가 포함됩니다. 메타데이터는 %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/ 아래에 JSON으로 영구 저장되므로 서버를 다시 시작한 후에도 작업을 계속 찾을 수 있습니다.

job_status

작업의 영구 저장된 상태를 읽습니다. 매개변수:

• job_id(문자열, 필수): job_start가 반환한 ID.

• tail_lines(정수, 선택): 기본값 40, 최대 1,000.

결과에는 running, exit_code(사용 가능한 경우), runtime_ms, started_at, combined 로그의 output_tail이 포함됩니다. 분리된 래퍼는 명령이 종료될 때 exit_code.txt를 작성하여 서버를 다시 시작해도 종료 코드를 보존합니다.

job_kill

이 서버가 시작한 작업을 종료합니다. job_id를 받습니다. Windows에서는 taskkill /T /F를 사용하여 래퍼의 프로세스 트리를 종료합니다. 이미 완료된 작업은 변경되지 않습니다.

job_list

유효한 모든 영구 저장 작업을 job_id, 선택적 name, pid, running 상태, 종료 코드, 시작 시간과 함께 나열합니다.

grep_files

ripgrep 없이 JavaScript 정규식을 사용하여 절대 파일 또는 디렉터리를 재귀적으로 검색합니다. 검색은 node_modules, .git, bin, obj, dist, target을 건너뛰고, 5MiB보다 큰 파일과 바이너리 파일을 무시하며, 결과 제한에서 중지합니다. 매개변수:

• pattern(문자열, 필수): JavaScript 정규식 소스.

• path(문자열, 필수): 절대 파일 또는 디렉터리 경로.

• glob(문자열, 선택): *와 ?를 사용하는 간단한 파일 이름 필터.

• case_sensitive(부울, 선택): 기본값은 false입니다.

• max_results(정수, 선택): 기본값 200, 최대 1,000.

• context_lines(정수, 선택): 각 일치 항목 앞뒤의 줄 수. 기본값 0, 최대 5.

결과에는 file, line_number, line, before, after가 포함된 matches와 files_scanned, truncated가 포함됩니다. 잘못된 정규식은 MCP 도구 오류를 반환합니다.

job_wait

기존 분리 작업이 종료될 때까지 대기하며, 500ms마다 영구 저장된 종료 마커를 폴링합니다. 매개변수:

• job_id(문자열, 필수): job_start가 반환한 ID.

• timeout_ms(정수, 선택): 기본값 60,000, 최대 600,000.

• tail_lines(정수, 선택): 기본값 40, 최대 1,000.

결과는 job_status와 동일한 필드를 가지며 timed_out이 추가됩니다. 작업이 아직 실행 중일 때 마감 시간이 되면 MCP 오류가 아닌 timed_out: true가 포함된 정상 결과입니다.

lock_acquire 및 lock_release

%LOCALAPPDATA%/director-shell-mcp/locks/ 아래에 영구 저장되는 에이전트 간 명명된 뮤텍스를 제공합니다. 이름에는 문자, 숫자, _, ., -만 포함될 수 있으며 최대 64자입니다. lock_acquire는 name(필수), wait_ms(선택, 기본값 0, 최대 600,000), 선택적 note를 받습니다. name, UUID token, acquired_at을 반환합니다. 획득은 원자적 디렉터리 생성을 사용하며 기록된 소유자 프로세스가 더 이상 살아 있지 않은 잠금을 복구합니다. 보류 중인 잠금 오류는 해당 pid, note(있는 경우), 지속 시간을 식별합니다. lock_release는 name과 소유자 token을 받습니다. 잘못된 토큰과 해제된 잠금은 오류이며 잠금을 변경하지 않습니다.

screenshot

Windows에서 System.Drawing과 Windows API를 사용하여 전체 가상 화면 또는 보이는 최상위 창을 PNG로 캡처합니다. 매개변수:

• target(screen 또는 window, 선택): 기본값은 screen입니다.

• window_title(문자열, window에 필수): 대소문자를 구분하지 않는 보이는 창 제목 부분 문자열.

• output_path(절대 .png, 선택): 기본값은 임시 출력 디렉터리의 타임스탬프 파일입니다.

결과에는 path, width, height, target, 창 캡처의 경우 일치한 window_title이 포함됩니다. Windows가 아닌 시스템에서는 명확한 미지원 오류를, 요청한 창을 찾을 수 없을 때는 명확한 불일치 오류를 반환합니다.

process_list

Windows에서 읽기 전용 프로세스 목록을 반환합니다. 매개변수:

• name_filter(문자열, 선택): 프로세스 이름 또는 실행 파일 경로의 대소문자를 구분하지 않는 부분 문자열.

• max_results(정수, 선택): 기본값 100, 최대 1,000.

각 프로세스에는 pid와 name이 포함되며, 사용 가능한 경우 path, started_at, working_set_bytes도 포함됩니다. 결과에는 truncated도 포함됩니다.

file_lockers

Restart Manager API를 통해 Windows에서 기존 파일을 열고 있는 프로세스를 보고합니다. path(필수)를 받으며, 이는 기존 파일의 절대 경로여야 하며 { path, lockers }를 반환합니다. 각 locker에는 pid, app_name, app_type이 포함됩니다. 잠기지 않은 파일은 빈 lockers 배열이 포함된 성공 결과입니다. Windows가 아닌 시스템에서는 명확한 미지원 오류를 반환합니다.

검증

가벼운 엔드투엔드 스모크 테스트를 실행합니다(echo와 PowerShell sleep만 사용):

npm run smoke

스모크 테스트는 stdio를 통해 새 MCP 서버를 시작하고, 초기화를 수행하고, 15개 도구를 모두 나열하고, 파일 쓰기, 정확한 텍스트 편집, Python 실행 및 인수 전달, 명령 완료 및 출력 캡처를 실행하고, 실행 중 및 종료 후 분리 작업을 검증하고, grep, wait, 잠금, 스크린샷, 프로세스 목록, Restart Manager 파일 잠금 감지를 실행하고, job_list를 통한 영속성을 확인하고, 명령 시간 초과 처리를 검증합니다.

라이선스

MIT