@weppy/roblox-mcp 1.0.2 → 1.2.0

package/docs/ja/tools/overview.md

@@ -1,99 +1,259 @@
-# Roblox MCP 機能
+# Roblox MCPツール
 
-AIとRoblox Studioを接続して、さまざまな作業を自動化できます。カテゴリ別にどんなことができるかを紹介します。
+MCPツールの詳細パラメータはMCPツール定義を直接確認してください。
 
-Syncポリシー:
-- Basic: Studio -> Local（片方向）
-- Pro: 双方向Sync + より広い高度機能（バルク操作でAIトークン効率向上）
-
----
-
-## Basic（無料）
-
-### オブジェクト管理
-
-パーツ、モデル、フォルダなどのゲームオブジェクトを作成、複製、削除、移動できます。「赤いパーツを作って」「このモデルを複製して横に置いて」のような作業が可能です。
-
-### プロパティ設定
-
-オブジェクトのサイズ、色、位置、マテリアルなどすべてのプロパティを読み取り、変更できます。複数のプロパティを一度に変更したり、現在の値を基準に相対的に調整することも可能です。
-
-### スクリプト
-
-新しいスクリプトを作成し、既存のコードを読み取り、修正できます。特定の行だけを編集したり、スクリプト内のテキストを検索したり、どのモジュールを参照しているか依存関係を把握することも可能です。
-
-### セレクション
-
-現在選択しているオブジェクトを確認し、選択を変更し、選択をクリアできます。Studioで作業中の対象を理解し制御するために不可欠です。
-
-### 検索
-
-名前やクラス（種類）でゲーム内のオブジェクトを検索できます。
-
-### タグ
-
-オブジェクトにタグを付けたり外したり、特定のタグが付いたオブジェクトを一度に検索できます。同じ種類のオブジェクトをグループで管理するときに便利です。
-
-### カメラ
-
-カメラを特定のオブジェクトや位置に移動できます。作業中のエリアを素早く確認するのに便利です。
-
-### ログ
-
-ゲーム実行中に発生した出力ログとエラーを確認できます。バグの発見と修正に役立ちます。
-
-### 接続
-
-MCPサーバーとRoblox Studioの接続状態と使用量を確認できます。
-
----
-
-## Pro
-
-より強力な機能が必要なら、Proにアップグレードできます。
+関連ドキュメント:
+- [Sync機能詳細ガイド](../sync/overview.md)
 
-### 高度なセレクション
-
-選択したオブジェクトのプロパティやソースコードを含む詳細なコンテキストを確認し、選択階層を探索し、選択にアイテムを追加・削除し、Place情報やゲームサービスを確認できます。高度なワークフローや自動化に便利です。
-
-### 高度なスクリプト
-
-複数のスクリプトの内容を一括で置換したり、Luauコードを即座に実行できます。繰り返しのコード修正や素早いテストに便利です。
-
-### 高度な検索
-
-ファイルツリー全体を探索したり、プロパティやタグでオブジェクトを検索できます。プロジェクト構造を一目で把握し、特定のオブジェクトのすべての子孫や祖先を確認できます。
-
-### 一括操作
-
-数百のオブジェクトを一度に作成、削除、修正、複製できます。マップに木を植えたり、すべてのパーツの色を変えたり、パターンに従ってオブジェクトを配置する大規模な作業を素早く処理します。
-
-### アセット
-
-Roblox Creator Storeから無料モデルを検索してすぐに挿入できます。「中世の城モデルを探して」「武器モデルを入れて」のように会話だけでアセットを追加します。
-
-### 環境設定
-
-照明、空、霧、地形プロパティ、時間帯を自然言語で設定できます。「夕焼けの雰囲気にして」「深夜12時に設定して」のようなリクエストが可能です。
-
-### 状態管理
-
-Workspaceの現在の状態をスナップショットとして保存し、最近の変更やビューポートの状態を確認できます。複雑な作業中に現在の状態を把握するのに役立ちます。
-
-### 空間分析
-
-オブジェクトのサイズと位置を正確に把握し、空きスペースを見つけ、衝突の有無を確認できます。オブジェクトをグリッドに揃えることも可能です。
-
-### レイキャスト
-
-目に見えない光線を飛ばして地形やオブジェクトとの衝突地点を見つけます。地面の位置の検出、オブジェクト配置の可否確認、スポーン位置の検索、移動可能エリアの分析など、ゲームレベルデザインに不可欠な機能です。
-
-### 地形
-
-ブロック、球、円柱、くさびなどさまざまな形状で地形を埋めたり、削ったり、滑らかにできます。マテリアルや色を変更したり、山や川のある自然の地形を手続き的に自動生成することもできます。
-
-### 可視化
-
-エリア、マーカー、ラインなどを画面に表示して、作業中の空間を視覚的に確認できます。デバッグやレベルデザインのレビューに便利です。
-
-👉 [Proアップグレードガイド](../pro-upgrade.md)
+Syncポリシー:
+- Basic: Studio -> Local 片方向同期
+- Pro: 双方向同期 + より広い高度アクション範囲（バルク操作でAIトークン効率向上）
+
+## Query Instances（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `get` | パスでインスタンスプロパティを取得 | Basic |
+| `children` | 直接の子または全子孫を取得 | Basic |
+| `find_child` | 名前とオプションのクラスフィルタで最初の子を検索 | Basic |
+| `find_descendant` | 名前で最初の子孫を検索 | Basic |
+| `wait_for_child` | 子が表示されるまで待機（タイムアウト付き） | Basic |
+| `class_info` | クラス情報と有効なプロパティを取得 | Basic |
+| `search_name` | 名前パターンでインスタンスを検索（ワイルドカード対応） | Basic |
+| `search_class` | クラス名でインスタンスを検索 | Basic |
+| `file_tree` | ルートからファイルツリー構造を取得 | Pro |
+| `project_structure` | プロジェクト全体構造を取得 | Pro |
+| `descendants` | インスタンスの全子孫を取得 | Pro |
+| `ancestors` | インスタンスの全祖先を取得 | Pro |
+| `search_property` | プロパティ値でインスタンスを検索 | Pro |
+| `search_tag` | タグでインスタンスを検索 | Pro |
+
+## Mutate Instances（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `create` | 新しいインスタンスを作成 | Basic |
+| `create_with_props` | 初期プロパティ付きでインスタンスを作成 | Basic |
+| `delete` | インスタンスを削除 | Basic |
+| `clone` | インスタンスを複製 | Basic |
+| `move` | インスタンスを新しい親に移動 | Basic |
+| `rename` | インスタンスの名前を変更 | Basic |
+| `pivot` | ピボット位置またはCFrameを設定 | Basic |
+| `create_tree` | 階層的インスタンスツリーを作成 | Pro |
+| `mass_create` | 複数のインスタンスを一括作成 | Pro |
+| `mass_delete` | 複数のインスタンスを削除 | Pro |
+| `mass_duplicate` | 複数のインスタンスを複製 | Pro |
+| `smart_duplicate` | 間隔と個数を指定して複製 | Pro |
+
+## Manage Properties（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `get` | 単一プロパティ値を取得 | Basic |
+| `set` | 単一プロパティ値を設定 | Basic |
+| `get_all` | インスタンスの全プロパティを取得 | Basic |
+| `set_multiple` | 複数プロパティを一括設定 | Basic |
+| `get_attr` | アトリビュート値を取得 | Basic |
+| `set_attr` | アトリビュート値を設定 | Basic |
+| `get_all_attrs` | 全アトリビュートを取得 | Basic |
+| `delete_attr` | アトリビュートを削除 | Basic |
+| `add_tag` | インスタンスにタグを追加 | Basic |
+| `remove_tag` | インスタンスからタグを削除 | Basic |
+| `check_tag` | インスタンスがタグを持っているか確認 | Basic |
+| `get_tags` | インスタンスの全タグを取得 | Basic |
+| `get_tagged` | 特定タグを持つ全インスタンスを取得 | Basic |
+| `set_calculated` | 数式を使ってプロパティを設定 | Pro |
+| `set_relative` | 現在値を基準に相対的にプロパティを設定 | Pro |
+| `mass_set` | 複数インスタンスにプロパティを設定 | Pro |
+| `mass_get` | 複数インスタンスからプロパティを取得 | Pro |
+| `modify_children` | 親の全子を修正 | Pro |
+
+## Manage Scripts（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `get_source` | スクリプトソースコードを取得 | Basic |
+| `set_source` | スクリプトソースコードを設定 | Basic |
+| `create` | 新しいスクリプトを作成 | Basic |
+| `delete` | スクリプトを削除 | Basic |
+| `edit_replace` | スクリプトの特定行を置換 | Basic |
+| `edit_insert` | 特定位置に行を挿入 | Basic |
+| `edit_delete` | 特定行を削除 | Basic |
+| `search` | スクリプト内でテキストを検索 | Basic |
+| `get_dependencies` | スクリプトの依存関係を取得 | Basic |
+| `replace` | 複数スクリプトで一括置換 | Pro |
+
+## Manage Lighting（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `lighting` | Lightingサービスプロパティを設定 | Pro |
+| `atmosphere` | Atmosphereプロパティを設定 | Pro |
+| `sky` | Skyプロパティを設定 | Pro |
+| `terrain_props` | Terrain水/視覚プロパティを設定 | Pro |
+| `time` | 時間帯を設定 | Pro |
+
+## Manage Selection（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `get` | 現在の選択を取得 | Basic |
+| `set` | 現在の選択を置換 | Basic |
+| `clear` | 選択をクリア | Basic |
+| `cached` | ラウンドトリップなしでキャッシュされた選択を取得 | Basic |
+| `context` | ソースとプロパティを含む詳細コンテキストを取得 | Pro |
+| `details` | 祖先/子孫を含む階層的詳細を取得 | Pro |
+| `add` | 選択にアイテムを追加 | Pro |
+| `remove` | 選択からアイテムを削除 | Pro |
+| `watch` | 選択変更を監視 | Pro |
+
+## Manage Camera（Basic）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `info` | カメラ位置、回転、FOV、ビューポートサイズを取得 | Basic |
+| `focus_path` | カメラをインスタンスにフォーカス移動 | Basic |
+| `focus_position` | カメラを位置にフォーカス移動 | Basic |
+| `suggest` | ターゲットの推奨カメラビューを取得 | Basic |
+
+## Manage Tween（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `create` | ターゲットプロパティ付きトゥイーンを作成 | Pro |
+| `play` | 作成したトゥイーンを再生 | Pro |
+| `pause` | 実行中のトゥイーンを一時停止 | Pro |
+| `cancel` | トゥイーンをキャンセル | Pro |
+
+## Manage Audio（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `play` | サウンドを再生（必要に応じてSound作成） | Pro |
+| `stop` | 再生中のサウンドを停止 | Pro |
+| `pause` | 再生中のサウンドを一時停止 | Pro |
+| `resume` | 一時停止中のサウンドを再開 | Pro |
+| `set_listener` | オーディオリスナータイプ/ターゲットを設定 | Pro |
+
+## Manage Animation（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `load` | Humanoid/AnimationControllerにアニメーションをロード | Pro |
+| `play` | ロード済みアニメーショントラックを再生 | Pro |
+| `stop` | 再生中のアニメーションを停止 | Pro |
+| `get_tracks` | ロード済み全アニメーショントラックを一覧 | Pro |
+
+## Manage Physics（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `register_group` | 衝突グループを登録 | Pro |
+| `set_collidable` | 2つのグループが衝突可能か設定 | Pro |
+| `get_groups` | 登録済み全衝突グループを一覧 | Pro |
+
+## Manage Effects（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `emit` | ParticleEmitterからパーティクルを放出 | Pro |
+| `clear` | 全パーティクルをクリア | Pro |
+| `toggle` | エフェクトを有効化または無効化 | Pro |
+
+## Manage Terrain（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `fill_block` | ブロック形状の地形を塗りつぶし | Pro |
+| `fill_ball` | 球形状の地形を塗りつぶし | Pro |
+| `fill_cylinder` | 円柱形状の地形を塗りつぶし | Pro |
+| `fill_wedge` | くさび形状の地形を塗りつぶし | Pro |
+| `clear_region` | 領域の地形をクリア | Pro |
+| `clear_bounds` | 境界の地形をクリア | Pro |
+| `replace_material` | 領域のマテリアルを置換 | Pro |
+| `colors_get` | マテリアル色を取得 | Pro |
+| `colors_set` | マテリアル色を設定 | Pro |
+| `read_voxel` | 単一ボクセルデータを読み取り | Pro |
+| `read_voxels` | 一括ボクセルデータを読み取り | Pro |
+| `write_voxels` | 一括ボクセルデータを書き込み | Pro |
+| `generate` | 手続き型地形を生成 | Pro |
+| `smooth` | 地形を滑らかにする | Pro |
+
+## Spatial Query（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `raycast` | 単一レイを投射 | Pro |
+| `find_ground` | 地点下の地面位置を検出 | Pro |
+| `check_placement` | 配置が衝突なしか確認 | Pro |
+| `multi_raycast` | 複数レイを一括投射 | Pro |
+| `scan_area` | 領域のハイトマップを生成 | Pro |
+| `find_flat` | 建築用の平坦エリアを検索 | Pro |
+| `find_spawn` | 適切なスポーン位置を検索 | Pro |
+| `analyze_walkable` | 歩行可能グリッドを分析 | Pro |
+| `spatial_map` | 全BasePartの位置を取得 | Pro |
+| `find_space` | オブジェクト用の空きスペースを検索 | Pro |
+| `bounds` | インスタンスのバウンディングボックスを取得 | Pro |
+| `snap_grid` | 位置をグリッドにスナップ | Pro |
+| `collision` | AABB衝突を確認 | Pro |
+
+## Manage Assets（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `insert` | アセットIDでモデルを挿入 | Pro |
+| `info` | アセットメタデータを取得 | Pro |
+| `search` | Creator Storeを検索 | Pro |
+| `search_insert` | 検索して最初のマッチを挿入 | Pro |
+| `insert_free` | フリーモデルを挿入 | Pro |
+| `insert_package` | パッケージを挿入 | Pro |
+| `export` | 現在の選択をエクスポート | Pro |
+
+## Manage Sync（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `status` | Placeの同期ステータスを取得 | Pro |
+| `config` | 同期設定を取得 | Pro |
+| `history` | 変更履歴を取得 | Pro |
+| `directions` | タイプ別同期方向を取得 | Pro |
+| `read_file` | 同期済みファイルを読み取り | Pro |
+| `write_file` | 同期済みファイルに書き込み | Pro |
+| `progress` | リアルタイム同期進捗と帯域幅を取得 | Pro |
+
+## Workspace State（Pro）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `sync` | 現在のWorkspace状態を取得 | Pro |
+| `snapshot` | 完全なインスタンスツリー構造を取得 | Pro |
+| `changes` | 最近の変更を取得 | Pro |
+| `viewport` | カメラとビューポート情報を取得 | Pro |
+
+## Manage Logs（Basic）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `get` | フィルタリングされたログを取得 | Basic |
+| `clear` | ログバッファをクリア | Basic |
+| `errors` | 最近のエラーのみ取得 | Basic |
+
+## System Info（混合）
+
+| アクション | 説明 | ティア |
+|------------|------|--------|
+| `ping` | 接続テスト | Basic |
+| `connection` | サーバー/プラグイン接続情報を取得 | Basic |
+| `usage` | 現在のティアを取得（basic/pro） | Basic |
+| `place_info` | Place ID、名前、クリエイターを取得 | Pro |
+| `services` | 全Robloxサービスを一覧 | Pro |
+| `studio_settings` | Studio設定を取得 | Pro |
+| `run_command` | Studioコマンドを実行 | Pro |
+
+## Batch Execute（Pro）
+
+複数のコマンドを単一バッチで実行します。各コマンドはツール名と引数を指定します。コマンドは順次実行され、エラー時の続行動作を選択できます。
+
+## Execute Luau（Pro）
+
+Roblox Studioサンドボックスで任意のLuauコードを実行します。ブロックされたサービス：HttpService、DataStoreService、MessagingService。CoreGui/CorePackagesにはアクセスできません。

package/docs/ko/README.md

@@ -6,67 +6,40 @@
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## 이런 것들을 할 수 있어요
+## 핵심 기능
 
-### 아이디어 하나로, 플레이 가능한 게임까지
+### 1) MCP Tool: 말로 지시하면 Studio에서 바로 실행
 
-"마인크래프트 느낌 서바이벌 게임 만들어줘. 낮/밤 사이클, 채집, 제작, 웨이브 방어까지." — 한 문장이면 AI가 게임 구조를 설계하고, 맵·오브젝트·스크립트를 직접 만들어줍니다.
+Roblox MCP의 첫 번째 축은 **MCP Tool 실행 능력**입니다.  
+스크립트, 인스턴스, 속성, 지형, 조명, 에셋, 오디오, 애니메이션까지 AI가 Studio에서 직접 처리합니다.
 
-> **Tip**: "먼저 계획을 세워줘"라고 요청한 뒤 계획을 확인하고 "실행해줘"라고 지시하면 더 완성도 높은 결과를 얻을 수 있습니다.
+- "플레이어 점프 시 파티클 + 사운드 + 쿨타임까지 한 번에 넣어줘."
+- "맵 중앙에 보스 아레나 만들고, 스폰 포인트도 충돌 없이 배치해줘."
+- "이 모듈 인터페이스 바꾸고 참조하는 스크립트 전부 함께 수정해줘."
 
-### 내 프로젝트를 처음부터 끝까지 읽은 AI
+단순 코드 생성이 아니라, **실행 가능한 작업 단위**로 처리된다는 점이 핵심입니다.
 
-AI가 Roblox 프로젝트를 로컬에 동기화해서 모든 스크립트·오브젝트·구조를 파악합니다. 수십 개 파일을 한번에 이해하고 일관되게 수정합니다.
+### 2) Sync: AI가 프로젝트 전체 문맥을 읽고 유지
 
-- "RemoteEvent 쓰는 곳 전부 찾아서 호출 흐름 정리해줘."
-- "적 AI 관련 스크립트 전체를 상태 머신 구조로 통일해줘."
-- "어제 이후 바뀐 파일 기준으로 위험한 변경만 요약해줘."
+두 번째 축은 **Project Sync**입니다.  
+AI가 로컬 동기화된 프로젝트를 기준으로 전체 구조를 이해해, 여러 파일에 걸친 변경을 일관되게 수행합니다.
 
-여러 Place를 동시에 관리하고, 변경 이력도 추적합니다.
+- Basic: Studio -> Local 단방향 동기화
+- Pro: 양방향 동기화 + 타입별 Direction/Apply Mode + 변경 기록 + 멀티 Place
 
-### 스크립트 작성·리팩터링·디버깅, 연관 파일까지 한번에
+즉, "지금 어떤 파일이 실제 기준인지", "무엇이 언제 바뀌었는지"를 놓치지 않고 협업할 수 있습니다.
 
-기능 추가, 버그 수정, 성능 개선을 스크립트 하나가 아니라 연관 파일까지 묶어서 처리합니다.
+## 유저가 바로 체감하는 장점
 
-- "플레이어가 점프할 때 파티클 + 사운드 + 쿨타임 넣어줘."
-- "메모리 누수 가능성 있는 이벤트 연결 전부 찾아서 안전하게 고쳐줘."
-- "이 모듈을 참조하는 모든 스크립트와 함께 인터페이스를 바꿔줘."
+- 반복 작업 압축: 수십 번 클릭/수정을 자연어 한 번으로 처리
+- 연관 변경 자동화: 한 파일 수정이 아니라 의존 파일까지 함께 반영
+- 리스크 감소: 변경 이력과 동기화 상태를 기준으로 안전하게 수정
+- 토큰 효율 개선(Pro): 대량 action과 batch 실행으로 왕복 요청 감소
 
-### 오브젝트 생성과 배치 — 수백 개도 명령 하나로
+## 세부 문서
 
-"이 도로 따라 가로등 50개 간격 맞춰 세워줘", "벽돌 집 20채를 구역별로 랜덤 회전 배치해줘" — AI가 Studio에 직접 만들어줍니다. 여러 오브젝트의 속성을 한번에 변경하는 것도 명령 하나면 충분합니다.
-
-### 조명·날씨·연출을 한 문장으로
-
-"석양의 먼지 낀 사막 분위기로 바꿔줘", "폭풍우 치는 밤, 번개 순간에만 주변이 밝아지게 해줘" — 한마디면 조명, 하늘, 대기, 안개가 한번에 자동으로 바뀝니다.
-
-### 대화로 조각하는 자연 지형
-
-"맵 북쪽에 절벽 산맥, 중앙엔 강, 남쪽엔 넓은 평원 만들어줘" — 산, 강, 평원, 동굴을 대화만으로 생성합니다. 재질, 색상, 높이, 부드럽기를 원하는 대로 조절하고, 지형 편집기를 열지 않고도 맵 전체를 완성할 수 있습니다.
-
-### Creator Store 에셋 검색과 즉시 배치
-
-"중세 성 모델 찾아서 맵 중앙에 배치하고 스케일 1.5배로 맞춰줘" — Creator Store에서 무료 모델을 검색해서 프로젝트에 바로 넣어줍니다.
-
-### 공간 지능으로 레벨 디자인까지
-
-"새 보스 아레나 들어갈 빈 공간 찾아줘", "몬스터가 실제로 순찰 가능한 영역만 추려서 표시해줘" — 복잡한 공간 추론과 배치 로직을 AI가 처리합니다.
-
-### 애니메이션·물리·오디오, 게임 시스템으로 연결
-
-- "대시 애니메이션 재생 중엔 플레이어-적 충돌 규칙 바꿔줘."
-- "궁극기 발동 시 전용 BGM 페이드인, 종료 시 자연스럽게 복귀시켜줘."
-
-캐릭터 움직임, 충돌 규칙, 사운드를 따로따로가 아니라 게임 시스템으로 연결해서 다룹니다.
-
-### 어떤 Roblox API든 직접 실행
-
-"이건 내장 도구엔 없는데?" 싶은 순간에도, AI가 임의의 Luau 코드를 Studio에서 직접 실행합니다.
-
-- "Workspace 전체에서 Anchored=false인 파트만 찾아 목록으로 보여줘."
-- "조건 맞는 오브젝트 일괄 수정하고 변경 결과 로그 남겨줘."
-
-> [전체 기능 목록 보기](tools/overview.md)
+- [Tool 지원 범위 (Tools Overview)](tools/overview.md)
+- [Sync 기능 상세 가이드](sync/overview.md)
 
 ## 시작하기
 

package/docs/ko/installation/ai-apps/gemini-cli.md

@@ -61,7 +61,7 @@ gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp
 
 **CLI:**
 ```bash
-gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox-mcp
+gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp
 ```
 
 **설정 파일:**
@@ -72,7 +72,7 @@ gemini mcp add weppy-roblox-mcp npx --trust -e MCP_PORT=3002 -- -y @weppy/roblox
       "command": "npx",
       "args": ["-y", "@weppy/roblox-mcp"],
       "env": {
-        "MCP_PORT": "3002"
+        "HTTP_PORT": "3002"
       }
     }
   }

package/docs/ko/sync/overview.md

@@ -0,0 +1,104 @@
+# Roblox MCP Sync 상세 가이드
+
+Sync는 Roblox Studio 상태와 로컬 파일을 연결해, AI가 프로젝트 전체 문맥을 안정적으로 읽고 수정할 수 있게 만드는 기능입니다.
+
+## 왜 Sync가 중요한가
+
+Sync가 없으면 AI는 대화에 붙여 넣은 코드 일부만 보고 판단하게 됩니다. Sync를 켜면 프로젝트 전체를 기준으로 작업하므로 다음이 쉬워집니다.
+
+- 여러 스크립트에 걸친 리팩터링을 일관되게 적용
+- 변경 이력을 기반으로 위험한 수정만 빠르게 검토
+- Studio와 로컬 중 어느 쪽이 기준인지 방향을 명확히 유지
+
+## 기본 동작 방식
+
+1. Full Sync: Studio 트리와 인스턴스를 로컬 미러로 초기 동기화
+2. Incremental Sync: 변경 감시로 이후 변경분만 반영
+3. History/Status 추적: 어떤 변경이 언제 어떤 방향으로 반영됐는지 확인
+
+로컬 기본 경로는 `roblox-project-sync/place_{placeId}/explorer` 형태로 생성됩니다.
+
+## Basic vs Pro
+
+| 항목 | Basic | Pro |
+|------|------|-----|
+| 동기화 방향 | Studio -> Local | 양방향 |
+| 타입별 Direction | 미지원 | 지원 (Scripts / Values / Containers / Data / Services) |
+| 타입별 Apply Mode | 미지원 | 지원 (Auto / Manual) |
+| 상태/기록 조회 API | 미지원 | 지원 (`status`, `history`, `progress`) |
+| `manage_sync` 도구 사용 | 미지원 | 지원 |
+| 멀티 Place Sync | 미지원 | 지원 (최대 3개 Place) |
+
+## 동기화 대상과 기본 제외 규칙
+
+기본 동기화 대상 서비스:
+
+- `Workspace`
+- `Lighting`
+- `ReplicatedStorage`
+- `ServerStorage`
+- `ServerScriptService`
+- `StarterGui`
+- `StarterPlayer`
+- `StarterPack`
+- `ReplicatedFirst`
+- `SoundService`
+- `Chat`
+- `LocalizationService`
+
+기본 제외 항목:
+
+- 클래스: `Terrain`, `Camera`
+- 보안상 금지 경로: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity`
+
+## Direction과 Apply Mode
+
+### Direction (타입별 동기화 방향)
+
+- `forward`: Studio -> Local
+- `reverse`: Local -> Studio
+- `bidirectional`: 양방향
+
+타입은 `scripts`, `values`, `containers`, `data`, `services`로 분리되어 관리됩니다.
+
+### Apply Mode (reverse 변경 적용 방식)
+
+- `manual`: Studio 반영 전 사용자가 확인 후 적용
+- `auto`: 감지된 변경을 자동 적용
+
+Pro에서는 타입별로 Direction/Apply Mode를 다르게 설정해 워크플로우를 세밀하게 제어할 수 있습니다.
+
+## `manage_sync` 액션 가이드 (Pro)
+
+| 액션 | 설명 | 주요 인자 |
+|------|------|-----------|
+| `status` | 현재 Place의 동기화 상태 확인 | `placeId` |
+| `config` | 동기화 설정 확인 | `placeId` |
+| `history` | 변경 기록 조회 | `placeId`, `query.limit`, `query.offset` |
+| `directions` | 타입별 Direction 조회 | `placeId` |
+| `read_file` | 동기화된 파일 읽기 | `placeId`, `instancePath` |
+| `write_file` | 동기화된 파일 쓰기 | `placeId`, `instancePath`, `content` |
+| `progress` | 실시간 진행률/처리량 확인 | `placeId` |
+
+## 추천 워크플로우
+
+### 1) 안전하게 시작하기
+
+- 먼저 Full Sync를 완료해 현재 상태를 기준점으로 만듭니다.
+- 초반에는 `manual` 적용으로 운영해 변경 위험을 줄입니다.
+
+### 2) AI와 함께 변경하기
+
+- "Sync 상태 확인하고, 최근 변경 기록 기준으로 위험한 변경만 요약해줘"
+- "`ServerScriptService` 쪽 스크립트만 우선 리팩터링하고, 변경 이력까지 남겨줘"
+
+### 3) 문제 발생 시 복구하기
+
+- `history`로 최근 변경을 추적
+- 필요한 파일을 `read_file`로 확인
+- 복구할 내용을 `write_file`로 반영 후 Studio 상태 재확인
+
+## 함께 보면 좋은 문서
+
+- [Tool 지원 범위 (Tools Overview)](../tools/overview.md)
+- [Pro 업그레이드 가이드](../pro-upgrade.md)

package/docs/ko/tools/overview.md

@@ -2,6 +2,9 @@
 
 MCP 도구의 상세 파라미터는 MCP 도구 정의를 직접 확인하세요.
 
+관련 문서:
+- [Sync 기능 상세 가이드](../sync/overview.md)
+
 Sync 정책:
 - Basic: Studio -> Local 단방향 동기화
 - Pro: 양방향 동기화 + 더 넓은 고급 action 범위(대량 작업으로 AI 토큰 효율 개선)
@@ -211,11 +214,12 @@ Sync 정책:
 | 액션 | 설명 | 티어 |
 |------|------|------|
 | `status` | Place의 동기화 상태 가져오기 | Pro |
-| `config` | 동기화 설정 가져오기/설정 | Pro |
+| `config` | 동기화 설정 가져오기 | Pro |
 | `history` | 변경 기록 가져오기 | Pro |
-| `directions` | 타입별 동기화 방향 가져오기/설정 | Pro |
+| `directions` | 타입별 동기화 방향 가져오기 | Pro |
 | `read_file` | 동기화된 파일 읽기 | Pro |
 | `write_file` | 동기화된 파일에 쓰기 | Pro |
+| `progress` | 실시간 동기화 진행률 및 대역폭 가져오기 | Pro |
 
 ## Workspace State (Pro)