j-mcp-code-bettler

MCP 服务器，提供支持字符集的文件读写和编辑工具，用于解决 AI 编程工具（如 Joycode）读取 GBK 等非 UTF-8 编码文件时的乱码问题。

功能特性

• ✅ 支持 GBK、GB2312、GB18030、UTF-8、BIG5 等多种字符集
• ✅ read_file - 读取文件时指定字符集
• ✅ write_file - 写入文件时指定字符集
• ✅ search_replace - 搜索并替换文本
• ✅ edit_apply_diff - 精确的差异编辑
• ✅ list_files - 列出目录内容（支持递归）
• ✅ detect_charset - 自动检测文件字符集（实验性）
• ✅ 字符集名称大小写不敏感（gbk、GBK 都可以）

Code Rule：百补项目编码字符集

项目规则要求如下：

AI Coding 读写代码编码规则

• 强制使用 MCP 工具 j-mcp-code-bettler 进行读取、写入、编辑、替换文档内容，并且强制指定 GBK 编码，防止乱码

| 工具 | 用途 | charset 默认值 | |------|------|----------------| | read_file | 读取文件内容 | gbk | | write_file | 写入/创建新文件 | gbk | | search_replace | 搜索并替换文本 | gbk | | edit_apply_diff | 精确的差异编辑 | gbk | | list_files | 列出目录内容 | - |

快速开始

方式一：从源码安装（推荐）

这种方式性能最好，MCP 服务保持长期运行，不需要每次都启动新进程。

git clone <repo-url>
cd j-mcp-code-bettler
npm link

在 .joycode/joycode-mcp.json 中配置：

{
  "mcpServers": {
    "j-mcp-code-bettler": {
      "command": "j-mcp",
      "args": [],
      "type": "stdio",
      "transportType": "stdio",
      "autoApprove": [
        "read_file",
        "write_file",
        "detect_charset",
        "edit_apply_diff"
      ]
    }
  }
}

方式二：全局安装 CLI

npm install -g @philpi/j-mcp-code-bettler

配置同上，使用 j-mcp 命令。

方式三：npx 直接运行

如果不想安装，直接使用 npx 运行：

{
  "mcpServers": {
    "j-mcp-code-bettler": {
      "command": "npx",
      "args": ["-y", "@philpi/j-mcp-code-bettler"],
      "type": "stdio",
      "transportType": "stdio",
      "autoApprove": [
        "read_file",
        "write_file",
        "detect_charset",
        "edit_apply_diff"
      ]
    }
  }
}

注意：npx 方式每次连接都会启动新进程，首次连接较慢。

npx 拉取新版本：npx 默认会缓存包，如需强制拉取最新版本，可以：

• 指定版本号：args: ["-y", "@philpi/[email protected]"]
• 每次拉最新：args: ["-y", "@philpi/j-mcp-code-bettler@latest"]
• 或清除缓存：npx cache clean

如果你用的是源码安装方式 (npm link)，修改代码后需要重新 npm run build 编译才能生效。

工具使用示例

read_file - 读取文件

{
  "name": "read_file",
  "arguments": {
    "path": "/path/to/file.java",
    "charset": "GBK"
  }
}

write_file - 写入文件

{
  "name": "write_file",
  "arguments": {
    "path": "/path/to/file.java",
    "content": "你好世界",
    "charset": "GBK"
  }
}

edit_apply_diff - 编辑文件（替换内容）

{
  "name": "edit_apply_diff",
  "arguments": {
    "path": "/path/to/file.java",
    "search": "要替换的内容",
    "replace": "替换后的内容",
    "charset": "GBK",
    "use_regex": false,
    "ignore_case": false
  }
}

search_replace - 搜索并替换文本

{
  "name": "search_replace",
  "arguments": {
    "path": "/path/to/file.java",
    "search": "要搜索的内容",
    "replace": "替换后的内容",
    "charset": "GBK",
    "ignore_case": false
  }
}

list_files - 列出目录内容

{
  "name": "list_files",
  "arguments": {
    "path": "/path/to/directory",
    "recursive": false
  }
}

detect_charset - 检测字符集

{
  "name": "detect_charset",
  "arguments": {
    "path": "/path/to/file.java"
  }
}

参数说明

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | 是 | 文件路径 | | charset | string | 否 | 字符集，默认 UTF-8 | | content | string | write_file 必填 | 要写入的内容 | | search | string | edit_apply_diff 必填 | 要搜索的内容 | | replace | string | edit_apply_diff 必填 | 替换后的内容 | | use_regex | boolean | 否 | 是否使用正则表达式，默认 false | | ignore_case | boolean | 否 | 是否忽略大小写，默认 false |

支持的字符集

• UTF-8 / UTF8（默认）
• GBK / gbk
• GB2312 / gb2312
• GB18030 / gb18030
• BIG5 / big5
• ISO-8859-1 / iso-8859-1
• ASCII / ascii
• Shift_JIS / shift_jis
• EUC-JP / euc-jp

背景

在使用 Idea 插件 Joycode 进行 AI 编程时，老项目使用 GBK 编码，而 Joycode 默认使用 UTF-8 读取文件，导致中文乱码。本 MCP 服务提供带字符集参数的文件读写工具，解决该问题。

项目结构

j-mcp-code-bettler/
├── src/
│   ├── index.ts          # MCP 服务器主入口
│   ├── tools.ts          # MCP 工具定义和实现
│   └── utils.ts          # 字符集转换工具类
├── dist/                 # 编译后的 JavaScript
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md            # 项目文档

技术栈

• TypeScript
• Node.js
• @modelcontextprotocol/sdk (MCP SDK)
• iconv-lite (字符集转换)

注意事项

1. 字符集检测是实验性的：detect_charset 工具基于内容分析，可能不够准确。建议明确指定字符集。

2. 路径处理：支持绝对路径和相对路径，会自动规范化。

3. 目录自动创建：写入文件时，如果父目录不存在，会自动创建。

4. 字符集大小写不敏感：传入 gbk、GBK、Gbk 都可以正常工作。

License

ISC