MCP 服务器（Claude Desktop / Claude Code）

automation_file 自带一个 Model Context Protocol（MCP）服务器，将共享的 ActionRegistry 中的每一项暴露为 MCP 工具。Claude Desktop、Claude Code 以及其他 MCP 宿主，可以像调用普通 MCP 工具一样调用 FA_* 动作—— 无需自写插件，无需额外打包。

传输方式为 **stdio**（stdin / stdout 上每行一条 JSON-RPC 2.0 消息），与目前 MCP 宿主使用的协议一致。

提供的能力

initialize 握手，返回协议版本 2024-11-05、 serverInfo.name 与 serverInfo.version。
tools/list 为每个已注册的 FA_* 动作返回一个 MCP 工具描述，其参数 JSON Schema 由 Python 函数签名自动派生（str → "string"、int → "integer" 等）。
tools/call 通过注册表派发，并以 JSON 编码后的文本内容块返回结果。
--allowed-actions 允许列表参数，让你只把注册表的子集暴露给宿主。
所有内部错误都会以 JSON-RPC 错误对象形式返回—— 宿主无需解析异常字符串即可呈现错误。

启动服务器

CLI:

python -m automation_file mcp
python -m automation_file mcp --name automation_file --version 1.0.0
python -m automation_file mcp --allowed-actions FA_list_dir,FA_file_checksum

进程在前台运行，从 stdin 读取分行 JSON 并把响应写到 stdout。通常宿主会替你启动该进程，不需要手工运行。

从 Python 启动（例如嵌入到自家 stdio 桥接器里）：

from automation_file import MCPServer

server = MCPServer(name="automation_file", version="1.0.0")
server.serve_stdio()        # stdin 关闭前阻塞

通过自定义注册表把可调用动作面缩小：

from automation_file import MCPServer
from automation_file.core.action_registry import ActionRegistry
from automation_file import executor

safe = ActionRegistry()
for name in ("FA_list_dir", "FA_file_checksum", "FA_fast_find"):
    safe.register(name, executor.registry.resolve(name))

MCPServer(safe).serve_stdio()

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）的 mcpServers 下添加条目：

{
  "mcpServers": {
    "automation_file": {
      "command": "python",
      "args": ["-m", "automation_file", "mcp"]
    }
  }
}

重启 Claude Desktop。automation_file 服务器会出现在工具面板中，所有 FA_* 动作都可被调用。

对于操作敏感路径的宿主，建议把可用动作锁死为白名单：

{
  "mcpServers": {
    "automation_file": {
      "command": "python",
      "args": [
        "-m", "automation_file", "mcp",
        "--allowed-actions",
        "FA_list_dir,FA_fast_find,FA_file_checksum,FA_verify_checksum"
      ]
    }
  }
}

显式指定虚拟环境的解释器（避免误用系统 Python）：

{
  "mcpServers": {
    "automation_file": {
      "command": "C:\\envs\\fa\\Scripts\\python.exe",
      "args": ["-m", "automation_file", "mcp"]
    }
  }
}

Claude Code 配置

Claude Code 使用同一份 MCP 定义。可通过 claude mcp add CLI 注册:

claude mcp add automation_file -- python -m automation_file mcp

或在仓库根目录提交 .mcp.json：

{
  "mcpServers": {
    "automation_file": {
      "command": "python",
      "args": ["-m", "automation_file", "mcp"]
    }
  }
}

加载完成后，要求 Claude Code 使用 mcp__automation_file__FA_* 工具—— 例如「使用 FA_fast_find 找出 ./var 下所有 *.log」。

查看工具目录

可渲染与宿主完全一致的描述符——便于测试、GUI 调试或生成文档：

from automation_file import tools_from_registry, executor

for tool in tools_from_registry(executor.registry):
    print(tool["name"], "->", tool["description"])

每个描述符的形状如下:

{
  "name": "FA_fast_find",
  "description": "底层可调用对象的第一行 docstring。",
  "inputSchema": {
    "type": "object",
    "properties": {"root": {"type": "string"}, "pattern": {"type": "string"}},
    "required": ["root", "pattern"],
    "additionalProperties": true,
  },
}

手工烟雾测试

直接把 JSON-RPC 帧喂给服务器以确认其能正常加载:

printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"FA_fast_find","arguments":{"root":".","pattern":"*.py","limit":3}}}' \
  | python -m automation_file mcp

每行输入在 stdout 上恰得到一条 JSON-RPC 响应（通知没有响应）。

安全注意事项

MCP 服务器以 启动它的 Python 进程的权限 运行。每次工具调用都落在你 shell 用户账户里。
默认情况下，服务器暴露全部已注册的 FA_* 动作，其中包含会删除文件、写文件系统、上传到远程后端的动作。对任何不完全可信的宿主，请用 --allowed-actions 只白名单暴露必要的动作。
在打算给第三方宿主使用的 MCP 服务器启动前，不要调用 add_package_to_executor() （或暴露其动作）。该助手会注册任意包的全部顶层函数 / 类 / 内置，权限相当于 eval。
服务器启动时会通过 file_automation_logger 以 INFO 级别记录暴露的工具数量与配置的服务器名称。工具调用负载从不被记录。
涉及对外 HTTP 的动作（FA_download_file、各云后端）仍会通过 SSRF 校验；MCP 层不会放宽任何单动作检查。