agent-file-control MCP Server

English | 中文

完整的文件控制 MCP 服务器，基于 Node.js/TypeScript 实现。支持三种内容写入模式，灵活处理各种文件操作场景，包括 Unicode 字符问题。

安装

npm install -g agent-file-control-mcp-server

# 或使用 npx 无需安装
npx -y agent-file-control-mcp-server

核心特性：三种写入模式

所有写入类工具支持三种编码方式：

⚠️ Unicode 字符问题

Go/Python/TypeScript 代码中的 Unicode 字符（如 \u25cf → ●、\u2713 → ✓）在 JSON-RPC 传输时会出问题：

问题根源：

• Agent 生成的 "value": "●" → JSON 序列化 → "value": "\\u25cf" → 文件内容错误
• Base64 模式也无法解决，因为问题发生在 JSON 序列化阶段，而非传输阶段

解决方案：生成器模式

• Agent 只传递简单的 key-value 参数（如 { "name": "radioOn", "value": "●" }）
• MCP server 在内部生成文件内容
• 完全绕过 JSON 序列化问题

配置方法

OpenCode 配置

编辑 ~/.config/opencode/opencode.json，在 mcp 字段中添加：

{
  "mcp": {
    "agent-file-control": {
      "type": "local",
      "command": ["npx", "-y", "agent-file-control-mcp-server"],
      "enabled": true
    }
  }
}

Claude Code 配置

编辑 ~/.claude.json 或 ~/.mcp.json，添加 mcpServers 字段：

{
  "mcpServers": {
    "agent-file-control": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "agent-file-control-mcp-server"],
      "env": {}
    }
  }
}

或使用命令行：

claude mcp add agent-file-control -- npx -y agent-file-control-mcp-server

可用工具

文件生成器（优先使用）

文件写入

文件编辑

文件读取

文件管理

编码工具

内置生成器

查看生成器详情：调用 afc_list_generators(detailed=true)

使用示例

生成器模式 - Unicode 字符（推荐）

// 生成 Go 常量文件，包含 Unicode 符号
{
  "path": "/path/to/styles.go",
  "generator": "go-constants",
  "input": {
    "package": "tui",
    "constants": [
      { "name": "radioOn", "value": "●", "comment": "选中状态" },
      { "name": "radioOff", "value": "○", "comment": "未选中状态" },
      { "name": "cursorStr", "value": "▸ " },
      { "name": "checkMark", "value": "✓" }
    ]
  }
}

// 生成的文件内容：
// package tui
// 
// const (
//     radioOn   = "●" // 选中状态
//     radioOff  = "○" // 未选中状态
//     cursorStr = "▸ "
//     checkMark = "✓"
// )

生成器模式 - 结构体

// 生成 Go 结构体
{
  "path": "/path/to/config.go",
  "generator": "go-struct",
  "input": {
    "package": "config",
    "structName": "Server",
    "fields": [
      { "name": "Host", "type": "string", "jsonTag": "host" },
      { "name": "Port", "type": "int", "jsonTag": "port" }
    ]
  }
}

Text 模式 - 简单文本

// 写入简单文本
{
  "path": "/home/user/test.txt",
  "content": "Hello World",
  "content_encoding": "text"
}

Base64 模式 - 复杂代码（无 Unicode）

// 写入复杂 JavaScript 代码
{
  "path": "/home/user/code.js",
  "content": "Y29uc3QgeCA9ICJoZWxsbztcblxuY29uc29sZS5sb2coeCk7",
  "content_encoding": "base64"
}

// 先调用 afc_encode_string 生成 base64：
{
  "text": "const x = \"hello\";\nconsole.log(x);"
}
// 返回: Y29uc3QgeCA9ICJoZWxsbztcblxuY29uc29sZS5sb2coeCk7

模式选择决策

生成器工作原理

Agent 调用 afc_write_generated({ generator: "go-constants", input: {...} })
    ↓
MCP server 接收参数，在内部生成文件内容
    ↓
直接写入文件（绕过 JSON 序列化）

关键优势：

• Agent 只传简单 key-value 数据
• MCP server 内部处理复杂内容生成
• Unicode 字符直接写入文件，无转义问题

管理命令

# Claude Code
claude mcp list
claude mcp get agent-file-control
claude mcp remove agent-file-control -s user

# 在 Claude Code 中检查状态
/mcp

License

MIT © LeenixP