encoding-aware-fs 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "encoding-aware-fs",
+  "version": "0.1.0",
+  "description": "Encoding-aware file operations MCP Server for AI tools working with GB18030 projects",
+  "main": "dist/server.js",
+  "bin": {
+    "encoding-aware-fs": "dist/index.js"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "prepare": "node build.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["mcp", "encoding", "gb18030", "utf-8", "claude-code", "opencode"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0",
+    "iconv-lite": "^0.6.3",
+    "diff": "^8.0.3",
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.20.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/skills/claude-code/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: encoding-aware-fs
+description: >
+  Use encoding-aware-fs MCP tools for all file operations in this project.
+  This project contains files encoded in GB18030/GBK/GB2312, and the MCP server
+  handles encoding detection and conversion transparently. Use this skill whenever
+  you are reading, writing, or editing files in this project — even if the user
+  doesn't mention encoding. The MCP tools replace the built-in Read, Write, and
+  Edit tools for any file inside the project directory.
+---
+
+# Encoding-Aware File Operations
+
+This project uses the **encoding-aware-fs** MCP server to handle files that may
+be encoded in GB18030, GBK, or GB2312. The server automatically detects file
+encoding and converts to/from UTF-8, so you always work with readable text.
+
+## Why This Matters
+
+Many source files in this project are stored in GB18030 (a Chinese character
+encoding). If you read them with the standard Read tool, Chinese text will appear
+as garbled bytes. If you write UTF-8 content back without re-encoding, you'll
+corrupt the file for other tools that expect GB18030. The MCP tools handle all
+of this transparently.
+
+## Tool Mapping
+
+Use these MCP tools **instead of** the built-in equivalents:
+
+| Built-in Tool | MCP Tool      | Purpose                                    |
+|---------------|---------------|--------------------------------------------|
+| Read          | `read_file`   | Read file content (returns UTF-8)          |
+| Edit          | `edit_file`   | Find-and-replace edits (preserves encoding)|
+| Write         | `write_file`  | Write content to file (encodes to original)|
+
+## Tool Parameters
+
+### read_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "head": 50,
+  "tail": 20
+}
+```
+- `path` (required): Absolute file path
+- `head` (optional): Return only the first N lines
+- `tail` (optional): Return only the last N lines
+- Cannot specify both `head` and `tail`
+
+### edit_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "edits": [
+    { "oldText": "text to find", "newText": "replacement text" }
+  ],
+  "dryRun": false
+}
+```
+- `path` (required): Absolute file path
+- `edits` (required): Array of `{oldText, newText}` replacements
+- `dryRun` (optional): Preview changes without writing (returns unified diff)
+- Supports exact match and fuzzy line-by-line matching with indentation preservation
+
+### write_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "content": "UTF-8 text content to write"
+}
+```
+- `path` (required): Absolute file path
+- `content` (required): UTF-8 text to write
+- Preserves existing file encoding; new files use project default encoding
+
+## Usage Examples
+
+**Reading a GB18030-encoded source file:**
+```
+Use read_file with path "/project/src/module.cpp"
+→ Returns clean UTF-8 text, Chinese characters display correctly
+```
+
+**Editing a function in an encoded file:**
+```
+Use edit_file with:
+  path: "/project/src/utils.cpp"
+  edits: [{ oldText: "旧的函数实现", newText: "新的函数实现" }]
+→ File stays in GB18030, only the targeted text changes
+```
+
+**Writing a new file (inherits project encoding):**
+```
+Use write_file with:
+  path: "/project/src/new-module.cpp"
+  content: "// 新模块\n#include <stdio.h>\n"
+→ Written in the project's default encoding (GB18030)
+```
+
+## When to Use MCP Tools vs Built-in Tools
+
+**Use MCP tools (`read_file` / `edit_file` / `write_file`) for:**
+- Any file inside the project directory
+- Any file that might be GB-encoded
+- All project source files, config files, and data files
+
+**Use built-in tools (Read / Edit / Write) for:**
+- Files outside the project directory (e.g., system files, other projects)
+- Files that you know are not part of this project
+
+## Fallback Behavior
+
+If an MCP tool call fails (e.g., server not running, connection error), fall back
+to the built-in tool for that operation. The built-in tool won't handle encoding
+conversion, but it's better than failing entirely. Inform the user that encoding
+may not be handled correctly in this case.
+
+## Project Configuration
+
+The file `.encoding-converter.json` in the project root controls encoding behavior:
+
+```json
+{
+  "sourceEncoding": "GB18030",
+  "targetEncoding": "UTF-8",
+  "confidenceThreshold": 0.8
+}
+```
+
+- `sourceEncoding`: Default encoding for files when auto-detection is uncertain
+- `targetEncoding`: Always UTF-8 (the encoding you see and produce)
+- `confidenceThreshold`: Minimum confidence (0-1) to trust auto-detected encoding

package/skills/opencode/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: encoding-aware-fs
+description: >
+  Use encoding-aware-fs MCP tools for all file operations in this project.
+  This project contains files encoded in GB18030/GBK/GB2312, and the MCP server
+  handles encoding detection and conversion transparently. Use this skill whenever
+  you are reading, writing, or editing files in this project — even if the user
+  doesn't mention encoding. The MCP tools replace the built-in file read/write/edit
+  tools for any file inside the project directory.
+---
+
+# Encoding-Aware File Operations
+
+This project uses the **encoding-aware-fs** MCP server to handle files that may
+be encoded in GB18030, GBK, or GB2312. The server automatically detects file
+encoding and converts to/from UTF-8, so you always work with readable text.
+
+## Why This Matters
+
+Many source files in this project are stored in GB18030 (a Chinese character
+encoding). If you read them with standard file tools, Chinese text will appear
+as garbled bytes. If you write UTF-8 content back without re-encoding, you'll
+corrupt the file for other tools that expect GB18030. The MCP tools handle all
+of this transparently.
+
+## Tool Mapping
+
+Use these MCP tools **instead of** the built-in equivalents:
+
+| Action         | MCP Tool      | Purpose                                    |
+|----------------|---------------|--------------------------------------------|
+| Read a file    | `read_file`   | Read file content (returns UTF-8)          |
+| Edit a file    | `edit_file`   | Find-and-replace edits (preserves encoding)|
+| Write a file   | `write_file`  | Write content to file (encodes to original)|
+
+## Tool Parameters
+
+### read_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "head": 50,
+  "tail": 20
+}
+```
+- `path` (required): Absolute file path
+- `head` (optional): Return only the first N lines
+- `tail` (optional): Return only the last N lines
+- Cannot specify both `head` and `tail`
+
+### edit_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "edits": [
+    { "oldText": "text to find", "newText": "replacement text" }
+  ],
+  "dryRun": false
+}
+```
+- `path` (required): Absolute file path
+- `edits` (required): Array of `{oldText, newText}` replacements
+- `dryRun` (optional): Preview changes without writing (returns unified diff)
+- Supports exact match and fuzzy line-by-line matching with indentation preservation
+
+### write_file
+```json
+{
+  "path": "/absolute/path/to/file.txt",
+  "content": "UTF-8 text content to write"
+}
+```
+- `path` (required): Absolute file path
+- `content` (required): UTF-8 text to write
+- Preserves existing file encoding; new files use project default encoding
+
+## Usage Examples
+
+**Reading a GB18030-encoded source file:**
+```
+Use read_file with path "/project/src/module.cpp"
+→ Returns clean UTF-8 text, Chinese characters display correctly
+```
+
+**Editing a function in an encoded file:**
+```
+Use edit_file with:
+  path: "/project/src/utils.cpp"
+  edits: [{ oldText: "旧的函数实现", newText: "新的函数实现" }]
+→ File stays in GB18030, only the targeted text changes
+```
+
+**Writing a new file (inherits project encoding):**
+```
+Use write_file with:
+  path: "/project/src/new-module.cpp"
+  content: "// 新模块\n#include <stdio.h>\n"
+→ Written in the project's default encoding (GB18030)
+```
+
+## When to Use MCP Tools vs Built-in Tools
+
+**Use MCP tools (`read_file` / `edit_file` / `write_file`) for:**
+- Any file inside the project directory
+- Any file that might be GB-encoded
+- All project source files, config files, and data files
+
+**Use built-in tools for:**
+- Files outside the project directory (e.g., system files, other projects)
+- Files that you know are not part of this project
+
+## Fallback Behavior
+
+If an MCP tool call fails (e.g., server not running, connection error), fall back
+to the built-in tool for that operation. The built-in tool won't handle encoding
+conversion, but it's better than failing entirely. Inform the user that encoding
+may not be handled correctly in this case.
+
+## Project Configuration
+
+The file `.encoding-converter.json` in the project root controls encoding behavior:
+
+```json
+{
+  "sourceEncoding": "GB18030",
+  "targetEncoding": "UTF-8",
+  "confidenceThreshold": 0.8
+}
+```
+
+- `sourceEncoding`: Default encoding for files when auto-detection is uncertain
+- `targetEncoding`: Always UTF-8 (the encoding you see and produce)
+- `confidenceThreshold`: Minimum confidence (0-1) to trust auto-detected encoding