使用说明（Markdown格式）

项目简介

Box Agentic MCP 服务器是一套基于 MCP 的后端服务，旨在通过统一的 JSON-RPC 风格接口向 LLM 客户端提供对资源、工具和提示相关功能的访问。核心功能包括：

• 资源/内存管理：在 Box 文件夹中读写代理内存（.agent_memory.json）。
• 安全沙箱（Shadow）与变更提交：通过 [SHADOW] 子文件夹实现安全 staging，提交前需获得明确授权。
• 审计日志（Ledger）：对每次操作记录详细的时间戳、模型、提示与推理等元数据，支持合规追溯。
• MCP 工具暴露：通过 MCP 服务暴露上述功能，LLM 客户端可通过调用相应工具实现任务传递、内存查询、阴影操作等。

主要功能点

• MCP 服务端：提供 FastMCP 实例，注册并暴露多个工具接口。
• memory（内存层）：在 Box 文件夹层级读写 .agent_memory.json，供多轮对话、任务切换使用。
• shadow（沙箱层）：在目标文件夹内创建 [SHADOW] 子文件夹，复制生产文件以供安全修改，提交时可回写生产环境。
• ledger（审计层）：将操作以日志形式写入 .reasoning_ledger.log，包含时间、动作、提示、模型和推理等信息。
• API 入口与 demos：虽然核心实现通过 MCP 提供工具，但仓库还包含演示脚本和单元测试，便于验证内存/日志等核心能力。

安装与运行步骤（简要）

• 确保 Python 3.11+ 环境。
• 安装依赖（如 Box SDK、MCP 依赖等）。
• 配置 Box 账户凭据（.env 文件中设置 BOX_CLIENT_ID、BOX_CLIENT_SECRET、BOX_ACCESS_TOKEN 等）。
• 启动 MCP 服务器：通常使用命令运行模块，例如 python -m box_agentic_mesh.mcp_server（具体命令以实际发布环境为准）。
• MCP 客户端连接：MCP 客户端应按照配置格式（下方“服务器配置 JSON 示例”所示）告知服务器名称、启动命令与参数，以建立连接并调用工具。

服务器配置（MCP 客户端使用的连接配置，示例为 JSON 结构，非代码）

{ "server_name": "BoxAgenticMeshMCPServer", "command": "python", "args": ["-m", "box_agentic_mesh.mcp_server"] // 说明： // - server_name：MCP 服务端在客户端侧显示的名称，用于标识不同的 MCP 服务器。 // - command：启动服务器所用的命令，通常为解释器/执行入口。 // - args：上述命令的参数，包含模块路径等信息。 // 客户端不需要包含服务器端实现细节，仅需提供上述即可与 MCP 服务器建立通信。 }

基本使用方法

• 启动服务器后，客户端通过 MCP 协议向服务器发送工具调用请求，例如读取内存、写入内存、创建阴影、提交阴影和写入审计日志等。
• 使用内存工具进行任务传递与状态保存；使用阴影工具进行安全的文件修改；使用审计日志记录每次操作的上下文和推理。
• 观察输出与日志以确认操作成功与审计信息完整性。

运行与调试建议

• 在测试环境中模拟 Box 文件夹结构（含 .agent_memory.json、.reasoning_ledger.log、[SHADOW] 等）以验证读写、复制、提交等行为。
• 使用单元测试确认 memory 模块的读写路径在不同场景下的健壮性。
• 确保环境变量（Box 的凭据、文件夹 ID 等）正确无误，以避免授权失败。

额外说明

• MCP 模块的具体实现依赖 mcp.server.fastmcp，服务端工具通过装饰器 @app.tool() 暴露给客户端。
• 项目定位为 AI 助手的中间层/后端服务，主要围绕“内存、沙箱、审计”三大能力，便于 LLM 客户端以一致的接口进行上下文管理和功能扩展。