scratchpad-mcp

AI 에이전트를 위한 지속적이고 토큰 효율적인 저장소입니다. 에이전트가 매번 동일한 파일을 다시 읽고 동일한 컨텍스트를 다시 로드하는 것을 방지하는 MCP 서버입니다.

agent: "what changed in this file since I last read it?"
server: { diff: [...], current_version: 14 }   ← not the whole file

목적

에이전트는 토큰을 낭비합니다. 이미 본 파일을 다시 읽고, 이미 처리한 문서를 다시 요약하며, 이미 계산한 상태를 다시 발견합니다. 이 서버는 에이전트가 그러한 작업 결과를 저장하고 나중에 모델이 저렴하게 추론할 수 있는 방식으로 다시 가져올 수 있는 공간을 제공합니다.

구체적으로:

• 버전 관리 쓰기: 에이전트가 작업 문서를 저장하고 "마지막으로 본 이후 무엇이 변경되었는가?"라고 물으면, 서버는 전체 내용 대신 구조화된 차이점(diff)을 반환합니다.

• 추가 전용 로그: 커서 기반 페이지네이션을 지원하여 에이전트가 자신의 작업 기록을 기록하고 효율적으로 재생할 수 있습니다.

• 온디맨드 요약: 긴 파일(예상 토큰 2000개 이상)에 대해 Claude Haiku로 생성되며 파일 버전별로 캐싱되므로, 동일한 요약 호출은 무료입니다.

• 에이전트별 네임스페이스: 하나의 서버 인스턴스가 상태를 공유하지 않고 여러 에이전트를 서비스할 수 있습니다.

도구

모든 도구는 첫 번째 인수로 agent_id를 받습니다. 작업은 해당 에이전트로 범위가 제한되며, 에이전트는 서로의 파일이나 로그를 읽을 수 없습니다.

차이점(Diff) 형식

since_version과 함께 read_file을 호출하면 청크의 JSON 배열이 반환됩니다:

{
  "diff": [
    { "op": "equal",  "lines": ["line that didn't change"] },
    { "op": "remove", "lines": ["line that was deleted"] },
    { "op": "add",    "lines": ["line that was added"] }
  ]
}

라인 단위의 차이점 분석은 의도적인 것입니다. 이는 에이전트가 가장 안정적으로 처리할 수 있는 형식이며, 에이전트가 전체 파일을 다시 처리하는 대신 무엇이 변경되었는지 추론할 수 있게 합니다.

경로 규칙

경로는 [a-zA-Z0-9/_.-]+와 일치해야 하며, 최대 255자, 선행 / 없음, .. 시퀀스 금지 규칙을 따라야 합니다. 오류 발생 시 위반된 규칙이 명시됩니다.

제한 사항

• 파일 쓰기당 1MB

• 로그 항목당 64KB

• 파일당 10개 버전 유지(오래된 버전은 자동으로 삭제)

• read_log 페이지당 100개 로그 항목

설치

Node 20 이상과 Anthropic API 키(summarize_file용)가 필요합니다.

git clone <this repo>
cd scratchpad-mcp
npm install
npm run build

이 명령을 실행하면 실행 가능한 서버인 dist/index.js가 생성됩니다.

Claude Desktop 설정

%APPDATA%\Claude\claude_desktop_config.json(Windows) 또는 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)에 추가하세요:

{
  "mcpServers": {
    "scratchpad": {
      "command": "node",
      "args": ["C:\\path\\to\\scratchpad-mcp\\dist\\index.js"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

ANTHROPIC_API_KEY는 summarize_file을 호출하려는 경우에만 필요합니다. 나머지 7개 도구는 키 없이도 작동합니다.

선택 사항: SCRATCHPAD_DB_PATH를 설정하여 SQLite 위치를 변경할 수 있습니다. 기본값은 프로젝트 루트의 scratchpad.db입니다.

Claude Desktop을 재시작하세요. 서버가 8개의 도구와 함께 MCP 서버 목록에 나타나야 합니다.

보안 모델 — 호스팅 전 필독

agent_id는 일반 텍스트 도구 매개변수입니다. 인증이 없으므로 호출자는 누구든 agent_id를 주장할 수 있으며 서버는 이를 신뢰합니다. 이는 V1을 위해 의도된 것이며 다음과 같은 배포 형태에 적합합니다:

• 서버 프로세스당 사용자 1명. 에이전트와 SQLite 파일은 신뢰 경계를 공유합니다. 예: Claude Desktop 설치, Smithery 로컬 설치, 사용자별 Apify Actor 실행(기본적으로 실행당 새로운 컨테이너와 새로운 데이터베이스 파일 생성).

다음 경우에는 안전하지 않습니다:

• 다중 테넌트 대기 모드. 하나의 서버 프로세스가 동일한 SQLite 파일을 읽고 쓰는 여러 신뢰할 수 없는 호출자를 서비스하는 경우. 누구나 다른 호출자의 agent_id를 전달하여 데이터를 읽거나 덮어쓸 수 있습니다.

다중 테넌트를 원한다면 래퍼 계층에서 호출자의 API 키로부터 agent_id를 파생시키거나(V2 계획), 테넌트당 하나의 프로세스를 실행하세요.

적용된 심층 방어 조치

• 모든 SQL은 매개변수화되어 있어 경로, agent_id, 접두사를 통한 주입이 불가능합니다.

• 경로 유효성 검사는 .., 선행 /, 공백 및 [a-zA-Z0-9/_.-] 이외의 모든 문자를 거부합니다.

• list_files 접두사 일치는 SUBSTR 동등성(LIKE가 아님)을 사용하므로 SQL 와일드카드 _ 및 %가 적용되지 않으며 대소문자를 구분합니다.

• 호출당 크기 제한(파일당 1MB, 로그 항목당 64KB).

• 에이전트별 할당량(1000개 파일, 10만 개 로그 항목, 총 100MB)을 두어 폭주하는 에이전트가 호스팅 환경의 공유 디스크를 고갈시키지 않도록 합니다.

• 오류는 err.message만 반환하며 스택 추적, SQLite 경로, API 키는 포함하지 않습니다.

summarize_file 비용은 누가 부담하나요?

항상 호출자가 부담합니다.

• 로컬 설치(Smithery, Claude Desktop, mcp.so): 사용자가 자신의 설정에 ANTHROPIC_API_KEY를 제공합니다. 자신의 기기, 자신의 키, 자신의 비용입니다.

• Apify 호스팅: 모든 Actor 실행은 실행당 입력에서 anthropicApiKey를 읽습니다. .actor/entrypoint.sh 런처가 서버를 시작하기 전에 이를 환경 변수에 매핑합니다. 각 호출자는 자신의 요약에 대해 Anthropic에 비용을 지불하며, Actor 게시자는 Apify의 호출당 수수료만 수취합니다.

이 프로젝트를 포크하여 호스팅하려는 경우, Dockerfile, Apify Actor 환경 또는 공개적으로 배포되는 설정 파일에 API 키를 하드코딩하지 마십시오. 나머지 7개 도구는 키 없이 작동하므로 키를 설정하지 않는 것이 안전한 기본값입니다.

저장소 작동 방식

단일 SQLite 파일이 모든 것을 보관합니다:

• files — (agent_id, path)당 한 행, 현재 버전을 추적합니다.

• file_versions — 버전별 전체 내용, 파일당 최근 10개로 제한됩니다. 삭제는 write_file마다 발생합니다.

• log_entries — 추가 전용 항목, 수정되지 않습니다.

• summaries — 파일별 요약 캐시, 버전 불일치 시 무효화됩니다.

• agent_usage — get_usage_stats를 위한 에이전트별 작업 카운터.

버전 관리는 쓰기가 빨라야 하고 읽기가 명확해야 하므로 버전별로 전체 내용을 저장합니다(델타가 아님). 차이점은 두 버전을 라인 단위로 비교하여 읽을 때 계산됩니다. 비용은 차이점을 요청하는 호출자가 부담하며, 모든 작성자가 부담하는 것이 아닙니다.

로드맵

• [ ] 호출당 과금을 위한 Apify 패키징.

• [ ] 매개변수로 받는 대신 API 키에서 agent_id 파생.

• [ ] Postgres 백엔드(SQLite 스키마는 이식 가능하므로 연결 교체 작업입니다).

• [ ] 에이전트별 속도 제한.

• [ ] 작업 가시성을 위한 구조화된 로깅.

라이선스

MIT — LICENSE를 참조하세요.