MCP 도구

업스트림 MCP 도구를 투명하게 프록시하는 것 외에도, memtomem-stm은 프록시를 관찰·제어하기 위한 12개 관리 도구를 제공합니다. 모델용 도구 4개는 기본 노출되며, 관찰 도구 8개는 MCP 노출 opt-in입니다.

관찰 도구 노출 제어

12개 중 8개는 관찰(observability) 도구이며, 에이전트 컨텍스트를 아끼기 위해 기본적으로 MCP 도구 목록에서 숨겨집니다. MCP 클라이언트 설정의 env에 MEMTOMEM_STM_ADVERTISE_OBSERVABILITY_TOOLS=true를 지정하면 관찰 도구가 tools/list에 노출됩니다. 파이썬 테스트나 내부 코드에서는 어느 쪽이든 호출 가능합니다.

범주	항상 노출	플래그 on일 때 노출
항상 on	`stm_proxy_select_chunks`, `stm_proxy_read_more`, `stm_surfacing_feedback`, `stm_compression_feedback`	—
관찰	—	`stm_proxy_stats`, `stm_proxy_health`, `stm_proxy_cache_clear`, `stm_surfacing_stats`, `stm_index_stats`, `stm_compression_stats`, `stm_progressive_stats`, `stm_tuning_recommendations`

프록시 통계 및 제어

`stm_proxy_stats`

토큰 절감, 캐시 히트, 도구별 호출 이력.

파라미터 없음. (관찰 — advertise_observability_tools=true일 때만 MCP에 노출.)

`stm_proxy_health`

업스트림 연결 상태와 서킷 브레이커 상태.

파라미터 없음. (관찰.)

`stm_proxy_cache_clear`

응답 캐시 비우기.

파라미터	타입	필수	설명
`server`	string	아니오	특정 업스트림 범위로 제한
`tool`	string	아니오	특정 도구 범위로 제한

(관찰.)

`stm_proxy_select_chunks`

이전 호출에서 받은 selective / hybrid TOC 중 특정 섹션을 선택합니다.

파라미터	타입	필수	설명
`key`	string	예	이전 응답의 TOC 키
`sections`	string[]	예	확장할 섹션 id

`stm_proxy_read_more`

progressive 응답의 다음 청크를 읽습니다.

파라미터	타입	필수	설명
`key`	string	예	Progressive 응답 키
`offset`	integer	예	재개할 바이트 오프셋
`limit`	integer	아니오	이번 턴에 반환할 문자 수

에이전트는 \n---\n 단독이 아닌 정식 PROGRESSIVE_FOOTER_TOKEN(\n---\n[progressive: chars=)으로 분할해야 합니다. 단순 \n---\n는 Markdown HR·YAML 펜스와 충돌합니다.

서피싱 피드백

`stm_surfacing_feedback`

자동 튜너가 임계값을 조정할 수 있도록 서피싱된 기억을 평가합니다.

파라미터	타입	필수	설명
`surfacing_id`	string	예	서피싱 푸터에서 얻은 id
`rating`	string	예	`helpful` / `partially_helpful` / `not_relevant` / `already_known`
`memory_id`	string	아니오	피드백 대상 개별 기억
`ratings`	object[]	아니오	`memory_id`와 `rating`을 가진 per-memory batch 피드백

`stm_surfacing_stats`

서피싱 지표와 피드백 분포를 집계합니다. events_total, distinct_tools, total_feedback, 도구별 분해, rating 분포, helpfulness %, 최근 꼬리 목록을 보고합니다.

파라미터	타입	필수	설명
`tool`	string	아니오	업스트림 도구 이름으로 필터
`since`	string	아니오	ISO-8601 타임스탬프(예: `2026-04-20T00:00:00`) 이후 이벤트만 포함
`limit`	integer	아니오	`Recent` 섹션 꼬리 크기 (기본 `10`, `0`은 숨김)

(관찰.)

인덱싱 통계

`stm_index_stats`

자동 인덱싱과 추출 경로를 통한 STM 기반 LTM 쓰기 통계.

파라미터	타입	필수	설명
`tool`	string	아니오	업스트림 도구 이름으로 필터

(관찰.)

압축 피드백

`stm_compression_feedback`

압축이 누락한 정보를 보고합니다.

파라미터	타입	필수	설명
`server`	string	예	업스트림 서버
`tool`	string	예	도구 이름
`missing`	string	예	에이전트가 필요했으나 받지 못한 내용
`kind`	string	아니오	범주 힌트
`trace_id`	string	아니오	Langfuse 등 트레이스 id

`stm_compression_stats`

도구별 압축 피드백 집계.

파라미터	타입	필수	설명
`tool`	string	아니오	도구 이름으로 필터

(관찰.)

점진적 전달 통계

`stm_progressive_stats`

Progressive 압축을 거친 호출의 응답별 후속 읽기 비율과 커버리지를 집계합니다. 초기 청크와 이어지는 각 stm_proxy_read_more은 progressive_reads 테이블의 한 행으로 기록되며, 캐시 키 단위로 모읍니다 — 후속 5회 응답과 후속 없음 응답의 가중치가 동일합니다. total reads, total responses, follow-up rate, avg chars served, avg total chars, avg coverage, 도구별 분해를 보고합니다.

파라미터	타입	필수	설명
`tool`	string	아니오	업스트림 도구 이름으로 필터

(관찰 — advertise_observability_tools=true일 때만 MCP에 노출.)

INDEX 쓰기 통계

`stm_index_stats`

STM이 LTM에 쓴 활동 통계 — 두 INDEX 경로(auto_index_response = 응답 verbatim 청킹, extract_and_store = LLM 사실 추출 후 청킹)를 함께 다룹니다. SURFACE 경로의 stm_surfacing_stats와 대칭이지만 INDEX는 의도적으로 품질 시그널을 두지 않습니다 — 운영자가 보는 값은 attempts(경로별 시도 수)와 outcomes(stored / error / dedup_skip / extracted_zero_facts) 분포뿐입니다.

현재 standalone mms 서버에서는 Stage 4 INDEX 설정이 유효한 설정이지만, 시작 시 FileIndexer 엔진이 연결되지 않아 inert 상태입니다. 이 카운터는 라이브러리 통합과 향후 서버 연결에서 의미가 있으며, 지금 stm_proxy.json에서 auto_index를 켠다고 standalone 서버가 LTM으로 write-back하지는 않습니다.

파라미터	타입	필수	설명
`tool`	string	아니오	업스트림 도구 이름으로 필터 — `__total__` 행은 항상 포함

(관찰 — advertise_observability_tools=true일 때만 MCP에 노출.)

`stm_tuning_recommendations`

최근 피드백을 근거로 한 도구별 자동 튜너 권고.

파라미터	타입	필수	설명
`since_hours`	number	아니오	시간 창 (기본 `24.0`)
`tool`	string	아니오	도구 이름으로 필터

(관찰.)

프록시되는 업스트림 도구

등록된 업스트림 MCP 서버의 모든 도구는 {prefix}__{tool} 패턴으로 STM을 통해 프록시됩니다. 예:

mms add filesystem --command npx \
  --args "-y @modelcontextprotocol/server-filesystem ~/projects" \
  --prefix fs
# filesystem의 read_file 은 fs__read_file 이 됩니다

MCP 도구 선택 UI(예: Claude Code의 /mcp)에서 렌더링되는 프록시 도구의 제목(annotations.title 필드)에는 출처를 나타내도록 [{server}] 접두사가 자동으로 붙습니다. 예를 들어 filesystem 서버의 Read file 도구는 [filesystem] Read file 로 표시됩니다. 이는 도구를 호출할 때 사용하는 {prefix}__{tool} 이름과는 별개이며, 업스트림 도구가 이미 annotations.title 을 제공하는 경우에만 적용됩니다.

에이전트가 fs__read_file을 호출하면 프록시는 활성 파이프라인인 CLEAN → COMPRESS → SURFACE를 실행하며, INDEX는 index engine이 연결된 경우에만 동작합니다. 반환값은 압축된 응답 + 서피싱된 기억입니다.

메커니즘은 능동적 서피싱과 압축 전략을 참조하세요.