@weppy/roblox-mcp 0.1.7 → 0.1.9

package/docs/ja/tools/overview.md

@@ -1,238 +1,95 @@
-# Roblox MCPツール
+# Roblox MCP 機能
 
-MCPツールの詳細パラメータはMCPツール定義を直接確認してください。
+AIとRoblox Studioを接続して、さまざまな作業を自動化できます。カテゴリ別にどんなことができるかを紹介します。
 
 ---
 
-## Basicツール (68個)
-
-### Instance (インスタンス) - 13個
-
-| ツール | 説明 |
-|------|-------------|
-| `create_instance` | 新しいインスタンスを作成 |
-| `create_instance_with_properties` | プロパティと共にインスタンスを作成 |
-| `clone_instance` | 既存のインスタンスを複製 |
-| `delete_instance` | インスタンスを削除 |
-| `move_instance` | インスタンスを新しい親に移動 |
-| `rename_instance` | インスタンス名を変更 |
-| `get_instance` | インスタンス情報を取得 |
-| `get_instance_children` | インスタンスの子一覧を取得 |
-| `find_first_child` | 名前で最初の子を検索 |
-| `find_first_descendant` | 名前で最初の子孫を検索 |
-| `get_class_info` | クラス情報を取得 |
-| `wait_for_child` | 子が作成されるまで待機 |
-| `pivot_to` | Pivot CFrameを設定 |
-
-### Property (プロパティ) - 10個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_property` | プロパティ値を取得 |
-| `set_property` | プロパティ値を設定 |
-| `get_all_properties` | すべてのプロパティを取得 |
-| `set_multiple_properties` | 複数のプロパティを同時に設定 |
-| `set_calculated_property` | 計算された値でプロパティを設定 |
-| `set_relative_property` | 相対的な値でプロパティを設定 |
-| `get_attribute` | アトリビュート値を取得 |
-| `set_attribute` | アトリビュート値を設定 |
-| `get_all_attributes` | すべてのアトリビュートを取得 |
-| `delete_attribute` | アトリビュートを削除 |
-
-### Script (スクリプト) - 9個
-
-| ツール | 説明 |
-|------|-------------|
-| `create_script` | 新しいスクリプトを作成 |
-| `get_script_source` | スクリプトのソースコードを取得 |
-| `set_script_source` | スクリプトのソースコードを更新 |
-| `delete_script` | スクリプトを削除 |
-| `edit_script_lines` | 特定の行を編集 |
-| `insert_script_lines` | 行を挿入 |
-| `delete_script_lines` | 行を削除 |
-| `search_in_scripts` | スクリプト内を検索 |
-| `get_script_dependencies` | 依存関係を取得 |
-
-### Selection (選択) - 12個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_selection` | 現在選択されているインスタンスを取得 |
-| `get_selection_context` | コンテキストと共に選択項目を取得 |
-| `get_selection_details` | 選択項目の詳細情報を取得 |
-| `set_selection` | インスタンスの選択を設定 |
-| `clear_selection` | 選択を解除 |
-| `add_to_selection` | 選択に追加 |
-| `remove_from_selection` | 選択から削除 |
-| `get_place_info` | Place情報を取得 |
-| `get_services` | ゲームサービス一覧を取得 |
-| `get_studio_settings` | Studio設定を取得 |
-| `run_command` | Studioコマンドを実行 |
-| `watch_selection` | 選択変更を監視 |
-
-### Search (検索) - 2個
-
-| ツール | 説明 |
-|------|-------------|
-| `search_by_name` | 名前でインスタンスを検索 |
-| `search_by_class` | クラスでインスタンスを検索 |
-
-### Tag (タグ) - 5個
-
-| ツール | 説明 |
-|------|-------------|
-| `add_tag` | インスタンスにタグを追加 |
-| `remove_tag` | インスタンスからタグを削除 |
-| `get_tags` | インスタンスのタグ一覧を取得 |
-| `get_tagged` | タグ付けされたインスタンス一覧を取得 |
-| `has_tag` | インスタンスのタグ保有を確認 |
-
-### Camera (カメラ) - 4個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_camera_info` | カメラ情報を取得 |
-| `get_suggested_camera_view` | おすすめのカメラビューを取得 |
-| `focus_camera_path` | パスでインスタンスにカメラをフォーカス |
-| `focus_camera_position` | ワールド位置にカメラをフォーカス |
-
-### Log (ログ) - 3個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_output_logs` | 出力ログを取得 |
-| `clear_output_logs` | 出力ログをクリア |
-| `get_recent_errors` | 最近のエラーを取得 |
-
-### Connection (接続) - 2個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_connection_info` | 接続状態を取得 |
-| `get_usage_status` | 使用量/割り当て状態を取得 |
+## Basic（無料）
+
+### オブジェクト管理
+
+パーツ、モデル、フォルダなどのゲームオブジェクトを作成、複製、削除、移動できます。「赤いパーツを作って」「このモデルを複製して横に置いて」のような作業が可能です。
+
+### プロパティ設定
+
+オブジェクトのサイズ、色、位置、マテリアルなどすべてのプロパティを読み取り、変更できます。複数のプロパティを一度に変更したり、現在の値を基準に相対的に調整することも可能です。
+
+### スクリプト
+
+新しいスクリプトを作成し、既存のコードを読み取り、修正できます。特定の行だけを編集したり、スクリプト内のテキストを検索したり、どのモジュールを参照しているか依存関係を把握することも可能です。
+
+### セレクション
+
+現在選択しているオブジェクトを確認し、選択を変更し、選択をクリアできます。Studioで作業中の対象を理解し制御するために不可欠です。
+
+### 検索
+
+名前やクラス（種類）でゲーム内のオブジェクトを検索できます。
+
+### タグ
+
+オブジェクトにタグを付けたり外したり、特定のタグが付いたオブジェクトを一度に検索できます。同じ種類のオブジェクトをグループで管理するときに便利です。
+
+### カメラ
+
+カメラを特定のオブジェクトや位置に移動できます。作業中のエリアを素早く確認するのに便利です。
+
+### ログ
+
+ゲーム実行中に発生した出力ログとエラーを確認できます。バグの発見と修正に役立ちます。
+
+### 接続
+
+MCPサーバーとRoblox Studioの接続状態と使用量を確認できます。
 
 ---
 
-## Proツール (+72個)
-👉 [Proアップグレードガイド](pro-upgrade.md)
-
-### Script (スクリプト) - 2個
-
-| ツール | 説明 |
-|------|-------------|
-| `replace_in_scripts` | スクリプト内容を一括置換 |
-| `execute_script` | Luauコードを直接実行 |
-
-### Search (検索) - 6個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_file_tree` | ファイルツリーを取得 |
-| `get_project_structure` | プロジェクト構造ツリーを取得 |
-| `search_by_property` | プロパティで検索 |
-| `search_by_tag` | タグで検索 |
-| `get_descendants` | すべての子孫を取得 |
-| `get_ancestors` | 祖先を取得 |
-
-### Bulk (一括操作) - 8個
-
-| ツール | 説明 |
-|------|-------------|
-| `mass_create_instances` | インスタンスを一括作成 |
-| `mass_delete_instances` | インスタンスを一括削除 |
-| `mass_set_property` | プロパティを一括設定 |
-| `mass_get_property` | プロパティを一括取得 |
-| `mass_duplicate` | インスタンスを一括複製 |
-| `smart_duplicate` | オフセットを適用したスマート複製 |
-| `batch_execute` | 複数コマンドを一括実行 |
-| `modify_children` | すべての子を修正 |
-
-### Asset (アセット) - 7個
-
-| ツール | 説明 |
-|------|-------------|
-| `insert_model` | Creator Storeからモデルを挿入 |
-| `get_asset_info` | アセット情報を取得 |
-| `search_creator_store` | Creator Storeアセットを検索 |
-| `search_and_insert_model` | モデルを検索して挿入 |
-| `insert_free_model` | 無料モデルを挿入 |
-| `insert_package` | パッケージを挿入 |
-| `export_selection` | 選択項目をエクスポート |
-
-### Environment (環境) - 5個
-
-| ツール | 説明 |
-|------|-------------|
-| `set_lighting` | ライティングプロパティを設定 |
-| `set_atmosphere` | Atmosphereプロパティを設定 |
-| `set_sky` | Skyプロパティを設定 |
-| `set_terrain` | Terrainプロパティを設定 |
-| `set_time_of_day` | 時間を設定 |
-
-### State (状態) - 9個
-
-| ツール | 説明 |
-|------|-------------|
-| `sync_workspace_state` | Workspace状態を同期 |
-| `get_workspace_snapshot` | Workspaceスナップショットを取得 |
-| `get_recent_changes` | 最近の変更を取得 |
-| `clear_change_history` | 変更履歴をクリア |
-| `get_viewport_info` | ビューポート状態情報を取得 |
-| `get_workspace_metadata` | Workspaceメタデータを取得 |
-| `get_script_list` | スクリプト一覧を取得 |
-| `get_selection_info` | 選択情報を取得 |
-| `clear_state_cache` | 状態キャッシュをクリア |
-
-### Spatial (空間) - 5個
-
-| ツール | 説明 |
-|------|-------------|
-| `get_spatial_map` | エリアの空間マップを取得 |
-| `find_empty_space` | エリア内の空きスペースを検索 |
-| `get_bounds` | インスタンスのバウンディングボックスを取得 |
-| `snap_to_grid` | 位置をグリッドにスナップ |
-| `check_collision` | インスタンス間の衝突を確認 |
-
-### Raycast (レイキャスト) - 8個
-
-| ツール | 説明 |
-|------|-------------|
-| `raycast` | レイキャストを実行して衝突情報を取得 |
-| `find_ground` | その地点の地面位置を検索 |
-| `check_placement` | オブジェクト配置の可否を確認 |
-| `multi_raycast` | 複数レイキャストを実行 |
-| `scan_area` | エリアをスキャンしてハイトマップを生成 |
-| `find_flat_areas` | 平坦な配置エリアを検索 |
-| `find_spawn_positions` | 有効なスポーン位置を検索 |
-| `analyze_walkable_area` | 移動可能エリアを分析 |
-
-### Terrain (地形) - 14個
-
-| ツール | 説明 |
-|------|-------------|
-| `terrain_fill_block` | ブロック形状で地形を塗りつぶし |
-| `terrain_fill_ball` | 球形状で地形を塗りつぶし |
-| `terrain_fill_cylinder` | 円筒形状で地形を塗りつぶし |
-| `terrain_fill_wedge` | 楔形状で地形を塗りつぶし |
-| `terrain_clear` | 地形を削除 (Regionオブジェクト使用) |
-| `terrain_clear_region` | 地形を削除 (最小/最大座標使用) |
-| `terrain_replace_material` | 地形マテリアルを置換 |
-| `terrain_get_material_color` | 地形マテリアルの色を取得 |
-| `terrain_set_material_color` | 地形マテリアルの色を設定 |
-| `terrain_read_voxel` | 単一ボクセルを読み取り |
-| `terrain_read_voxels` | ボクセルデータを読み取り |
-| `terrain_write_voxels` | ボクセルデータを書き込み |
-| `terrain_generate` | 手続き的に地形を生成 |
-| `terrain_smooth` | 地形をスムーズに |
-
-### Visualization (可視化) - 7個
-
-| ツール | 説明 |
-|------|-------------|
-| `visualization_create_area` | エリア可視化を作成 |
-| `visualization_create_marker` | マーカー可視化を作成 (プレビュー含む) |
-| `visualization_create_line` | ライン可視化を作成 |
-| `visualization_remove` | 可視化を削除 |
-| `visualization_clear` | すべての可視化を削除 |
-| `visualization_get_status` | 可視化状態を取得 |
-| `visualization_focus` | 可視化項目にカメラをフォーカス |
+## Pro
+
+より強力な機能が必要なら、Proにアップグレードできます。
+
+### 高度なセレクション
+
+選択したオブジェクトのプロパティやソースコードを含む詳細なコンテキストを確認し、選択階層を探索し、選択にアイテムを追加・削除し、Place情報やゲームサービスを確認できます。高度なワークフローや自動化に便利です。
+
+### 高度なスクリプト
+
+複数のスクリプトの内容を一括で置換したり、Luauコードを即座に実行できます。繰り返しのコード修正や素早いテストに便利です。
+
+### 高度な検索
+
+ファイルツリー全体を探索したり、プロパティやタグでオブジェクトを検索できます。プロジェクト構造を一目で把握し、特定のオブジェクトのすべての子孫や祖先を確認できます。
+
+### 一括操作
+
+数百のオブジェクトを一度に作成、削除、修正、複製できます。マップに木を植えたり、すべてのパーツの色を変えたり、パターンに従ってオブジェクトを配置する大規模な作業を素早く処理します。
+
+### アセット
+
+Roblox Creator Storeから無料モデルを検索してすぐに挿入できます。「中世の城モデルを探して」「武器モデルを入れて」のように会話だけでアセットを追加します。
+
+### 環境設定
+
+照明、空、霧、地形プロパティ、時間帯を自然言語で設定できます。「夕焼けの雰囲気にして」「深夜12時に設定して」のようなリクエストが可能です。
+
+### 状態管理
+
+Workspaceの現在の状態をスナップショットとして保存し、最近の変更やビューポートの状態を確認できます。複雑な作業中に現在の状態を把握するのに役立ちます。
+
+### 空間分析
+
+オブジェクトのサイズと位置を正確に把握し、空きスペースを見つけ、衝突の有無を確認できます。オブジェクトをグリッドに揃えることも可能です。
+
+### レイキャスト
+
+目に見えない光線を飛ばして地形やオブジェクトとの衝突地点を見つけます。地面の位置の検出、オブジェクト配置の可否確認、スポーン位置の検索、移動可能エリアの分析など、ゲームレベルデザインに不可欠な機能です。
+
+### 地形
+
+ブロック、球、円柱、くさびなどさまざまな形状で地形を埋めたり、削ったり、滑らかにできます。マテリアルや色を変更したり、山や川のある自然の地形を手続き的に自動生成することもできます。
+
+### 可視化
+
+エリア、マーカー、ラインなどを画面に表示して、作業中の空間を視覚的に確認できます。デバッグやレベルデザインのレビューに便利です。
+
+👉 [Proアップグレードガイド](../pro-upgrade.md)

package/docs/ko/README.md

@@ -1,47 +1,59 @@
 # Roblox MCP
 
-[English](../en/README.md) | **한국어** | [日本語](../ja/README.md) | [Español](../es/README.md) | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
+[English](../../README.md) | **한국어** | [日本語](../ja/README.md) | [Español](../es/README.md) | [Português](../pt-br/README.md) | [Bahasa Indonesia](../id/README.md)
 
-> AI로 Roblox Studio를 제어하세요.
+> AI에게 말하면, Roblox Studio에서 바로 실행됩니다.
 
 [![Demo](https://img.youtube.com/vi/3jrUpBbZPaw/maxresdefault.jpg)](https://youtu.be/3jrUpBbZPaw)
 
-## 설치 방법
+## 이런 것들을 할 수 있어요
 
-### 1. Roblox 플러그인 설치
+### 게임 한번에 만들기
 
-👉 [플러그인 설치 가이드](installation/roblox-plugin.md)
+"마인크래프트 스타일 서바이벌 게임 만들어줘", "방탈출 퍼즐 게임 만들어줘"처럼 요청하면, AI가 게임 구조를 설계하고 맵, 오브젝트, 스크립트까지 직접 만들어줍니다. 간단한 아이디어 하나로 플레이 가능한 게임을 완성할 수 있어요.
 
-### 2. MCP 서버 설정
+> **Tip**: "먼저 계획을 세워줘"라고 요청한 뒤, 계획을 확인하고 "실행해줘"라고 지시하면 더 완성도 높은 결과를 얻을 수 있습니다.
 
-MCP를 지원하는 모든 AI 앱에서 사용할 수 있습니다. 사용하는 AI 앱에 맞는 가이드를 확인하세요:
+### 오브젝트 만들기와 배치
 
-| AI 앱 | 설치 가이드 |
-|-------|-------------|
-| Claude Code | [설정 방법](installation/claude-code.md) |
-| Claude Desktop | [설정 방법](installation/claude-app.md) |
-| Codex CLI | [설정 방법](installation/codex-cli.md) |
-| Codex Desktop | [설정 방법](installation/codex-app.md) |
-| Gemini CLI | [설정 방법](installation/gemini-cli.md) |
-| Cursor, Windsurf 등 | [설정 방법](installation/antigravity.md) |
+"빨간 벽돌 집을 만들어줘", "나무 10그루를 일렬로 심어줘"처럼 말하면 AI가 Roblox Studio에 직접 만들어줍니다. 하나씩 만들 수도 있고, 수백 개를 한번에 만들 수도 있어요.
 
-## 도구 목록
+### 스크립트 작성과 수정
 
-👉 [전체 도구 목록 보기](tools/overview.md)
+"플레이어가 점프하면 파티클이 나오게 해줘", "이 스크립트에서 버그 찾아줘"처럼 요청하면 AI가 코드를 직접 작성하고 수정합니다. 기존 스크립트를 분석하고, 의존성도 파악해줘요.
 
-## 문제 해결
+### 맵 분위기 설정
 
-- **"Not Connected"**: 플러그인에서 Connect 버튼을 다시 눌러주세요
-- **포트**: 3002번 포트를 사용합니다 (localhost)
+"석양 분위기로 바꿔줘", "비오는 날처럼 어둡게 해줘" 한마디면 조명, 하늘, 안개를 자동으로 조절합니다.
 
-## 링크
+### 지형 생성
 
-- [GitHub](https://github.com/hope1026/roblox-mcp)
-- [이슈 리포트](https://github.com/hope1026/roblox-mcp/issues)
+산, 강, 평원, 동굴 같은 자연 지형을 대화만으로 만들 수 있습니다. 재질, 색상, 크기도 자유롭게 조절하세요.
+
+### 에셋 검색과 삽입
+
+Creator Store에서 무료 모델과 에셋을 검색해서 바로 게임에 넣을 수 있습니다. "중세 성 모델 찾아서 넣어줘"처럼 말하면 돼요.
+
+### 공간 분석과 배치
+
+"이 영역에 빈 공간 찾아줘", "몬스터가 걸어다닐 수 있는 영역 분석해줘" 같은 공간 관련 작업도 AI가 처리합니다.
+
+### 디버깅과 분석
 
-## 라이선스
+게임 에러 로그를 확인하고, 문제를 찾아서 수정하는 것까지 AI와 함께할 수 있습니다.
 
-게임 개발에 무료로 사용할 수 있습니다.
+> [전체 기능 목록 보기](tools/overview.md)
 
-✅ **허용**: 게임 개발, 상업용 게임, 개인 프로젝트
-❌ **불가**: 소프트웨어 재판매, 경쟁 제품 개발
+## 시작하기
+
+설치는 두 단계로 완료됩니다:
+
+1. **Roblox Studio 플러그인 설치** — Studio와 AI를 연결하는 다리 역할을 합니다
+2. **AI 앱에 MCP 서버 등록** — 사용하는 AI 앱에서 Roblox MCP를 인식하도록 설정합니다
+
+5분이면 끝나요. 👉 [설치 가이드 보기](installation/README.md)
+
+## 링크
+
+- [GitHub](https://github.com/hope1026/roblox-mcp)
+- [이슈 리포트](https://github.com/hope1026/roblox-mcp/issues)

package/docs/ko/installation/README.md

@@ -0,0 +1,51 @@
+# 설치 가이드
+
+Roblox MCP를 사용하려면 **두 가지**를 설치해야 합니다.
+
+```
+AI 앱 (Claude, Codex, Gemini 등)
+       │
+   MCP 서버 ← 여기서 AI의 명령을 Roblox가 이해하는 형태로 변환
+       │
+Roblox Studio 플러그인 ← Studio 안에서 명령을 실행
+```
+
+AI 앱이 "파란 파트를 만들어줘"라고 하면, MCP 서버가 이 요청을 변환하고, Roblox Studio 플러그인이 실제로 파트를 만듭니다.
+
+---
+
+## 1단계: Roblox Studio 플러그인 설치
+
+GitHub에서 플러그인 파일을 다운로드한 뒤, Roblox Studio의 Plugins 폴더에 넣으면 됩니다.
+
+👉 [플러그인 설치 가이드](roblox-plugin.md)
+
+---
+
+## 2단계: AI 앱에 MCP 서버 등록
+
+사용하는 AI 앱에 MCP 서버를 등록합니다. MCP를 지원하는 모든 AI 앱에서 사용할 수 있어요.
+
+| AI 앱 | 설치 가이드 |
+|-------|-------------|
+| Claude Code | [설정 방법](ai-apps/claude-code.md) |
+| Claude Desktop | [설정 방법](ai-apps/claude-app.md) |
+| Codex CLI | [설정 방법](ai-apps/codex-cli.md) |
+| Codex Desktop | [설정 방법](ai-apps/codex-app.md) |
+| Gemini CLI | [설정 방법](ai-apps/gemini-cli.md) |
+| Antigravity | [설정 방법](ai-apps/antigravity.md) |
+
+> 위 목록에 없는 AI 앱이라도 MCP를 지원한다면 사용할 수 있습니다. MCP 서버 명령어는 `npx -y @weppy/roblox-mcp` 입니다.
+
+---
+
+## 설치 완료 후
+
+1. **Roblox Studio**를 열고, Plugins 탭에서 **W-MCP** → **Connect** 클릭
+2. **AI 앱**에서 다음과 같이 테스트해보세요:
+
+```
+Roblox Studio에 파란 파트 만들어줘
+```
+
+정상적으로 파트가 생성되면 설치가 완료된 것입니다!

package/docs/ko/installation/roblox-plugin.md

@@ -32,12 +32,12 @@ MCP 서버가 설치되어 있어야 합니다. 사용하는 AI 앱에 맞는
 
 | AI 앱 | 설치 가이드 |
 |-------|-------------|
-| Claude Code | [설정 방법](claude-code.md) |
-| Claude Desktop | [설정 방법](claude-app.md) |
-| Codex CLI | [설정 방법](codex-cli.md) |
-| Codex Desktop | [설정 방법](codex-app.md) |
-| Gemini CLI | [설정 방법](gemini-cli.md) |
-| Cursor, Windsurf 등 | [설정 방법](antigravity.md) |
+| Claude Code | [설정 방법](ai-apps/claude-code.md) |
+| Claude Desktop | [설정 방법](ai-apps/claude-app.md) |
+| Codex CLI | [설정 방법](ai-apps/codex-cli.md) |
+| Codex Desktop | [설정 방법](ai-apps/codex-app.md) |
+| Gemini CLI | [설정 방법](ai-apps/gemini-cli.md) |
+| Antigravity | [설정 방법](ai-apps/antigravity.md) |
 
 ### 연결하기
 

package/docs/ko/pro-upgrade.md

@@ -6,7 +6,7 @@
 
 **완성도 높은 게임** - 지형, 환경, 에셋, 공간 도구로 프로토타입이 아닌 완성된 게임 월드를 만들 수 있습니다.
 
-## Pro가 추가하는 도구 (72개)
+## Pro가 추가하는 도구
 
 | 카테고리 | 기능 |
 |---------|------|
@@ -21,8 +21,7 @@
 
 ### 1단계: Gumroad에서 구매
 
-1. [Gumroad - Weppy Roblox Plugin](https://sunityplugin.gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin
-) 접속
+1. [Gumroad - Weppy Roblox Plugin](https://gumroad.com/l/chllph?utm_source=github&utm_medium=repo&utm_campaign=sunity_plugin) 접속
 2. 플러그인 다운로드
 
 ### 2단계: 플러그인 설치
@@ -37,12 +36,12 @@
 
 1. W-MCP 플러그인 열기
 2. "Pro" 배지가 표시되는지 확인
-3. 140개 전체 도구 사용 가능!
+3. 모든 도구 사용 가능!
 
 ## 기능 비교
 
-| 기능 | Basic (68개) | Pro (140개) |
-|-----|:------------:|:-----------:|
+| 기능 | Basic | Pro |
+|-----|:-----:|:---:|
 | Instance, Script, Property | ✅ 전체 사용 | ✅ 전체 사용 |
 | Selection, Tag, Camera, Log | ✅ 전체 사용 | ✅ 전체 사용 |
 | 대량 작업 (Bulk) | ― | ✅ 무제한 |