Cursor 에이전트 모드를 활용해 복잡한 개발 작업을 수행할 때 세션이 길어질수록 컨텍스트 토큰 소비와 도구 호출 결과 누적으로 인한 부담이 커집니다. context-mode는 이러한 컨텍스트 낭비를 줄이고 도구 실행을 최적화하도록 돕는 CLI 도구이자 라이프사이클 관리 도구입니다.
현재 context-mode의 Cursor 마켓플레이스 플러그인은 심사 진행 중입니다. 따라서 마켓플레이스 원클릭 등록을 이용할 수 없는 환경에서는 글로벌 패키지를 설치한 뒤 MCP(Model Context Protocol) 설정과 라이프사이클 훅(hooks.json), 라우팅 규칙(rules)을 수동으로 구성해야 합니다.
Cursor 플러그인과 MCP는 서로 다른 개념입니다. MCP 서버는 Cursor 플러그인 시스템과 별개로 프로젝트의 설정 파일을 통해 독립적으로 구성할 수 있습니다. Node.js 환경에서 context-mode를 전역에 설치하고, .cursor/mcp.json, .cursor/hooks.json, .cursor/rules 파일을 정확히 배치해 정상 동작을 검증하는 전체 절차를 살펴보겠습니다.
사전 요구사항 점검과 context-mode 전역 패키지 설치
수동 연동을 진행하기 전에 로컬 개발 환경이 context-mode 실행 요건을 충족하는지 확인해야 합니다. 공식 저장소에서 요구하는 기본 런타임 및 IDE 조건은 다음과 같습니다.
- Node.js 런타임: Node.js 22.5 이상 버전 또는 Bun 런타임 환경이 설치되어 있어야 합니다.
- Cursor IDE: 에이전트 모드(Agent mode)를 지원하는 Cursor 실행 환경이 필요합니다.
시스템에 최신 Node.js 환경이 준비되었다면 터미널을 열고 다음 명령어를 실행하여 context-mode 패키지를 전역으로 설치합니다.
npm install -g context-mode전역 설치가 완료되면 시스템 터미널 어디서나 context-mode 바이너리를 직접 호출할 수 있는 상태가 됩니다.
mcp.json 구성을 통한 MCP 서버 수동 등록
Cursor 플러그인과 MCP 서버는 동작 영역이 구분된 기술입니다. 플러그인이 MCP 서버를 감싸서 배포될 수도 있지만, MCP 서버 자체는 플러그인 없이도 JSON 설정 파일을 통해 독립적으로 구동할 수 있습니다. context-mode는 표준 MCP 인터페이스를 제공하므로 Cursor의 MCP 설정에 바로 등록할 수 있습니다.
연동 범위에 따라 현재 작업 중인 프로젝트의 루트 경로에 .cursor/mcp.json 파일을 생성하거나, 시스템 전체 세션에 일괄 적용하려면 사용자 홈 디렉터리에 ~/.cursor/mcp.json 파일을 생성합니다. 파일 안에 아래와 같이 mcpServers 설정을 작성합니다.
{
"mcpServers": {
"context-mode": {
"command": "context-mode"
}
}
}이 설정은 Cursor 에이전트가 구동될 때 context-mode CLI를 로컬 프로세스 기반의 MCP 서버로 직접 실행하여 도구 목록을 가져오도록 지정합니다.
hooks.json 생명주기 훅 설정과 rules 파일 배치
에이전트가 도구를 호출하기 전후의 문맥을 context-mode가 직접 가로채서 관리하려면 라이프사이클 훅이 등록되어야 합니다. 이 수동 구성에서는 세션 시작 시 지침을 주입하는 훅에 의존하지 않고, 에이전트가 context-mode를 인지하고 라우팅할 수 있도록 별도의 규칙(rules) 파일을 배치합니다.
먼저 프로젝트 루트의 .cursor/hooks.json(또는 전역 ~/.cursor/hooks.json) 파일에 아래 JSON 내용을 작성합니다.
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "context-mode hook cursor pretooluse",
"matcher": "Shell|Read|Grep|WebFetch|Task|MCP:ctx_execute|MCP:ctx_execute_file|MCP:ctx_batch_execute"
}
],
"postToolUse": [
{
"command": "context-mode hook cursor posttooluse"
}
],
"stop": [
{
"command": "context-mode hook cursor stop"
}
]
}
}설정 항목 중 preToolUse의 matcher는 선택 사항입니다. 공식 가이드에 명시된 대로 matcher를 지정하지 않으면 에이전트가 실행하는 모든 도구 호출에 대해 훅이 발동됩니다. stop 훅은 에이전트의 턴이 끝날 때 실행되며 필요 시 추가 메시지를 전달해 루프를 이어갈 수 있도록 돕습니다.
다음으로 라우팅 규칙 파일을 배치합니다. 터미널에서 다음 명령어를 실행하여 rules 디렉터리를 만들고 설정 파일을 복사합니다.
mkdir -p .cursor/rules
cp "$(npm root -g)/context-mode/configs/cursor/context-mode.mdc" .cursor/rules/context-mode.mdc위 명령은 macOS 또는 Linux의 Bash 계열 셸 예시입니다. 전역 설치를 사용했으므로 프로젝트 안의 node_modules가 아니라 npm의 전역 패키지 경로에서 규칙 파일을 가져옵니다. 원본 파일을 찾을 수 없다면 설치된 패키지에 해당 파일이 포함되어 있는지 확인하고 공식 저장소의 configs/cursor/context-mode.mdc 파일을 프로젝트의 .cursor/rules 폴더로 복사하세요. 이 복사 예제는 Windows PowerShell 명령이 아니므로 그대로 입력하지 마세요.
주의해야 할 중복 설정 방지 원칙: 저장소를 직접 복제하여 심볼릭 링크나 robocopy로 연동하는 로컬 플러그인(Option A) 경로와 위에서 진행한 수동 설정(Option B) 방식을 동시에 사용해서는 안 됩니다. .cursor/hooks.json에 context-mode 훅이 수동으로 정의된 상태에서 로컬 플러그인까지 활성화되면 이벤트가 두 번씩 발동되며, context-mode doctor 실행 시 중복 훅 실행 경고가 출력됩니다. 반드시 둘 중 하나의 설정 경로만 유지해야 단일 발동(single-fire)이 보장됩니다.
Cursor 재시작 및 연결 상태와 ctx stats 정상 동작 검증
설정 파일과 규칙 배치가 끝났다면 Cursor가 새 구성을 올바르게 인식하는지 단계별로 확인해야 합니다.
- Cursor 재시작: 열려 있는 Cursor 창을 완전히 재시작하거나 에이전트 세션을 새로 시작합니다.
- MCP 연결 상태 점검: Cursor 상단 메뉴나 환경설정의
Settings > MCP메뉴로 이동합니다. 서버 목록 중context-mode항목이 표시되고 상태가connected로 활성화되어 있는지 확인합니다. - 에이전트 도구 정상 동작 확인: Cursor 에이전트 채팅창에
ctx stats를 입력하여 전송합니다. 정상 연동된 경우 context-mode의 현재 상태와 도구 로드 정보, 통계 데이터가 응답으로 반환됩니다.
만약 Settings > MCP에서 연결 상태가 표시되지 않거나 오류가 발생한다면, 터미널 환경 변수 PATH에 context-mode 명령어가 정상 등록되어 있는지, .cursor/mcp.json 및 .cursor/hooks.json의 JSON 문법(쉼표 및 따옴표)이 올바른지 확인해야 합니다. 또한 중복 훅 실행이 의심되는 경우 context-mode doctor를 터미널에서 실행하여 설정 충돌 여부와 오류 로그를 점검하시기 바랍니다.
