金大哥 - all-your-base64 MCP 详情

article

README

🚀 All Your Base64

这是一款现代、高效且专门设计的命令行工具，可将任何可能的输入文件转换为 Base64 字符串，并提供全面的输出选项。它采用 TypeScript 构建，兼顾了性能和开发者体验。

🚀 快速开始

# 编码文件
ayb64 encode myfile.jpg

# 编码并换行输出
ayb64 encode myfile.jpg --wrap 76

# 生成数据 URI
ayb64 encode image.png --data-uri

# 输出到文件并包含元数据
ayb64 encode document.pdf -o output.b64 --metadata

# 将 Base64 解码回文件
ayb64 decode SGVsbG8sIFdvcmxkIQ== -o hello.txt

# 从标准输入管道输入
echo "Hello, World!" | ayb64 encode

# 获取文件信息
ayb64 info myfile.jpg --json

✨ 主要特性

✨ 现代且快速：采用 TypeScript 构建，性能经过优化。
🔍 智能检测：通过 file-type 和 mime-types 实现行业领先的 MIME 类型检测。
📁 输入多样：支持文件、标准输入和字符串。
🎨 多格式输出：支持原始格式、JSON、JS、TS、CSS、HTML、XML、YAML 和 Markdown。
🔄 双向支持：支持编码和解码。
🛡️ 健壮可靠：具备全面的错误处理和验证机制。
📊 元数据丰富：提供文件信息、哈希值和处理统计数据。
🎯 数据 URI 支持：可生成带有正确 MIME 类型的数据 URI。
🌍 跨平台兼容：支持 macOS、Linux、Windows、Docker 和云环境。

📦 安装指南

全局安装（推荐）

npm install -g ayb64

本地安装

npm install ayb64

使用 npx（无需安装）

npx ayb64 --help
# 或使用简短命令
npx ayb64 --help

💻 使用示例

基础用法

# 编码文件
ayb64 encode myfile.jpg

高级用法

换行输出

ayb64 encode file.txt --wrap 64    # 每行 64 个字符
ayb64 encode file.txt --wrap 76    # 符合 RFC 2045 标准

处理多个文件

# 使用 shell 通配符
for file in *.jpg; do
  ayb64 encode "$file" -o "${file}.b64"
done

# 使用 find 命令
find . -name "*.png" -exec ayb64 encode {} -o {}.b64 \;

管道和重定向

# 从 curl 管道输入
curl -s https://example.com/image.jpg | ayb64 encode --data-uri

# 链式操作
ayb64 encode file.txt | ayb64 decode -o restored.txt

# 与其他工具配合使用
base64 -d encoded.txt | ayb64 encode --format json

📚 详细文档

命令说明

`encode` / `e`

将输入转换为 Base64 格式。

ayb64 encode [input] [options]

参数：

input - 输入文件路径（使用 - 表示标准输入）

选项：

-o, --output <path> - 输出文件路径（默认：标准输出）
-f, --format <format> - 输出格式：raw、json、js、ts、css、html、xml、yaml、md
-w, --wrap <columns> - 在指定列宽处换行输出 Base64 字符串
-d, --data-uri - 生成带有 MIME 类型的数据 URI
-m, --metadata - 输出中包含文件元数据
--no-mime - 禁用 MIME 类型检测
--quiet - 抑制非必要输出

`decode` / `d`

将 Base64 输入解码回原始格式。

ayb64 decode [input] [options]

参数：

input - 输入文件路径或 Base64 字符串（使用 - 表示标准输入）

选项：

-o, --output <path> - 输出文件路径（默认：标准输出）
-m, --metadata - 如有可用元数据则显示
--quiet - 抑制非必要输出

`info` / `i`

显示文件信息和元数据，不进行转换。

ayb64 info <input> [options]

参数：

input - 输入文件路径

选项：

-j, --json - 以 JSON 格式输出

`mcp`

启动用于 AI 代理的模型上下文协议（MCP）服务器。

ayb64 mcp

此命令启动 MCP 服务器，该服务器提供针对 AI 代理和编码工作流优化的 Base64 转换工具。服务器包含内存、作业召回、校验和和专用工具。 无选项 - MCP 服务器作为独立进程通过标准输入输出进行通信。

`batch` / `b`

批量处理多个文件（即将推出）。

ayb64 batch <pattern> [options]

输出格式

原始格式（默认）

ayb64 encode file.txt
# SGVsbG8sIFdvcmxkIQ==

JSON 格式

ayb64 encode file.txt --format json --metadata

{
  "data": "SGVsbG8sIFdvcmxkIQ==",
  "size": 22,
  "metadata": {
    "filename": "file.txt",
    "mimeType": "text/plain",
    "size": 13,
    "hash": "abc123...",
    "processingTime": 2
  }
}

JavaScript/TypeScript 模块

ayb64 encode file.txt --format js --metadata

const base64Data = 'SGVsbG8sIFdvcmxkIQ==';

const metadata = {
  filename: 'file.txt',
  mimeType: 'text/plain',
  size: 13,
};

module.exports = { base64Data, metadata };

数据 URI

ayb64 encode image.png --data-uri
# data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

HTML 文档

ayb64 encode file.txt --format html --metadata

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Base64 Data</title>
  </head>
  <body>
    <div class="base64-data" data-content="SGVsbG8sIFdvcmxkIQ=="></div>
    <div class="metadata">
      <h3>File Information</h3>
      <p><strong>Filename:</strong> file.txt</p>
      <p><strong>MIME Type:</strong> text/plain</p>
      <p><strong>Size:</strong> 13 bytes</p>
    </div>
  </body>
</html>

CSS 自定义属性

ayb64 encode file.txt --format css

.base64-data {
  --base64-content: 'SGVsbG8sIFdvcmxkIQ==';
}

.base64-data::before {
  content: var(--base64-content);
}

MCP 服务器（适用于 AI 代理）

All Your Base64 包含一个强大的 模型上下文协议（MCP）服务器，专为 AI 代理和编码任务进行了优化。MCP 服务器提供内存、作业召回、校验和以检测更改，以及适用于 AI 工作流的专用工具。

MCP 服务器特性

🧠 智能内存：使用 LRU 缓存，可通过 ID 召回作业。
🔍 更改检测：使用 SHA256 校验和检测文件修改。
🤖 AI 优化：专为编码和开发工作流设计的工具。
📋 作业历史：跟踪和召回先前的编码操作。
🔗 数据 URI：为图像和资产生成适用于 Web 的数据 URI。
⚡ 高性能：轻量级、可扩展且健壮。

MCP 服务器工具

encode - 对文件/数据进行编码，支持格式选项和作业跟踪。
decode - 解码 Base64，自动检测并输出文件。
recall - 通过 ID 检索先前的作业，包含完整上下文。
jobs - 列出最近的操作及其元数据。
datauri - 生成针对 Web 开发优化的数据 URI。
memory - 管理作业缓存（统计信息、清除）。

使用 MCP 服务器

启动 MCP 服务器

# 使用 CLI 命令（推荐）
ayb64 mcp

# 直接运行二进制文件
ayb64-mcp

# 开发模式
npm run mcp

# 或通过 npx 运行源代码
npx tsx src/mcp-server.ts

在 MCP 客户端中配置

VS Code/Cursor/Cline（添加到 mcp.json）：

{
  "mcpServers": {
    "ayb64": {
      "command": "ayb64",
      "args": ["mcp"]
    }
  }
}

Claude Desktop：

{
  "mcpServers": {
    "ayb64": {
      "command": "ayb64-mcp"
    }
  }
}

MCP 工作流示例

编码图像以供 Web 使用：

工具：encode
输入：{
  "data": "/path/to/logo.png",
  "isFile": true,
  "format": "js",
  "dataUri": true
}
输出：作业 ID + 包含数据 URI 的 JavaScript 常量

召回先前的作业：

工具：recall
输入：{"jobId": "job_1234567890_abc123"}
输出：包含元数据的完整原始结果

为 CSS 生成数据 URI：

工具：datauri
输入：{"input": "/path/to/background.jpg"}
输出：data:image/jpeg;base64,...（适用于 CSS）

🔧 技术细节

API 参考

文件信息输出

使用 --metadata 选项时，将获得全面的文件信息：

{
  "filename": "example.jpg",
  "mimeType": "image/jpeg",
  "size": 153600,
  "created": "2023-01-01T00:00:00.000Z",
  "modified": "2023-01-02T00:00:00.000Z",
  "hash": "sha256:a1b2c3d4...",
  "processingTime": 15
}

支持的 MIME 类型

该工具使用 file-type 包自动检测文件类型，支持以下类型：

图像：JPEG、PNG、GIF、WebP、SVG、BMP、TIFF、ICO
文档：PDF、DOC、DOCX、XLS、XLSX、PPT、PPTX
存档：ZIP、RAR、7Z、TAR、GZIP、BZIP2
媒体：MP4、AVI、MOV、MP3、WAV、OGG、FLAC
文本：纯文本、HTML、CSS、JavaScript、JSON、XML、YAML、Markdown
字体：TTF、OTF、WOFF、WOFF2、EOT
以及更多...

性能

基准测试

| 文件大小 | 时间 | 内存 | | --------- | ----- | --------- | | 1 KB | 5ms | 0 B | | 1 MB | 8ms | 92.26 KB | | 10 MB | 51ms | 170.35 KB | | 100 MB | 523ms | 257.27 KB | | 200 MB | 1.0s | 447.2 KB |

基准测试在真实硬件上运行：MacBook Pro，2.4 GHz 8 核 Intel Core i9，32GB DDR4，macOS 15.6.1

性能说明：

内存使用显示编码过程中的峰值堆增长。
采用非常节省内存的 Base64 实现。
处理时间随文件大小合理增长。

使用 npm run benchmark 在真实硬件上运行基准测试

优化建议

使用原始格式 以获得最佳性能。
避免使用元数据 进行简单转换。
根据使用场景选择合适的换行设置。
逐个处理文件，而不是批量处理大文件。

配置

环境变量

AYB64_MAX_MEMORY - 最大内存使用阈值
AYB64_QUIET - 默认安静模式设置

配置文件

创建 ~/.ayb64rc.json 以设置默认值：

{
  "format": "raw",
  "wrap": 76,
  "metadata": false
}

集成示例

Node.js 脚本

const { spawn } = require('child_process');

function encodeFile(filePath) {
  return new Promise((resolve, reject) => {
    const child = spawn('ayb64', ['encode', filePath, '--format', 'json']);
    let output = '';

    child.stdout.on('data', (data) => {
      output += data.toString();
    });

    child.on('close', (code) => {
      if (code === 0) {
        resolve(JSON.parse(output));
      } else {
        reject(new Error(`Process exited with code ${code}`));
      }
    });
  });
}

Web 开发

为 CSS 生成数据 URI：

ayb64 encode logo.png --data-uri > logo-data.css

创建 JavaScript 模块：

# 在批量命令实现之前使用 shell 通配符
for file in assets/*.png; do
  ayb64 encode "$file" --format js -o "${file%.png}.js"
done

CI/CD 管道

# GitHub Actions 示例
- name: Encode assets
  run: |
    for file in dist/assets/*; do
      ayb64 encode "$file" --format json --metadata > "$file.json"
    done

错误处理

All Your Base64 提供全面的错误处理和有用的建议：

$ ayb64 encode nonexistent.txt
错误：文件未找到：nonexistent.txt
建议：
  • 检查文件路径是否正确
  • 确保文件存在
  路径：nonexistent.txt

常见错误类型：

文件未找到 - 检查文件路径和权限。
无效的 Base64 - 解码时验证输入格式。
权限被拒绝 - 检查文件/目录权限。
无效的格式 - 使用 --help 查看支持的格式。

故障排除

常见问题

问：“Cannot find module 'file-type'”
答：运行 npm install 安装依赖项。

问：“Permission denied” 错误
答：检查文件权限：chmod +r filename 或使用适当的权限运行。

问：输出损坏
答：确保在 shell/终端中正确处理二进制数据。

调试模式

设置调试环境变量以获取详细输出：

DEBUG=ayb64:* ayb64 encode file.txt

📄 许可证

本项目采用 MIT 许可证，版权归 Joe Peterson 所有。

致谢

MIME 类型检测支持

All Your Base64 借助了开源社区的优秀成果来实现强大的文件类型检测：

🔍 file-type 由 Sindre Sorhus 开发 - 通过魔数检测文件类型的黄金标准。这个出色的包支持 100 多种文件类型，使用二进制签名进行快速检测。
📄 mime-types 由 jshttp 开发 - 全面的 MIME 类型数据库，支持扩展名映射。它是 Node.js 生态系统中 Web 服务器 MIME 处理的基础。

这些包提供了企业级的文件检测功能，独立实现和维护这些功能可能需要数年时间。我们站在了巨人的肩膀上！🚀

开源依赖

本项目基于以下优秀的开源包构建，并对它们表示感谢：

Commander.js - Node.js 命令行界面的完整解决方案。
TypeScript - 带有类型语法的 JavaScript。
Vitest - 由 Vite 驱动的快速单元测试框架。
ESLint - 查找和修复 JavaScript 代码中的问题。
Prettier - 有主见的代码格式化工具。

平台支持

All Your Base64 在多个平台上无缝运行：

🍎 macOS - 原生支持，具备正确的文件系统处理能力。
🐧 Linux - 全部分发版兼容。
🪟 Windows - 支持 PowerShell、命令提示符和 WSL。
📦 Docker - 适用于 CI/CD 管道的容器化支持。
☁️ 云环境 - 支持 AWS Lambda、Google Cloud Functions、Azure Functions。

变更日志

v1.0.0

初始版本发布
核心编码/解码功能
多种输出格式
全面的错误处理
完整的测试覆盖

用心打造 ❤️，咖啡助力 ☕

"起初，有比特，比特与 Base64 同在，比特就是 Base64。"