mcp-context-window

로컬 모델에 외부 컨텍스트 버퍼를 제공하는 MCP 서버입니다. 모델이 메모를 기록할 수 있는 지속적인 세션 메모리와, 전체를 로드하지 않고 페이지 단위로 읽을 수 있는 대용량 문서를 제공합니다.

MCP TypeScript SDK v2를 기반으로 2026-07-28 프로토콜 개정판에 맞춰 제작되었습니다. stdio(LM Studio, Claude Desktop, 로컬 프로세스를 실행하는 모든 호스트) 또는 Streamable HTTP를 통해 실행됩니다.

먼저 읽어보세요: MCP 서버가 할 수 있는 것과 할 수 없는 것

어떤 MCP 서버도 컨텍스트 창을 보거나 수정할 수 없습니다. MCP는 엄격한 요청/응답 방식입니다. 호스트가 도구를 호출하면 도구가 응답합니다. 서버는 대화를 볼 수 없고, 모델에 도달하기 전에 메시지를 가로챌 수 없으며, 어떤 것도 잘라낼 수 없습니다. LM Studio는 자체적으로 내부 트렁케이션을 수행하며 이에 대해 어떤 서버와도 상의하지 않습니다.

따라서 이것은 자동 슬라이딩 윈도우가 아니며, 그렇게 광고하는 것은 오해를 불러일으키는 것입니다. 이것이 실제로 하는 일은: 모델이 의도적으로 페이지를 넘겨가며 사용하는 저장소로, 자료의 대부분을 창 밖에 두고 필요한 것만 다시 가져오는 것입니다. 이는 8k 토큰 로컬 모델에서 진정으로 강력합니다. 하지만 모델이 호출하기 때문에 작동하는 것이지, 무엇인가를 가로채기 때문이 아닙니다.

실질적인 결과: 모델이 협조해야 합니다. 여기의 도구 설명은 규범적으로 작성되었으며, context_guide는 의도된 워크플로우를 반환합니다. 모델이 이를 무시한다면 시스템 프롬프트에 명시하세요.

관련 참고 사항: MCP 샘플링 — 서버가 클라이언트의 LLM에 텍스트 생성을 요청하는 메커니즘 — 은 2026-07-28 사양에서 더 이상 사용되지 않으며, 공식 권장 사항은 "LLM 제공자 API와 직접 통합하라"입니다. 따라서 이 서버는 자체적으로 OpenAI 호환 엔드포인트를 호출합니다. 이것이 또한 하네스에 구애받지 않게 하는 이유입니다. 동일한 코드가 LM Studio, Ollama, llama.cpp 또는 vLLM에서 작동합니다.

Related MCP server: membot

두 가지 구성 요소

세션 — 긴 작업 중 작업 메모리

문서 — 한 번에 읽기에는 너무 큰 자료

추가로 context_guide는 모델에게 워크플로우를 설명합니다.

빠른 시작

npm install
npm run build
npm test

node dist/index.js --ingest-root ./sources

또는 대화형으로 탐색하세요:

npx @modelcontextprotocol/inspector node dist/index.js

LM Studio

~/.lmstudio/mcp.json(Windows에서는 C:\Users\<you>\.lmstudio\mcp.json)을 Program → Install → Edit mcp.json을 통해 편집한 후 LM Studio를 다시 로드하세요.

{
  "mcpServers": {
    "context": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-context-sliding/dist/index.js",
        "--ingest-root", "/absolute/path/to/your/project",
        "--budget", "4000"
      ]
    }
  }
}

이 두 경로는 절대 경로여야 합니다. 호스트는 서버를 예측할 수 없는 작업 디렉토리로 자식 프로세스로 실행하므로 상대 경로는 해석되지 않습니다. 명령줄에서 작업 디렉토리를 제어하는 경우 --ingest-root ./sources와 같은 상대 경로는 괜찮습니다.

Windows에서는 슬래시(C:/Users/you/projects)를 쓰거나 백슬래시를 두 번 쓰세요. JSON 문자열에서 단일 \는 이스케이프 문자이기 때문입니다.

--budget을 모델의 컨텍스트 길이의 약 절반으로 설정하세요. 이것은 이 서버가 회상을 압축하는 대상이며, LM Studio가 강제하는 제한이 아닙니다.

--ingest-root는 doc_ingest가 파일을 읽을 수 있게 하는 것입니다. 이를 생략하면 서버는 인라인 텍스트만 허용합니다. 이는 안전한 기본값입니다. 모델의 지시에 따라 임의의 경로를 여는 서버는 위험 요소이기 때문입니다.

Docker

docker build -t mcp-context-window:latest .

{
  "mcpServers": {
    "context": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-v", "mcp-context-data:/data",
        "-v", "/absolute/path/to/your/project:/ingest:ro",
        "-e", "CTX_INGEST_ROOTS=/ingest",
        "--add-host", "host.docker.internal:host-gateway",
        "mcp-context-window:latest", "--stdio"
      ]
    }
  }
}

여기서 문제가 되는 두 가지: -i는 필수이며, 그렇지 않으면 JSON-RPC 핸드셰이크가 발생하지 않습니다. 그리고 명명된 볼륨은 필수이며, 그렇지 않으면 재시작할 때마다 저장된 모든 세션이 조용히 삭제됩니다. 컨테이너 내부에서 localhost는 컨테이너 자체이므로 LLM 기본 URL은 host.docker.internal로 기본 설정됩니다. Docker는 또한 -v 바인드 마운트의 호스트 측이 절대 경로여야 합니다.

세션이 실제로 진행되는 방식

context_open        session_id "refactor-auth"
context_append      "Goal: replace session cookies with JWT" (pinned)
context_append      "auth/middleware.ts:42 assumes a cookie is present"
context_append      "Decision: keep cookie support behind a flag for one release"
...
context_status      → 3200/4000 tokens — approaching budget
context_compact     → folds 14 old entries into one 380-token summary
context_recall      "cookie flag decision" → returns the pinned goal + the decision

그리고 문서:

doc_ingest      file_path "logs/build-failure.log"  → doc_kx91, 240 chunks
doc_search      "OutOfMemory"                       → 3 chunks, 1400 tokens
doc_window      from 118 to 121                     → the surrounding context

로그는 모델의 컨텍스트에 들어가지 않았습니다. 세 번의 대상 읽기만 수행되었습니다.

구성

설계 노트

토큰 계산은 실제 모델에 맞게 보정됩니다. 보편적인 토크나이저는 없습니다. Llama, Qwen, GPT는 모두 다르게 분할하며, 하나를 번들로 포함하면 크고 로드한 모델에 대해 틀릴 것입니다. 대신 서버는 저렴하게 추정한 다음 실제를 측정합니다. 서로 다른 길이의 두 샘플을 max_tokens: 1로 엔드포인트에 보내고 보고된 usage.prompt_tokens 사이의 기울기를 취합니다. 기울기는 채팅 템플릿의 고정 오버헤드를 상쇄하고 문자당 실제 한계 비용을 제공합니다. 결과는 캐시되므로 첫 실행만 보정되지 않으며, 백그라운드에서 실행되므로 아직 로드되지 않은 모델로 인해 시작이 차단되지 않습니다.

추정치는 의도적으로 높게 잡습니다. 과소 계산은 창을 넘치게 하고 이 서버가 보호하기 위해 존재하는 컨텍스트를 잘라냅니다.

요약은 실패하는 대신 성능이 저하됩니다. 엔드포인트에 연결할 수 없거나 모델이 로드되지 않은 경우 TF-ISF 문장 점수 기반의 추출적 요약으로 대체됩니다. 이는 즉각적이고 결정적이며 구조적으로 환각을 일으킬 수 없습니다. 저장된 컨텍스트에 대한 접근을 잃는 것은 더 조잡한 요약보다 더 나쁜 결과입니다. 실패 후 클라이언트는 잠시 백오프하므로 200개 청크 문서가 200개의 개별 TCP 시간 초과를 기다리지 않습니다.

저장은 추가 전용 JSONL입니다. 충돌은 최대 마지막 줄만 손상시킬 수 있으며, 로드 시 치명적이지 않고 건너뜁니다. tail로 파일을 보면서 메모리가 축적되는 것을 관찰할 수 있습니다. 압축은 원본을 삭제하는 대신 대체된 것으로 표시하므로 중요한 것을 놓친 압축도 로그에서 복구할 수 있습니다.

청크는 고정 오프셋이 아닌 문서 구조를 따릅니다. 제목, 단락, 펜스 코드 블록이 그대로 유지되며 각 청크는 그 아래에 있는 제목 경로를 포함합니다. 청크 전체보다 실제로 큰 블록만 강제 분할됩니다.

검색은 BM25와 최신성 기반이며 임베딩 모델이 없습니다. 이는 아무것도 로드할 필요가 없고, 메인 모델과 함께 VRAM을 소모하지 않으며, 결정적입니다. 모델이 보는 것에 대한 예측 가능성이 핵심일 때 중요합니다. 식별자는 전체 및 분할로 인덱싱되므로 getUserName은 "user name"으로 찾을 수 있습니다.

제한 사항

• 모델이 실제로 이러한 도구를 호출해야 합니다. 자동으로 되는 것은 없습니다.

• 키워드 검색은 임베딩 모델이 잡을 의역을 놓칩니다.

• 토큰 수는 첫 번째 보정이 성공할 때까지 추정치입니다.

• 두 전송 모두 인증하지 않습니다. HTTP는 그 이유로 루프백에 바인딩됩니다.

• doc_ingest는 UTF-8 텍스트를 읽습니다. PDF 또는 DOCX 추출기가 아닙니다.

라이선스

MIT