@mcptoolshop/file-forge 0.1.0 → 0.2.1

package/README.ja.md

@@ -0,0 +1,241 @@
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/mcp-file-forge/readme.png" alt="MCP File Forge" width="400"></p>
+
+<p align="center">
+  Secure file operations and project scaffolding for AI agents.
+  <br />
+  Part of <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mcptoolshop/file-forge"><img alt="npm version" src="https://img.shields.io/npm/v/@mcptoolshop/file-forge"></a>
+  <a href="https://github.com/mcp-tool-shop-org/mcp-file-forge/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://mcp-tool-shop-org.github.io/mcp-file-forge/"><img alt="Landing Page" src="https://img.shields.io/badge/Landing_Page-live-blue"></a>
+</p>
+
+---
+
+## 概要
+
+MCP File Forgeは、[Model Context Protocol](https://modelcontextprotocol.io) (MCP) サーバーであり、AIエージェントがローカルファイルシステムにアクセスする際に、サンドボックス環境とポリシーによる制御を提供します。 5つのカテゴリに分けて、**17種類のツール**を提供します。
+
+| カテゴリ | ツール | 説明 |
+| ---------- | ------- | ------------- |
+| **Reading** | `read_file`, `read_directory`, `read_multiple` | ファイルの読み込みとディレクトリ一覧の表示 |
+| **Writing** | `write_file`, `create_directory`, `copy_file`, `move_file`, `delete_file` | ファイルの作成、編集、コピー、移動、削除 |
+| **Search** | `glob_search`, `grep_search`, `find_by_content` | ファイル名パターンまたは内容によるファイルの検索 |
+| **Metadata** | `file_stat`, `file_exists`, `get_disk_usage`, `compare_files` | ファイルサイズ、タイムスタンプ、存在確認 |
+| **Scaffolding** | `scaffold_project`, `list_templates` | テンプレートを使用してプロジェクトを作成（変数置換可能） |
+
+主な機能：
+
+- **サンドボックス化:** 実行は、明示的に許可されたディレクトリに限定されます。
+- **読み取り専用モード:** 環境変数を変更することで、すべての書き込み機能を無効にできます。
+- **シンボリックリンク対応:** デフォルトではシンボリックリンクを追跡しないため、サンドボックスからのエスケープを防ぎます。
+- **Windows優先:** Windowsのパスと規約に合わせて設計されており、他の環境でも動作します。
+- **テンプレートエンジン:** `{{var}}` / `${var}` による変数置換に加え、パスレベルでの `__var__` による名前変更が可能です。
+
+---
+
+## インストール
+
+```bash
+npm install -g @mcptoolshop/file-forge
+```
+
+または、npxで直接実行します。
+
+```bash
+npx @mcptoolshop/file-forge
+```
+
+---
+
+## Claude Desktopの設定
+
+`claude_desktop_config.json` に以下の項目を追加します。
+
+```json
+{
+  "mcpServers": {
+    "file-forge": {
+      "command": "npx",
+      "args": ["-y", "@mcptoolshop/file-forge"],
+      "env": {
+        "MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects,C:/Users/you/Documents"
+      }
+    }
+  }
+}
+```
+
+グローバルにインストールした場合は、直接実行ファイルを参照できます。
+
+```json
+{
+  "mcpServers": {
+    "file-forge": {
+      "command": "mcp-file-forge",
+      "env": {
+        "MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects"
+      }
+    }
+  }
+}
+```
+
+---
+
+## ツールの参照
+
+### 読み込み
+
+| ツール | 説明 | 主要なパラメータ |
+| ------ | ------------- | ---------------- |
+| `read_file` | ファイルの内容を読み込む | `path`, `encoding?`, `start_line?`, `end_line?`, `max_size_kb?` |
+| `read_directory` | ディレクトリの内容を一覧表示する | `path`, `recursive?`, `max_depth?`, `include_hidden?`, `pattern?` |
+| `read_multiple` | 複数のファイルをまとめて読み込む | `paths`, `encoding?`, `fail_on_error?` |
+
+### 書き込み
+
+| ツール | 説明 | 主要なパラメータ |
+| ------ | ------------- | ---------------- |
+| `write_file` | ファイルへの書き込みまたは上書き | `path`, `content`, `encoding?`, `create_dirs?`, `overwrite?`, `backup?` |
+| `create_directory` | ディレクトリの作成 | `path`, `recursive?` |
+| `copy_file` | ファイルのコピーまたはディレクトリのコピー | `source`, `destination`, `overwrite?`, `recursive?` |
+| `move_file` | ファイルの移動または名前変更 | `source`, `destination`, `overwrite?` |
+| `delete_file` | ファイルの削除またはディレクトリの削除 | `path`, `recursive?`, `force?` |
+
+### 検索
+
+| ツール | 説明 | 主要なパラメータ |
+| ------ | ------------- | ---------------- |
+| `glob_search` | globパターンによるファイルの検索 | `pattern`, `base_path?`, `max_results?`, `include_dirs?` |
+| `grep_search` | 正規表現によるファイル内容の検索 | `pattern`, `path?`, `glob?`, `case_sensitive?`, `max_results?`, `context_lines?` |
+| `find_by_content` | 正規表現を使用しないテキスト検索 | `text`, `path?`, `file_pattern?`, `max_results?` |
+
+### メタデータ
+
+| ツール | 説明 | 主要なパラメータ |
+| ------ | ------------- | ---------------- |
+| `file_stat` | ファイル/ディレクトリの統計情報 | `path` |
+| `file_exists` | 存在確認と種類の確認 | `path`, `type?` (`file` / `directory` / `any`) |
+| `get_disk_usage` | ディレクトリのサイズ内訳 | `path`, `max_depth?` |
+| `compare_files` | 2つのパスの比較 | `path1`, `path2` |
+
+### テンプレート
+
+| ツール | 説明 | 主要なパラメータ |
+| ------ | ------------- | ---------------- |
+| `scaffold_project` | テンプレートからプロジェクトを作成 | `template`, `destination`, `variables?`, `overwrite?` |
+| `list_templates` | 利用可能なテンプレートの一覧表示 | `category?` |
+
+詳細なパラメータ、例、およびエラーコードは、[HANDBOOK.md](HANDBOOK.md) に記載されています。
+
+---
+
+## 環境変数
+
+| 変数 | 説明 | デフォルト値 |
+| ---------- | ------------- | --------- |
+| `MCP_FILE_FORGE_ALLOWED_PATHS` | 許可されたルートディレクトリのカンマ区切りリスト | `.` (カレントディレクトリ) |
+| `MCP_FILE_FORGE_DENIED_PATHS` | 禁止されたパスのglobパターン (カンマ区切り) | `**/node_modules/**`, `**/.git/**` |
+| `MCP_FILE_FORGE_READ_ONLY` | すべての書き込み操作を無効にする | `false` |
+| `MCP_FILE_FORGE_MAX_FILE_SIZE` | ファイルの最大サイズ (バイト) | `104857600` (100 MB) |
+| `MCP_FILE_FORGE_MAX_DEPTH` | 最大再帰深度 | `20` |
+| `MCP_FILE_FORGE_FOLLOW_SYMLINKS` | サンドボックス外のシンボリックリンクを追跡する | `false` |
+| `MCP_FILE_FORGE_TEMPLATE_PATHS` | カンマ区切りのテンプレートディレクトリ | `./templates` |
+| `MCP_FILE_FORGE_LOG_LEVEL` | ログの詳細度 (`error`, `warn`, `info`, `debug`) | `info` |
+| `MCP_FILE_FORGE_LOG_FILE` | ログファイルのパス (stderrに加えて) | _なし_ |
+
+---
+
+## 設定ファイル
+
+作業ディレクトリ内またはその上位ディレクトリに `mcp-file-forge.json` (または `.mcp-file-forge.json`) を作成します。
+
+```json
+{
+  "sandbox": {
+    "allowed_paths": ["C:/Projects", "C:/Users/you/Documents"],
+    "denied_paths": ["**/secrets/**", "**/.env"],
+    "follow_symlinks": false,
+    "max_file_size": 52428800,
+    "max_depth": 20
+  },
+  "templates": {
+    "paths": ["./templates", "~/.mcp-file-forge/templates"]
+  },
+  "logging": {
+    "level": "info",
+    "file": "./logs/mcp-file-forge.log"
+  },
+  "read_only": false
+}
+```
+
+設定の優先順位 (最も優先されるものが優先されます):
+
+1. 環境変数
+2. 設定ファイル
+3. デフォルト設定
+
+---
+
+## セキュリティ
+
+MCP File Forge は、AIエージェントが指定された作業領域から逸脱しないように、いくつかの保護機能を備えています。
+
+- **パスサンドボックス化:** すべてのパスが絶対パスに解決され、I/O 操作が行われる前に、`allowed_paths` リストに対してチェックされます。
+- **禁止パス:** 許可されたディレクトリ内でもブロックされるグローブパターン (例: `**/secrets/**`)。
+- **シンボリックリンク保護:** デフォルトではシンボリックリンクは追跡されません。シンボリックリンクのターゲットがサンドボックス外にある場合、操作は拒否されます。
+- **パストラバーサル検出:** サンドボックスから抜け出す `..` シーケンスは拒否されます。
+- **サイズ制限:** `max_file_size` を超えるファイルは、メモリ不足を防ぐために拒否されます。
+- **深さ制限:** 再帰的な操作は `max_depth` レベルで制限されます。
+- **読み取り専用モード:** `MCP_FILE_FORGE_READ_ONLY=true` を設定すると、`write_file`、`create_directory`、`copy_file`、`move_file`、`delete_file`、および `scaffold_project` が無効になります。
+- **ヌルバイトの拒否:** `\0` を含むパスは拒否されます。
+- **Windows の長いパスガード:** 32,767 文字を超えるパスは拒否されます。
+
+---
+
+## ドキュメント
+
+| ドキュメント | 説明 |
+| ---------- | ------------- |
+| [HANDBOOK.md](HANDBOOK.md) | 詳細: セキュリティモデル、ツールリファレンス、テンプレート、アーキテクチャ、FAQ |
+| [CHANGELOG.md](CHANGELOG.md) | リリース履歴 (Keep a Changelog 形式) |
+| [docs/PLANNING.md](docs/PLANNING.md) | 内部計画および調査ノート |
+
+---
+
+## 開発
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+---
+
+## ライセンス
+
+[MIT](LICENSE)
+
+---
+
+<a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> によって作成されました。

package/README.md

@@ -1,33 +1,69 @@
-# MCP File Forge
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/mcp-file-forge/readme.png" alt="MCP File Forge" width="400"></p>
 
-A Model Context Protocol (MCP) server for secure file operations and project scaffolding.
+<p align="center">
+  Secure file operations and project scaffolding for AI agents.
+  <br />
+  Part of <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
+</p>
 
-## Features
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mcptoolshop/file-forge"><img alt="npm version" src="https://img.shields.io/npm/v/@mcptoolshop/file-forge"></a>
+  <a href="https://github.com/mcp-tool-shop-org/mcp-file-forge/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://mcp-tool-shop-org.github.io/mcp-file-forge/"><img alt="Landing Page" src="https://img.shields.io/badge/Landing_Page-live-blue"></a>
+</p>
 
-- **Secure File Operations**: Read, write, copy, move, and delete files with sandboxed access controls
-- **Project Scaffolding**: Create projects from templates with variable substitution
-- **Windows-First**: Optimized for Windows paths, permissions, and conventions
-- **Search Capabilities**: Glob patterns and regex content search
-- **Configurable Security**: Define allowed paths, size limits, and read-only modes
+---
+
+## At a Glance
+
+MCP File Forge is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives AI agents sandboxed, policy-controlled access to the local file system. It ships **17 tools** across five categories:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Reading** | `read_file`, `read_directory`, `read_multiple` | Read files and directory listings |
+| **Writing** | `write_file`, `create_directory`, `copy_file`, `move_file`, `delete_file` | Create, modify, copy, move, and delete |
+| **Search** | `glob_search`, `grep_search`, `find_by_content` | Find files by name pattern or content |
+| **Metadata** | `file_stat`, `file_exists`, `get_disk_usage`, `compare_files` | Inspect size, timestamps, existence |
+| **Scaffolding** | `scaffold_project`, `list_templates` | Create projects from templates with variable substitution |
+
+Key properties:
+
+- **Sandboxed** -- operations are restricted to explicitly allowed directories.
+- **Read-only mode** -- flip one env var to disable all write tools.
+- **Symlink-safe** -- symlink following is off by default to prevent sandbox escapes.
+- **Windows-first** -- designed for Windows paths and conventions, works everywhere.
+- **Template engine** -- `{{var}}` / `${var}` substitution plus path-level `__var__` renaming.
+
+---
 
 ## Installation
 
 ```bash
-npm install @mcp-tool-shop/file-forge
+npm install -g @mcptoolshop/file-forge
+```
+
+Or run directly with npx:
+
+```bash
+npx @mcptoolshop/file-forge
 ```
 
-## Quick Start
+---
 
-### With Claude Desktop
+## Claude Desktop Configuration
 
-Add to your `claude_desktop_config.json`:
+Add the following to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "file-forge": {
-      "command": "node",
-      "args": ["path/to/mcp-file-forge/build/index.js"],
+      "command": "npx",
+      "args": ["-y", "@mcptoolshop/file-forge"],
       "env": {
         "MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects,C:/Users/you/Documents"
       }
@@ -36,69 +72,144 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-### Standalone
+If you installed globally you can point directly at the binary:
 
-```bash
-npx @mcp-tool-shop/file-forge
+```json
+{
+  "mcpServers": {
+    "file-forge": {
+      "command": "mcp-file-forge",
+      "env": {
+        "MCP_FILE_FORGE_ALLOWED_PATHS": "C:/Projects"
+      }
+    }
+  }
+}
 ```
 
-## Available Tools
+---
 
-### File Reading
-- `read_file` - Read file contents with encoding and line range options
-- `read_directory` - List directory contents with metadata
-- `read_multiple` - Batch read multiple files
+## Tool Reference
 
-### File Writing
-- `write_file` - Write or overwrite file contents
-- `create_directory` - Create directories
-- `copy_file` - Copy files or directories
-- `move_file` - Move or rename files
-- `delete_file` - Delete files or directories
+### Reading
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `read_file` | Read file contents | `path`, `encoding?`, `start_line?`, `end_line?`, `max_size_kb?` |
+| `read_directory` | List directory entries | `path`, `recursive?`, `max_depth?`, `include_hidden?`, `pattern?` |
+| `read_multiple` | Batch-read multiple files | `paths`, `encoding?`, `fail_on_error?` |
+
+### Writing
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `write_file` | Write or overwrite a file | `path`, `content`, `encoding?`, `create_dirs?`, `overwrite?`, `backup?` |
+| `create_directory` | Create a directory | `path`, `recursive?` |
+| `copy_file` | Copy a file or directory | `source`, `destination`, `overwrite?`, `recursive?` |
+| `move_file` | Move or rename | `source`, `destination`, `overwrite?` |
+| `delete_file` | Delete a file or directory | `path`, `recursive?`, `force?` |
 
 ### Search
-- `glob_search` - Find files matching glob patterns
-- `grep_search` - Search file contents with regex
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `glob_search` | Find files by glob pattern | `pattern`, `base_path?`, `max_results?`, `include_dirs?` |
+| `grep_search` | Search file contents with regex | `pattern`, `path?`, `glob?`, `case_sensitive?`, `max_results?`, `context_lines?` |
+| `find_by_content` | Literal text search (no regex) | `text`, `path?`, `file_pattern?`, `max_results?` |
 
 ### Metadata
-- `file_stat` - Get file statistics
-- `file_exists` - Check if path exists
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `file_stat` | File/directory statistics | `path` |
+| `file_exists` | Check existence and type | `path`, `type?` (`file` / `directory` / `any`) |
+| `get_disk_usage` | Directory size breakdown | `path`, `max_depth?` |
+| `compare_files` | Compare two paths | `path1`, `path2` |
 
 ### Scaffolding
-- `scaffold_project` - Create project from template
-- `list_templates` - List available templates
 
-## Configuration
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `scaffold_project` | Create project from template | `template`, `destination`, `variables?`, `overwrite?` |
+| `list_templates` | List available templates | `category?` |
 
-### Environment Variables
+Full parameter documentation, examples, and error codes are in the [HANDBOOK.md](HANDBOOK.md).
+
+---
+
+## Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `MCP_FILE_FORGE_ALLOWED_PATHS` | Comma-separated allowed paths | `.` |
-| `MCP_FILE_FORGE_READ_ONLY` | Disable write operations | `false` |
-| `MCP_FILE_FORGE_MAX_FILE_SIZE` | Max file size in bytes | `104857600` |
-| `MCP_FILE_FORGE_LOG_LEVEL` | Logging level | `info` |
+| `MCP_FILE_FORGE_ALLOWED_PATHS` | Comma-separated list of allowed root directories | `.` (cwd) |
+| `MCP_FILE_FORGE_DENIED_PATHS` | Comma-separated denied path glob patterns | `**/node_modules/**`, `**/.git/**` |
+| `MCP_FILE_FORGE_READ_ONLY` | Disable all write operations | `false` |
+| `MCP_FILE_FORGE_MAX_FILE_SIZE` | Maximum file size in bytes | `104857600` (100 MB) |
+| `MCP_FILE_FORGE_MAX_DEPTH` | Maximum recursion depth | `20` |
+| `MCP_FILE_FORGE_FOLLOW_SYMLINKS` | Allow following symlinks outside sandbox | `false` |
+| `MCP_FILE_FORGE_TEMPLATE_PATHS` | Comma-separated template directories | `./templates` |
+| `MCP_FILE_FORGE_LOG_LEVEL` | Log verbosity (`error`, `warn`, `info`, `debug`) | `info` |
+| `MCP_FILE_FORGE_LOG_FILE` | Path to a log file (in addition to stderr) | _none_ |
+
+---
 
-### Config File
+## Config File
 
-Create `mcp-file-forge.json` in the working directory:
+Create `mcp-file-forge.json` (or `.mcp-file-forge.json`) in or above your working directory:
 
 ```json
 {
   "sandbox": {
-    "allowed_paths": ["./projects"],
-    "denied_paths": ["**/secrets/**"],
-    "max_file_size": 52428800
-  }
+    "allowed_paths": ["C:/Projects", "C:/Users/you/Documents"],
+    "denied_paths": ["**/secrets/**", "**/.env"],
+    "follow_symlinks": false,
+    "max_file_size": 52428800,
+    "max_depth": 20
+  },
+  "templates": {
+    "paths": ["./templates", "~/.mcp-file-forge/templates"]
+  },
+  "logging": {
+    "level": "info",
+    "file": "./logs/mcp-file-forge.log"
+  },
+  "read_only": false
 }
 ```
 
+Configuration priority (highest wins):
+
+1. Environment variables
+2. Config file
+3. Built-in defaults
+
+---
+
 ## Security
 
-- Path sandboxing restricts operations to allowed directories
-- Symlink following is disabled by default
-- Read-only mode available for safe browsing
-- Size limits prevent memory exhaustion
+MCP File Forge enforces several layers of protection to keep AI agents from reaching outside their designated workspace:
+
+- **Path sandboxing** -- every path is resolved to an absolute path and checked against the `allowed_paths` list before any I/O occurs.
+- **Denied paths** -- glob patterns that are blocked even within allowed directories (e.g. `**/secrets/**`).
+- **Symlink protection** -- symlinks are not followed by default; if a symlink target resolves outside the sandbox, the operation is denied.
+- **Path traversal detection** -- `..` sequences that would escape the sandbox are rejected.
+- **Size limits** -- files larger than `max_file_size` are refused to prevent memory exhaustion.
+- **Depth limits** -- recursive operations are capped at `max_depth` levels.
+- **Read-only mode** -- set `MCP_FILE_FORGE_READ_ONLY=true` to disable `write_file`, `create_directory`, `copy_file`, `move_file`, `delete_file`, and `scaffold_project`.
+- **Null-byte rejection** -- paths containing `\0` are refused.
+- **Windows long-path guard** -- paths exceeding 32,767 characters are refused.
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [HANDBOOK.md](HANDBOOK.md) | Deep-dive: security model, tool reference, templates, architecture, FAQ |
+| [CHANGELOG.md](CHANGELOG.md) | Release history (Keep a Changelog format) |
+| [docs/PLANNING.md](docs/PLANNING.md) | Internal planning and research notes |
+
+---
 
 ## Development
 
@@ -109,17 +220,22 @@ npm install
 # Build
 npm run build
 
-# Development mode (watch)
+# Watch mode
 npm run dev
 
 # Run tests
 npm test
+
+# Lint
+npm run lint
 ```
 
+---
+
 ## License
 
-MIT
+[MIT](LICENSE)
 
-## Author
+---
 
-mcp-tool-shop
+Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>