base64-file-mcp 1.0.0__tar.gz

base64_file_mcp-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.pytest_cache/
+.pytest_tmp/
+__pycache__/
+*.py[cod]
+*.egg-info/
+out/
+ContractAgentRuns/
+ContractAgentProfiles/
+
+# 配置/参考目录（含 COS 密钥等敏感文件，勿提交）
+config/

base64_file_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: base64-file-mcp
+Version: 1.0.0
+Summary: MCP 插件：将 Base64 编码字符串解码为 docx、pdf、png 等任意格式文件
+Author: CM-Pub
+License: MIT
+Keywords: base64,converter,docx,file,mcp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# base64-file-mcp
+
+MCP 插件：将 Base64 编码字符串解码为任意格式文件（docx、xlsx、pdf、png、jpg、txt 等）。
+
+## 3 个工具函数
+
+| 工具名 | 功能 |
+|--------|------|
+| `base64_to_file` | Base64 → 文件，写入磁盘，返回文件路径和元数据 |
+| `base64_to_file_and_return_b64` | Base64 → 文件 + 写入磁盘 + 同时返回 Base64 数据 |
+| `file_to_base64` | 读取本地文件 → 编码为 Base64 字符串 |
+
+## 在商道平台导入（推荐方式）
+
+在商道平台的 MCP 插件配置中，使用 uvx 命令导入：
+
+```
+uvx --from base64-file-mcp base64-to-file
+```
+
+商道平台会自动发现并注册 3 个工具函数。
+
+## 本地测试
+
+```bash
+# 1. 安装 uv（如果未安装）
+pip install uv
+
+# 2. 直接通过 uvx 运行（不需要提前安装）
+uvx --from base64-file-mcp base64-to-file
+
+# 3. 或先安装再运行
+uv pip install -e .
+base64-to-file
+```
+
+## MCP STDIO 协议交互示例
+
+运行后，MCP 服务器通过 stdin/stdout 与平台通信。以下是手动测试步骤：
+
+```bash
+# 列出工具
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx --from base64-file-mcp base64-to-file
+```
+
+## 输出说明
+
+`base64_to_file` 工具返回的 JSON：
+
+```json
+{
+  "success": true,
+  "file_path": "C:\\Users\\...\\base64_to_file_xxx\\报告.docx",
+  "file_name": "报告.docx",
+  "file_size": 24576,
+  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "output_dir": "C:\\Users\\...\\base64_to_file_xxx"
+}
+```
+
+## 支持的文件格式
+
+通过 `file_name` 参数的扩展名自动识别，支持但不限于：
+
+- 文档：`.docx` `.xlsx` `.pptx` `.pdf` `.txt` `.md` `.csv`
+- 图片：`.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg`
+- 压缩包：`.zip` `.tar` `.gz`
+- 音视频：`.mp4` `.mp3`
+- 其他任意二进制格式

base64_file_mcp-1.0.0/README.md

@@ -0,0 +1,69 @@
+# base64-file-mcp
+
+MCP 插件：将 Base64 编码字符串解码为任意格式文件（docx、xlsx、pdf、png、jpg、txt 等）。
+
+## 3 个工具函数
+
+| 工具名 | 功能 |
+|--------|------|
+| `base64_to_file` | Base64 → 文件，写入磁盘，返回文件路径和元数据 |
+| `base64_to_file_and_return_b64` | Base64 → 文件 + 写入磁盘 + 同时返回 Base64 数据 |
+| `file_to_base64` | 读取本地文件 → 编码为 Base64 字符串 |
+
+## 在商道平台导入（推荐方式）
+
+在商道平台的 MCP 插件配置中，使用 uvx 命令导入：
+
+```
+uvx --from base64-file-mcp base64-to-file
+```
+
+商道平台会自动发现并注册 3 个工具函数。
+
+## 本地测试
+
+```bash
+# 1. 安装 uv（如果未安装）
+pip install uv
+
+# 2. 直接通过 uvx 运行（不需要提前安装）
+uvx --from base64-file-mcp base64-to-file
+
+# 3. 或先安装再运行
+uv pip install -e .
+base64-to-file
+```
+
+## MCP STDIO 协议交互示例
+
+运行后，MCP 服务器通过 stdin/stdout 与平台通信。以下是手动测试步骤：
+
+```bash
+# 列出工具
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx --from base64-file-mcp base64-to-file
+```
+
+## 输出说明
+
+`base64_to_file` 工具返回的 JSON：
+
+```json
+{
+  "success": true,
+  "file_path": "C:\\Users\\...\\base64_to_file_xxx\\报告.docx",
+  "file_name": "报告.docx",
+  "file_size": 24576,
+  "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "output_dir": "C:\\Users\\...\\base64_to_file_xxx"
+}
+```
+
+## 支持的文件格式
+
+通过 `file_name` 参数的扩展名自动识别，支持但不限于：
+
+- 文档：`.docx` `.xlsx` `.pptx` `.pdf` `.txt` `.md` `.csv`
+- 图片：`.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg`
+- 压缩包：`.zip` `.tar` `.gz`
+- 音视频：`.mp4` `.mp3`
+- 其他任意二进制格式

base64_file_mcp-1.0.0/base64_file_mcp/__init__.py

@@ -0,0 +1,271 @@
+"""base64 → 文件 转换 MCP 服务器。
+
+将 Base64 编码字符串解码为 docx、pdf、png 等任意格式文件。
+以 STDIO 传输方式运行，供商道平台通过 uvx 拉取调用。
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import tempfile
+import uuid
+from pathlib import Path
+from typing import Any
+
+from mcp.server import Server, NotificationOptions
+from mcp.server.models import InitializationOptions
+from mcp.types import EmbeddedResource, ImageContent, TextContent, Tool
+
+import mcp.server.stdio
+
+# ── 常量 ────────────────────────────────────────────────────────────
+
+SERVER_NAME = "base64-to-file"
+SERVER_VERSION = "1.0.0"
+
+# ── MCP Server 实例 ─────────────────────────────────────────────────
+
+server = Server(SERVER_NAME)
+
+
+# ── 辅助函数 ─────────────────────────────────────────────────────────
+
+def _safe_filename(file_name: str) -> str:
+    """清理文件名，防止路径穿越。"""
+    name = Path(file_name).name
+    if not name:
+        name = f"output_{uuid.uuid4().hex[:8]}"
+    return name
+
+
+def _guess_mime(ext: str) -> str:
+    """根据扩展名猜测 MIME 类型。"""
+    mime_map = {
+        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        ".pdf": "application/pdf",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".svg": "image/svg+xml",
+        ".txt": "text/plain",
+        ".md": "text/markdown",
+        ".json": "application/json",
+        ".xml": "application/xml",
+        ".csv": "text/csv",
+        ".zip": "application/zip",
+        ".tar": "application/x-tar",
+        ".gz": "application/gzip",
+        ".mp4": "video/mp4",
+        ".mp3": "audio/mpeg",
+    }
+    return mime_map.get(ext.lower(), "application/octet-stream")
+
+
+# ── 工具定义 ─────────────────────────────────────────────────────────
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="base64_to_file",
+            description="将Base64编码的字符串解码为二进制文件并写入磁盘。"
+                        "支持任意文件格式（docx、xlsx、pdf、png、jpg、txt 等），"
+                        "通过 file_name 参数的扩展名自动识别格式。",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "b64_str": {
+                        "type": "string",
+                        "description": "Base64编码的文件数据字符串",
+                    },
+                    "file_name": {
+                        "type": "string",
+                        "description": "输出文件名（含扩展名），如 报告.docx、photo.png",
+                        "default": "output.docx",
+                    },
+                    "output_dir": {
+                        "type": "string",
+                        "description": "输出目录（可选，默认使用平台临时目录）",
+                    },
+                },
+                "required": ["b64_str"],
+            },
+        ),
+        Tool(
+            name="base64_to_file_and_return_b64",
+            description="将Base64编码的字符串解码后，同时写入磁盘并返回文件内容（Base64编码）和元数据。"
+                        "适用于既需要文件落盘又需要将数据回传给调用方的场景。",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "b64_str": {
+                        "type": "string",
+                        "description": "Base64编码的文件数据字符串",
+                    },
+                    "file_name": {
+                        "type": "string",
+                        "description": "输出文件名（含扩展名），如 报告.docx",
+                        "default": "output.docx",
+                    },
+                    "output_dir": {
+                        "type": "string",
+                        "description": "输出目录（可选，默认使用平台临时目录）",
+                    },
+                },
+                "required": ["b64_str"],
+            },
+        ),
+        Tool(
+            name="file_to_base64",
+            description="读取本地文件并将其内容编码为Base64字符串。"
+                        "用于将已有文件编码为Base64以便在其他工具中传输。",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "file_path": {
+                        "type": "string",
+                        "description": "要读取的本地文件路径",
+                    },
+                },
+                "required": ["file_path"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(
+    name: str, arguments: dict[str, Any]
+) -> list[TextContent | ImageContent | EmbeddedResource]:
+    if name == "base64_to_file":
+        return await _handle_base64_to_file(arguments, return_b64=False)
+    elif name == "base64_to_file_and_return_b64":
+        return await _handle_base64_to_file(arguments, return_b64=True)
+    elif name == "file_to_base64":
+        return await _handle_file_to_base64(arguments)
+    else:
+        raise ValueError(f"未知工具: {name}")
+
+
+async def _handle_base64_to_file(
+    arguments: dict[str, Any], return_b64: bool = False
+) -> list[TextContent]:
+    b64_str: str = arguments.get("b64_str", "")
+    file_name: str = arguments.get("file_name", "output.docx")
+    output_dir: str | None = arguments.get("output_dir")
+
+    if not b64_str:
+        return [TextContent(type="text", text=json.dumps({
+            "success": False,
+            "error": "b64_str 参数不能为空",
+        }, ensure_ascii=False))]
+
+    safe_name = _safe_filename(file_name)
+    ext = Path(safe_name).suffix
+
+    try:
+        # 容忍 base64 中可能出现的换行/空格
+        compact = "".join(b64_str.split())
+        file_bytes = base64.b64decode(compact, validate=False)
+    except Exception as e:
+        return [TextContent(type="text", text=json.dumps({
+            "success": False,
+            "error": f"Base64解码失败: {str(e)}",
+        }, ensure_ascii=False))]
+
+    if output_dir:
+        out_dir = Path(output_dir)
+        out_dir.mkdir(parents=True, exist_ok=True)
+    else:
+        out_dir = Path(tempfile.mkdtemp(prefix="base64_to_file_"))
+
+    output_path = out_dir / safe_name
+    output_path.write_bytes(file_bytes)
+
+    file_size = len(file_bytes)
+    mime_type = _guess_mime(ext)
+
+    result: dict[str, Any] = {
+        "success": True,
+        "file_path": str(output_path.resolve()),
+        "file_name": safe_name,
+        "file_size": file_size,
+        "mime_type": mime_type,
+        "output_dir": str(out_dir.resolve()),
+    }
+
+    if return_b64:
+        result["b64_str"] = base64.b64encode(file_bytes).decode("ascii")
+
+    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False))]
+
+
+async def _handle_file_to_base64(
+    arguments: dict[str, Any]
+) -> list[TextContent]:
+    file_path: str = arguments.get("file_path", "")
+
+    if not file_path:
+        return [TextContent(type="text", text=json.dumps({
+            "success": False,
+            "error": "file_path 参数不能为空",
+        }, ensure_ascii=False))]
+
+    path = Path(file_path)
+    if not path.exists():
+        return [TextContent(type="text", text=json.dumps({
+            "success": False,
+            "error": f"文件不存在: {file_path}",
+        }, ensure_ascii=False))]
+
+    if not path.is_file():
+        return [TextContent(type="text", text=json.dumps({
+            "success": False,
+            "error": f"路径不是文件: {file_path}",
+        }, ensure_ascii=False))]
+
+    file_bytes = path.read_bytes()
+    b64_str = base64.b64encode(file_bytes).decode("ascii")
+    mime_type = _guess_mime(path.suffix)
+
+    return [TextContent(type="text", text=json.dumps({
+        "success": True,
+        "file_path": str(path.resolve()),
+        "file_name": path.name,
+        "file_size": len(file_bytes),
+        "mime_type": mime_type,
+        "b64_str": b64_str,
+    }, ensure_ascii=False))]
+
+
+# ── 入口 ─────────────────────────────────────────────────────────────
+
+def main():
+    """MCP 服务器入口函数（供 uvx / CLI 调用）。"""
+    import anyio
+
+    async def _run():
+        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name=SERVER_NAME,
+                    server_version=SERVER_VERSION,
+                    capabilities=server.get_capabilities(
+                        notification_options=NotificationOptions(),
+                        experimental_capabilities={},
+                    ),
+                ),
+            )
+
+    anyio.run(_run)
+
+
+if __name__ == "__main__":
+    main()

base64_file_mcp-1.0.0/base64_file_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""支持 `python -m base64_file_mcp` 直接运行。"""
+
+from base64_file_mcp import main
+
+if __name__ == "__main__":
+    main()

base64_file_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "base64-file-mcp"
+version = "1.0.0"
+description = "MCP 插件：将 Base64 编码字符串解码为 docx、pdf、png 等任意格式文件"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "CM-Pub" },
+]
+keywords = ["mcp", "base64", "docx", "file", "converter"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "anyio>=4.0",
+]
+
+[project.scripts]
+base64-to-file = "base64_file_mcp:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["base64_file_mcp"]