codepage-bridge-mcp 0.1.0

package/dist/src/tools/write.js

@@ -0,0 +1,80 @@
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { encodeText } from '../encoding/index.js';
+import { getProjectFileContext, encodeSnapshotText, readDecodedFile, readRegistry } from '../core.js';
+import { createStructuredPatch } from '../diff.js';
+import { atomicWriteBuffer } from '../filesystem/index.js';
+import { assertObject, rejectUnknown, requiredString } from '../validation.js';
+export function parseWriteInput(value) {
+    assertObject(value);
+    rejectUnknown(value, ['file_path', 'content']);
+    return {
+        file_path: requiredString(value, 'file_path'),
+        content: requiredString(value, 'content'),
+    };
+}
+export async function executeWrite(input) {
+    const context = await getProjectFileContext(input.file_path);
+    let exists = true;
+    try {
+        await stat(context.absolutePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        exists = false;
+    }
+    await mkdir(path.dirname(context.absolutePath), { recursive: true });
+    if (!exists) {
+        const buffer = encodeText(input.content, context.encoding);
+        await atomicWriteBuffer(context.root, context.absolutePath, buffer);
+        const info = await stat(context.absolutePath);
+        const snapshot = {
+            absolutePath: context.absolutePath,
+            root: context.root,
+            encoding: context.encoding,
+            text: '',
+            bom: null,
+            newline: null,
+            mtimeMs: 0,
+            size: 0,
+            hash: '',
+            complete: true,
+        };
+        readRegistry.updateAfterWrite(snapshot, input.content, buffer, info.mtimeMs);
+        return {
+            content: [{ type: 'text', text: `File created successfully at: ${context.absolutePath}` }],
+            structuredContent: {
+                type: 'create',
+                filePath: context.absolutePath,
+                content: input.content,
+                structuredPatch: createStructuredPatch(context.absolutePath, '', input.content),
+                originalFile: null,
+            },
+        };
+    }
+    const readSnapshot = readRegistry.get(context.absolutePath);
+    if (!readSnapshot)
+        throw new Error('File has not been read. Read it before attempting to write it.');
+    const current = await readDecodedFile(context);
+    if ((current.hash !== readSnapshot.hash || current.mtimeMs !== readSnapshot.mtimeMs) && current.text !== readSnapshot.text) {
+        throw new Error('File has been unexpectedly modified. Read it again before attempting to write it.');
+    }
+    const buffer = encodeSnapshotText(current, input.content, false);
+    await atomicWriteBuffer(context.root, context.absolutePath, buffer, {
+        expected: { mtimeMs: current.mtimeMs, hash: current.hash },
+    });
+    const info = await stat(context.absolutePath);
+    readRegistry.updateAfterWrite(current, input.content, buffer, info.mtimeMs);
+    return {
+        content: [{ type: 'text', text: `The file ${context.absolutePath} has been updated successfully.` }],
+        structuredContent: {
+            type: 'update',
+            filePath: context.absolutePath,
+            content: input.content,
+            structuredPatch: createStructuredPatch(context.absolutePath, current.text, input.content),
+            originalFile: current.text,
+        },
+    };
+}
+//# sourceMappingURL=write.js.map

package/dist/src/tools/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../../src/tools/write.ts"],"names":[],"mappings":"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"}

package/dist/src/validation.d.ts

@@ -0,0 +1,6 @@
+export declare function assertObject(value: unknown): asserts value is Record<string, unknown>;
+export declare function rejectUnknown(input: Record<string, unknown>, allowed: readonly string[]): void;
+export declare function requiredString(input: Record<string, unknown>, key: string): string;
+export declare function optionalString(input: Record<string, unknown>, key: string): string | undefined;
+export declare function optionalInteger(input: Record<string, unknown>, key: string, minimum: number): number | undefined;
+export declare function optionalBoolean(input: Record<string, unknown>, key: string): boolean | undefined;

package/dist/src/validation.js

@@ -0,0 +1,42 @@
+export function assertObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('Tool input must be an object');
+    }
+}
+export function rejectUnknown(input, allowed) {
+    const unknown = Object.keys(input).filter(key => !allowed.includes(key));
+    if (unknown.length > 0)
+        throw new Error(`Unknown input field(s): ${unknown.join(', ')}`);
+}
+export function requiredString(input, key) {
+    const value = input[key];
+    if (typeof value !== 'string')
+        throw new Error(`${key} must be a string`);
+    return value;
+}
+export function optionalString(input, key) {
+    const value = input[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${key} must be a string`);
+    return value;
+}
+export function optionalInteger(input, key, minimum) {
+    const value = input[key];
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < minimum) {
+        throw new Error(`${key} must be an integer greater than or equal to ${minimum}`);
+    }
+    return value;
+}
+export function optionalBoolean(input, key) {
+    const value = input[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`${key} must be a boolean`);
+    return value;
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAA;IACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA8B,EAAE,OAA0B;IACtF,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;IACxE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAC1F,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAA8B,EAAE,GAAW;IACxE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,mBAAmB,CAAC,CAAA;IACzE,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAA8B,EAAE,GAAW;IACxE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,mBAAmB,CAAC,CAAA;IACzE,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAA8B,EAC9B,GAAW,EACX,OAAe;IAEf,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAK,KAAgB,GAAG,OAAO,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,gDAAgD,OAAO,EAAE,CAAC,CAAA;IAClF,CAAC;IACD,OAAO,KAAe,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAA8B,EAAE,GAAW;IACzE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IACxB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACzC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,GAAG,oBAAoB,CAAC,CAAA;IAC3E,OAAO,KAAK,CAAA;AACd,CAAC"}

package/examples/claude-config/settings.fragment.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__codepage-bridge__Read",
+      "mcp__codepage-bridge__Grep",
+      "mcp__codepage-bridge__Edit",
+      "mcp__codepage-bridge__Write"
+    ],
+    "deny": [
+      "Read",
+      "Grep",
+      "Edit",
+      "Write",
+      "NotebookEdit"
+    ]
+  }
+}

package/examples/minimal-project/.encoding-rules

@@ -0,0 +1,10 @@
+# Minimal project encoding rules
+# Last matching rule wins
+
+*.c gbk
+*.cpp gbk
+*.h gbk
+**/*.json utf8
+
+# Example: generated files remain strict UTF-8
+!SourceCode/generated/**

package/examples/minimal-project/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "codepage-bridge": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "/absolute/path/to/codepage-bridge-mcp/dist/src/server.js"
+      ]
+    }
+  }
+}

package/examples/minimal-project/CLAUDE.md

@@ -0,0 +1,15 @@
+## File encoding policy
+
+Use Codepage Bridge for all project file content operations:
+
+- Read with `mcp__codepage-bridge__Read`.
+- Search with `mcp__codepage-bridge__Grep`.
+- Edit with `mcp__codepage-bridge__Edit`.
+- Create or completely rewrite with `mcp__codepage-bridge__Write`.
+
+Do not use built-in Read, Grep, Edit, Write, NotebookEdit, shell commands,
+PowerShell commands, or scripts as substitutes for project file content access.
+Glob may only be used to discover paths.
+
+Do not manually transcode files or normalize line endings. `.encoding-rules`
+is the source of truth.

package/install/download-release-unix.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="${1:-latest}"
+SERVER_NAME="${SERVER_NAME:-codepage-bridge}"
+SCOPE="${SCOPE:-user}"
+REPO="skyispainted/codepage-bridge-mcp"
+INSTALL_ROOT="${HOME}/.codepage-bridge"
+RELEASE_ROOT="${INSTALL_ROOT}/releases"
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Required command not found: $1" >&2
+    exit 1
+  }
+}
+
+require_command node
+require_command claude
+require_command curl
+require_command tar
+require_command uname
+
+mkdir -p "$RELEASE_ROOT"
+
+platform="$(uname -s)"
+arch="$(uname -m)"
+case "$platform" in
+  Linux) os="linux" ;;
+  Darwin) os="darwin" ;;
+  *) echo "Unsupported platform: $platform" >&2; exit 1 ;;
+esac
+case "$arch" in
+  x86_64|amd64) cpu="x64" ;;
+  arm64|aarch64) cpu="arm64" ;;
+  *) echo "Unsupported architecture: $arch" >&2; exit 1 ;;
+esac
+
+if [ "$VERSION" = "latest" ]; then
+  api_url="https://api.github.com/repos/$REPO/releases/latest"
+else
+  api_url="https://api.github.com/repos/$REPO/releases/tags/$VERSION"
+fi
+
+release_json="$(curl -fsSL -H 'User-Agent: codepage-bridge-installer' "$api_url")"
+tag="$(printf '%s' "$release_json" | node -e "const fs=require('fs'); const data=JSON.parse(fs.readFileSync(0,'utf8')); process.stdout.write(data.tag_name)")"
+asset_name="codepage-bridge-${tag}-${os}-${cpu}.tar.gz"
+asset_url="$(printf '%s' "$release_json" | node -e "const fs=require('fs'); const data=JSON.parse(fs.readFileSync(0,'utf8')); const asset=data.assets.find(a=>a.name===process.argv[1]); if(!asset){process.exit(2)} process.stdout.write(asset.browser_download_url)" "$asset_name")" || {
+  echo "Release asset not found: $asset_name" >&2
+  exit 1
+}
+
+archive="$INSTALL_ROOT/$asset_name"
+target_dir="$RELEASE_ROOT/$tag"
+rm -rf "$target_dir"
+mkdir -p "$target_dir"
+
+echo "[1/3] Downloading $asset_name ..."
+curl -fsSL -H 'User-Agent: codepage-bridge-installer' "$asset_url" -o "$archive"
+
+echo "[2/3] Extracting release ..."
+tar -xzf "$archive" -C "$target_dir"
+rm -f "$archive"
+
+package_root="$target_dir/codepage-bridge-${tag}-${os}-${cpu}"
+if [ ! -d "$package_root" ]; then
+  echo "Expected extracted package directory not found: $package_root" >&2
+  exit 1
+fi
+
+echo "[3/3] Installing extracted release package ..."
+bash "$package_root/install/install-this-release-unix.sh" "$SERVER_NAME"

package/install/download-release-windows.ps1

@@ -0,0 +1,61 @@
+param(
+  [string]$Version = 'latest',
+  [string]$ServerName = 'codepage-bridge',
+  [string]$Scope = 'user'
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Require-Command($name) {
+  if (-not (Get-Command $name -ErrorAction SilentlyContinue)) {
+    throw "Required command not found: $name"
+  }
+}
+
+Require-Command node
+Require-Command claude
+Require-Command powershell
+
+$Repo = 'skyispainted/codepage-bridge-mcp'
+$InstallRoot = Join-Path $env:USERPROFILE '.codepage-bridge'
+$ReleaseRoot = Join-Path $InstallRoot 'releases'
+New-Item -ItemType Directory -Force -Path $ReleaseRoot | Out-Null
+
+function Get-ReleaseInfo {
+  param([string]$Version)
+  if ($Version -eq 'latest') {
+    $url = "https://api.github.com/repos/$Repo/releases/latest"
+  } else {
+    $url = "https://api.github.com/repos/$Repo/releases/tags/$Version"
+  }
+  Invoke-RestMethod -Uri $url -Headers @{ 'User-Agent' = 'codepage-bridge-installer' }
+}
+
+$release = Get-ReleaseInfo -Version $Version
+$tag = $release.tag_name
+$assetName = "codepage-bridge-$tag-win32-x64.zip"
+$asset = $release.assets | Where-Object { $_.name -eq $assetName } | Select-Object -First 1
+if (-not $asset) {
+  throw "Release asset not found: $assetName"
+}
+
+$zipPath = Join-Path $InstallRoot $assetName
+$targetDir = Join-Path $ReleaseRoot $tag
+if (Test-Path $targetDir) {
+  Remove-Item -Recurse -Force $targetDir
+}
+
+Write-Host "[1/3] Downloading $assetName ..."
+Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $zipPath -Headers @{ 'User-Agent' = 'codepage-bridge-installer' }
+
+Write-Host "[2/3] Extracting release ..."
+Expand-Archive -Path $zipPath -DestinationPath $targetDir -Force
+Remove-Item -Force $zipPath
+
+$packageRoot = Join-Path $targetDir "codepage-bridge-$tag-win32-x64"
+if (-not (Test-Path $packageRoot)) {
+  throw "Expected extracted package directory not found: $packageRoot"
+}
+
+Write-Host "[3/3] Installing extracted release package ..."
+& (Join-Path $packageRoot 'install\install-this-release-windows.ps1') -ServerName $ServerName -Scope $Scope

package/install/install-from-release-unix.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="${1:-latest}"
+SERVER_NAME="${SERVER_NAME:-codepage-bridge}"
+SCOPE="${SCOPE:-user}"
+
+PACKAGE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ENTRY="$PACKAGE_ROOT/dist/src/server.js"
+
+if [ -f "$ENTRY" ]; then
+  echo "Detected an extracted release package in the current directory. Installing from local files..."
+  bash "$PACKAGE_ROOT/install/install-this-release-unix.sh" "$SERVER_NAME"
+  exit 0
+fi
+
+echo "No local extracted release package detected. Downloading from GitHub Release..."
+SCOPE="$SCOPE" SERVER_NAME="$SERVER_NAME" bash "$PACKAGE_ROOT/install/download-release-unix.sh" "$VERSION"

package/install/install-from-release-windows.ps1

@@ -0,0 +1,19 @@
+param(
+  [string]$Version = 'latest',
+  [string]$ServerName = 'codepage-bridge',
+  [string]$Scope = 'user'
+)
+
+$ErrorActionPreference = 'Stop'
+
+$packageRoot = Split-Path -Parent $PSScriptRoot
+$entry = Join-Path $packageRoot 'dist\src\server.js'
+
+if (Test-Path $entry) {
+  Write-Host 'Detected an extracted release package in the current directory. Installing from local files...'
+  & (Join-Path $PSScriptRoot 'install-this-release-windows.ps1') -ServerName $ServerName -Scope $Scope
+  exit 0
+}
+
+Write-Host 'No local extracted release package detected. Downloading from GitHub Release...'
+& (Join-Path $PSScriptRoot 'download-release-windows.ps1') -Version $Version -ServerName $ServerName -Scope $Scope

package/install/install-from-source-unix.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SERVER_NAME="${1:-codepage-bridge}"
+SCOPE="${SCOPE:-user}"
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Required command not found: $1" >&2
+    exit 1
+  }
+}
+
+require_command node
+require_command npm
+require_command claude
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ENTRY="$REPO_ROOT/dist/src/server.js"
+
+echo "[1/4] Installing npm dependencies..."
+npm --prefix "$REPO_ROOT" install
+
+echo "[2/4] Building Codepage Bridge..."
+npm --prefix "$REPO_ROOT" run build
+
+if [ ! -f "$ENTRY" ]; then
+  echo "Build did not produce $ENTRY" >&2
+  exit 1
+fi
+
+echo "[3/4] Registering Claude Code MCP..."
+claude mcp remove "$SERVER_NAME" --scope "$SCOPE" >/dev/null 2>&1 || true
+claude mcp add --scope "$SCOPE" "$SERVER_NAME" -- node "$ENTRY"
+
+echo "[4/4] Verifying MCP connection..."
+claude mcp get "$SERVER_NAME"
+
+echo
+echo "Next required steps:"
+echo "1. Merge examples/claude-config/settings.fragment.json into ~/.claude/settings.json"
+echo "2. Add examples/minimal-project/CLAUDE.md to your project or ~/.claude/CLAUDE.md"
+echo "3. Add a .encoding-rules file to each legacy-encoded project"
+echo "4. Start a new Claude Code session and verify it uses mcp__codepage-bridge__Read/Grep/Edit/Write"

package/install/install-from-source-windows.ps1

@@ -0,0 +1,45 @@
+param(
+  [string]$ServerName = "codepage-bridge",
+  [string]$Scope = "user"
+)
+
+$ErrorActionPreference = "Stop"
+
+function Require-Command($name) {
+  if (-not (Get-Command $name -ErrorAction SilentlyContinue)) {
+    throw "Required command not found: $name"
+  }
+}
+
+Require-Command node
+Require-Command npm
+Require-Command claude
+
+$repoRoot = Split-Path -Parent $PSScriptRoot
+$entry = Join-Path $repoRoot "dist\src\server.js"
+
+Write-Host "[1/4] Installing npm dependencies..."
+npm --prefix $repoRoot install
+
+Write-Host "[2/4] Building Codepage Bridge..."
+npm --prefix $repoRoot run build
+
+if (-not (Test-Path $entry)) {
+  throw "Build did not produce $entry"
+}
+
+Write-Host "[3/4] Registering Claude Code MCP..."
+try {
+  claude mcp remove $ServerName --scope $Scope | Out-Null
+} catch {}
+claude mcp add --scope $Scope $ServerName -- node $entry
+
+Write-Host "[4/4] Verifying MCP connection..."
+claude mcp get $ServerName
+
+Write-Host ""
+Write-Host "Next required steps:" -ForegroundColor Yellow
+Write-Host "1. Merge examples/claude-config/settings.fragment.json into ~/.claude/settings.json"
+Write-Host "2. Add examples/minimal-project/CLAUDE.md to your project or ~/.claude/CLAUDE.md"
+Write-Host "3. Add a .encoding-rules file to each legacy-encoded project"
+Write-Host "4. Start a new Claude Code session and verify it uses mcp__codepage-bridge__Read/Grep/Edit/Write"

package/install/install-this-release-unix.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SERVER_NAME="${1:-codepage-bridge}"
+SCOPE="${SCOPE:-user}"
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || {
+    echo "Required command not found: $1" >&2
+    exit 1
+  }
+}
+
+require_command node
+require_command claude
+
+PACKAGE_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ENTRY="$PACKAGE_ROOT/dist/src/server.js"
+
+if [ ! -f "$ENTRY" ]; then
+  echo "This directory does not look like an extracted Codepage Bridge release package. Missing: $ENTRY" >&2
+  exit 1
+fi
+
+echo "[1/2] Registering Claude Code MCP from this release package..."
+claude mcp remove "$SERVER_NAME" --scope "$SCOPE" >/dev/null 2>&1 || true
+claude mcp add --scope "$SCOPE" "$SERVER_NAME" -- node "$ENTRY"
+
+echo "[2/2] Verifying MCP connection..."
+claude mcp get "$SERVER_NAME"
+
+echo
+echo "Installed $SERVER_NAME from the current extracted release package."
+echo "Next required steps:"
+echo "1. Merge examples/claude-config/settings.fragment.json into ~/.claude/settings.json"
+echo "2. Add CLAUDE.md policy from examples/minimal-project/CLAUDE.md"
+echo "3. Add a .encoding-rules file to each legacy-encoded project"

package/install/install-this-release-windows.ps1

@@ -0,0 +1,36 @@
+param(
+  [string]$ServerName = 'codepage-bridge',
+  [string]$Scope = 'user'
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Require-Command($name) {
+  if (-not (Get-Command $name -ErrorAction SilentlyContinue)) {
+    throw "Required command not found: $name"
+  }
+}
+
+Require-Command node
+Require-Command claude
+
+$packageRoot = Split-Path -Parent $PSScriptRoot
+$entry = Join-Path $packageRoot 'dist\src\server.js'
+
+if (-not (Test-Path $entry)) {
+  throw "This directory does not look like an extracted Codepage Bridge release package. Missing: $entry"
+}
+
+Write-Host "[1/2] Registering Claude Code MCP from this release package..."
+try { claude mcp remove $ServerName --scope $Scope | Out-Null } catch {}
+claude mcp add --scope $Scope $ServerName -- node $entry
+
+Write-Host "[2/2] Verifying MCP connection..."
+claude mcp get $ServerName
+
+Write-Host ""
+Write-Host "Installed $ServerName from the current extracted release package." -ForegroundColor Green
+Write-Host "Next required steps:" -ForegroundColor Yellow
+Write-Host "1. Merge examples/claude-config/settings.fragment.json into ~/.claude/settings.json"
+Write-Host "2. Add CLAUDE.md policy from examples/minimal-project/CLAUDE.md"
+Write-Host "3. Add a .encoding-rules file to each legacy-encoded project"

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "codepage-bridge-mcp",
+  "version": "0.1.0",
+  "description": "Encoding-transparent MCP file tools for legacy codepages in Claude Code",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "codepage-bridge-mcp": "dist/src/server.js"
+  },
+  "files": [
+    "dist/src/",
+    "LICENSE",
+    "README.md",
+    "README_CN.md",
+    "examples/",
+    "install/",
+    ".claude-plugin/",
+    ".mcp.json"
+  ],
+  "scripts": {
+    "clean": "node -e \"const fs=require('fs'); fs.rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "start": "node dist/src/server.js",
+    "prepublishOnly": "npm run check && npm test && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skyispainted/codepage-bridge-mcp.git"
+  },
+  "homepage": "https://github.com/skyispainted/codepage-bridge-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/skyispainted/codepage-bridge-mcp/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "encoding",
+    "gbk",
+    "legacy-codepage",
+    "grep",
+    "read",
+    "edit",
+    "write"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.0",
+    "diff": "^8.0.2",
+    "iconv-lite": "^0.6.3",
+    "picomatch": "^4.0.3",
+    "sharp": "^0.34.3"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.2",
+    "@types/node": "^24.0.15",
+    "@types/picomatch": "^4.0.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}