Weavatrix Refactor

Weavatrix 생태계의 명시적 소스 쓰기 계층입니다. Core는 읽기 전용으로 유지됩니다.

에이전트가 추측하지 않고도 파일 간 리팩터링을 수행합니다.

Weavatrix Refactor는 코딩 에이전트를 위한 네이티브 MCP 서버입니다. 저장소 그래프를 통해 심볼을 찾고, 바이트 단위로 정확한 편집을 미리 보여 주며, 증명할 수 없는 동일 이름의 모든 발생을 보고하고, 명시적이고 해시로 바인딩된 확인 후에만 쓰기를 수행합니다.

유용한 차이점은 "AI가 단어를 바꿀 수 있다"는 것이 아닙니다. 에이전트가 쓰기 전에 증거를 얻고, 쓰기 후에는 복구 가능한 트랜잭션을 얻는다는 점입니다.

설치

npm을 통해 네이티브 바이너리를 실행합니다:

npx -y weavatrix-refactor mcp /absolute/path/to/repository

또는 Cargo로 설치합니다:

cargo install weavatrix-refactor --locked
weavatrix-refactor mcp /absolute/path/to/repository

MCP 클라이언트가 직접 시작할 수 있습니다:

{
  "mcpServers": {
    "weavatrix-refactor": {
      "command": "weavatrix-refactor",
      "args": ["mcp", "/absolute/path/to/repository"],
      "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
    }
  }
}

미리 보기 전용 세션에서는 WEAVATRIX_ALLOW_SOURCE_EDITS를 설정하지 않은 상태로 두세요. 미리 보기는 읽기입니다. 확인된 적용 또는 롤백만 게이트가 필요합니다.

플러그인으로 설치

이 저장소에는 Cursor, Codex, Claude Code, Grok Build용 플러그인 번들도 포함되어 있습니다. 플러그인은 확장 전용 프로필을 시작하므로 Weavatrix Core의 43개 읽기 전용 메서드 정의를 반복하지 않고 11개의 Refactor 메서드를 제공합니다. 두 표면이 모두 필요하면 별도의 Weavatrix 플러그인을 설치하세요.

번들된 스킬은 선택 사항이며 명시적으로 요청된 리팩터링 작업에서만 활성화됩니다. 진입점은 짧게 유지되며, 각 메서드에는 필요할 때만 로드되는 개별 참조 카드가 있습니다.

• Cursor: 마켓플레이스 승인 후 Weavatrix Refactor를 검색하세요.

• Codex: .agents/plugins에서 Weavatrix/weavatrix-refactor 마켓플레이스를 추가한 다음 weavatrix-refactor@weavatrix-refactor를 추가하세요.

• Claude Code: .claude-plugin에서 동일한 저장소 마켓플레이스를 추가한 다음 weavatrix-refactor@weavatrix-refactor를 설치하세요.

• Grok Build: grok plugin marketplace add Weavatrix/weavatrix-refactor를 실행하고 /marketplace를 열어 설치하세요.

플러그인은 WEAVATRIX_ALLOW_SOURCE_EDITS=1을 열지만, 모든 쓰기에는 여전히 정확한 미리 보기의 단기 유효한 플랜 바인딩 단일 사용 토큰이 필요합니다.

이름 변경 작업의 경우 에이전트가 필요한 두 도구만 노출하세요:

weavatrix-refactor mcp /absolute/path/to/repository --profile=rename

rename 프로필은 rename_symbol과 rollback_last_apply를 유지합니다. 관련 없는 그래프 및 리팩터링 도구는 모두 없으며 호출할 수 없습니다. 옵션을 생략하거나(또는 --profile=refactor 사용) 11개의 Refactor 메서드를 모두 사용하세요. 더 좁은 카탈로그는 반복되는 에이전트 컨텍스트를 줄이지만 미리 보기 해시, 쓰기 게이트, 확인 토큰 또는 롤백 검사를 약화시키지 않습니다.

Weavatrix Core가 별도의 MCP로 이미 설치된 경우 Refactor가 추가하는 11개 메서드만 노출하세요:

weavatrix-refactor mcp /absolute/path/to/repository --profile=refactor

refactor 프로필은 마켓플레이스 플러그인을 포함한 MCP 및 list-tools의 기본값입니다. 이전의 full 호환 프로필은 제거되었으며 두 명령 모두에서 거부됩니다. Refactor는 더 이상 Core 메서드를 다시 게시하지 않습니다. 읽기 전용 저장소 인텔리전스도 필요하면 Weavatrix Core를 자체 MCP로 설치하세요.

Related MCP server: MCP Refactoring

세 번의 호출로 안전한 크로스 파일 이름 변경

두 파일이 resolveTarget을 선언한다고 가정해 보겠습니다. 단순한 이름은 모호하므로 서버는 하나를 선택하기를 거부하고 정확한 ID를 반환합니다:

// rename_symbol
{"symbol":"resolveTarget","new_name":"locateTarget","output_format":"json"}

{
  "status": "NOT_FOUND",
  "reason": "the name matches more than one symbol; pass one of the candidate ids",
  "candidates": [
    "symbol:src/core.ts#function:resolveTarget@2:1",
    "symbol:src/shadow.ts#function:resolveTarget@3:1"
  ]
}

의도한 ID로 다시 시도하세요. 결과는 여전히 읽기 전용입니다. 편집 계획, 콘텐츠 해시, 입증된 편집 횟수, 백엔드가 추측을 거부한 참조가 포함됩니다.

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "output_format": "json"
}

{
  "status": "PLANNED",
  "completeness": "PARTIAL",
  "renamedEdits": 7,
  "uncertainReferences": ["... three named locations ..."],
  "confirmToken": "single-use-token",
  "plan": {"schemaVersion":"weavatrix.edit-plan.v1","files":["..."]}
}

계획을 검토한 후 동일한 입력과 토큰으로 동일한 작업을 반복하세요:

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "mode": "apply",
  "confirm_token": "single-use-token",
  "output_format": "json"
}

{"status":"APPLIED"}

이 정확한 흐름은 실제 stdio MCP 서버에 대해 실행됩니다. 저장소 픽스처는 세 파일에 걸쳐 7개의 편집이 필요하며, 4개의 트랩(더 긴 식별자, 문자열, 주석, 관련 없는 섀도)을 보존하고 여전히 컴파일되어야 합니다. 12/12를 기록합니다.

현재 자동화된 기능

11개의 도구가 모두 동일한 수준의 자동화를 주장하지는 않습니다:

Refactor는 내부적으로 Rust Weavatrix 그래프를 증거로 사용하지만 Core 메서드를 내보내지 않습니다. 읽기 전용 저장소 인텔리전스는 별도의 Weavatrix 플러그인을 설치하세요. Refactor MCP는 정확히 11개의 확장 메서드를 소유합니다. --profile=rename은 선택적인 더 좁은 두 메서드 워크플로입니다.

안전 모델 및 정확한 제한

• 모호한 이름은 첫 번째 일치 항목을 선택하는 대신 후보 ID로 실패합니다.

• PARTIAL은 그래프가 계획의 편집을 증명했지만 다른 의미적 참조가 없다는 것을 증명하지 않았음을 의미합니다. uncertainReferences는 검토가 필요한 위치를 명명합니다.

• 계획의 모든 파일에는 콘텐츠 해시가 포함됩니다. 변경된 작업 트리는 이전 좌표를 적용하는 대신 미리 보기를 오래된 것으로 만듭니다.

• 적용하려면 WEAVATRIX_ALLOW_SOURCE_EDITS=1과 해당 저장소 및 정확히 다시 계산된 계획에 바인딩된 단기 유효한 단일 사용 토큰이 필요합니다.

• rollback_last_apply는 트랜잭션 후 드리프트된 파일을 덮어쓰기를 거부합니다.

• 다중 파일 쓰기는 저널링되고 충돌 복구 가능합니다. 관련 없는 프로세스에 관찰적으로 원자적이지는 않습니다. 다른 프로세스가 중간 파일 시스템 상태를 잠시 관찰할 수 있습니다.

입증된 출처가 있는 편집만 적용됩니다. 어휘 또는 그래프 백엔드는 언어 서버보다 의도적으로 더 보수적이며 전체 컴파일러 의미론의 주장으로 읽혀서는 안 됩니다.

측정된 벤치마크: 서로 다른 계층은 분리 유지

체크인된 2026년 8월 벤치마크는 동등한 적대적 TypeScript, Rust, Python 픽스처를 사용합니다. 각각 7개의 필수 편집, 4개의 트랩, 빌드/테스트 게이트가 있습니다. 프로토콜 실행은 정확한 o200k_base 초기화, 카탈로그, 요청, 응답 토큰을 계산합니다. 에이전트 실행은 고정된 gpt-5.6-sol / 중간 추론으로 Codex CLI가 보고한 실제 누적 사용량을 사용합니다. 바이트 프록시나 추정된 초당 토큰 변환은 사용되지 않습니다.

새로운 이름 변경 전용 프로필은 고정 MCP 컨텍스트를 9,331에서 485 토큰으로 줄이면서 9개의 프로토콜 실행 모두를 12/12로 유지했습니다. 안내된 TypeScript 에이전트 A/B는 다음과 같습니다:

전체 에이전트 매트릭스는 27개의 TypeScript/Rust/Python 실행 모두에서 12/12입니다. 모든 실행은 운영적으로 완료되었고 정화된 편집 채널 감사를 통과했습니다. 결정적 프로토콜 매트릭스는 또한 언어별 Serena 결함을 노출했습니다. 제안된 find_symbol → rename_symbol 흐름은 TypeScript에서 세 번의 실행 모두 7/12를 기록한 반면 Rust와 Python은 통과했습니다. 또한 Rust 매크로 호출과 Python f-string/모듈 수준 호출 증거에 대한 수정을 찾아 구동했습니다.

이 장난감 TypeScript 저장소에서 Naked Codex는 여전히 좁은 프로필보다 빠르고 저렴합니다. Weavatrix의 입증된 가치는 쓰기 전 미리 보기, 명명된 불확실성, 오래된 계획 거부, 명시적 권한 부여, 롤백입니다. 보편적인 소규모 저장소 토큰 승리가 아닙니다.

전체 방법론, 모든 언어 중앙값, 원시 결과 링크 및 제한 사항을 참조하세요.

계약

11개의 Refactor 도구 이름, 스키마 및 결과 상태는 contract/refactor-tools.v1.json에 고정되어 있습니다. 모든 리팩터링 작업은 네이티브 Rust입니다. 호스트는 기본 표면에서 메서드를 내보내지 않고 그래프 증거를 위해 내부적으로 읽기 전용 weavatrix-rust 엔진을 사용합니다.

0.1.x 버전은 JavaScript 엔진을 사용했습니다. 해당 라인은 weavatrix-refactor-js로 계속되며 별도의 상태 디렉터리, 토큰 저장소 및 롤백 저널을 유지합니다.

라이선스

MIT.