使用说明（Markdown格式）

概述

本仓库实现了一个符合 MCP 协议的后端服务器，用于向 LLM 客户端提供上下文信息与功能。核心能力包括：

托管和管理资源 (Resources)，提供数据访问能力
注册和执行 Tools（工具），允许外部功能调用
定义和渲染 Prompt 模板，支持多种交互模式
通过 JSON-RPC 与客户端通信，支持命名工具的注册、执行以及工具调用的审批流程
提供多传输协议支持（标准输入输出、流式 HTTP、SSE 等），并具备会话管理和沙箱等安全能力

主要功能点

MCP 服务器核心实现：完整处理 MCP 请求、工具注册、执行、错误处理及结果返回
工具服务器集成：通过 ToolServer 提供对 MCP 服务的调用，并在需要时进行工具调用审批
内嵌 IPython 内核执行：KernelGateway 与 KernelClient 实现代码执行、状态持久化、输出处理和图片生成
账户与会话管理：支持多客户端并发、执行超时、输出截断、以及环境变量注入
安全沙箱支持：可选开启 sandbox 模式以限制网络访问，提升执行安全性
MCP 客户端辅助：提供自动化的 MCP 客户端配置与工具调用封装

安装步骤

准备环境：需要 Python 3.8+ 环境
安装依赖：通过 pip 安装 ipybox 及其依赖（仓库中包含实现代码，无需额外步骤即可使用）
运行 MCP 服务器：方式一（模块运行，推荐）: python -m ipybox.mcp_server --workspace <工作目录> --log-level INFO 方式二（直接脚本运行，若已知绝对路径）: python <工作目录>/mcp_server.py --workspace <工作目录> --log-level INFO

服务器配置（MCP 客户端需要的最小连接信息）

以下 JSON 使用示例展示了集成 MCP 服务器所需的最小字段。MCP 客户端需要提供 server_name、command、args 等信息来启动 MCP 服务器（具体字段说明如下）。

{ "server_name": "test_mcp_server", "server_params": { "command": "python", "args": ["-m", "ipybox.mcp_server", "--workspace", "/path/to/workspace", "--log-level", "INFO"] } }

说明：

server_name: 您将要注册的 MCP 服务器的标识名称，用于在客户端代码中引用。
server_params: 启动 MCP 服务器的参数集合
- command: 启动命令（通常为 python）
- args: 启动参数，可包含 -m ipybox.mcp_server、--workspace、--log-level 等这份配置用于 MCP 客户端与 MCP 服务器建立连接时的参数注入，不同实现场景可以将 workspace 指向实际工作目录，log-level 选择合适的日志详细程度。

基本使用方法

生成工具 API（可选）: 使用仓库中的生成器将 MCP 服务器的工具暴露为 Python API，便于在本地代码中直调用
调用工具前置条件: MCP 服务器必须正在运行，且客户端正确配置 server_name、command、args 以启动服务器
代码执行与审批流程:
- 使用 CodeExecutor/ToolServer 等组件实现对 MCP 工具的调用
- 当工具调用发生时，如需要审批，将通过 ApprovalChannel/ApprovalClient 进行交互，用户需要做出接受或拒绝
安全性与稳定性：可开启 Sandbox 模式以限制网络访问，必要时配置自定义沙箱策略

运行示例（高层描述）

启动 MCP 服务器：使用模块方式运行：python -m ipybox.mcp_server --workspace /path/to/workspace --log-level WARNING
通过 MCP 客户端连接： server_params 示例如上配置，将 server_name 指向已注册的 MCP 服务器名称，便可调用 tool_1、tool_2、tool_3 等工具
生成并使用工具 API（可选）：使用 generate_mcp_sources 将 MCP 服务转为本地可导入的 Python 包，便于在代码中直接调用
调用工具时如需审批，将自动向已连接的审批端发送请求，由用户决定是否执行

关键特性与注意事项

支持多种传输协议（stdio、流式 HTTP、SSE）以及多进程/会话模型
提供自动化的工具注册、源码生成与导入能力
内置的 IPython 内核执行环境，含状态持久化、错误堆栈信息和图片输出
安全特性：可开启沙箱模式、环境变量隔离、审批机制

适用场景

AI 代理/助手需调用外部工具以获取信息、执行任务
需要将 MCP 服务暴露为可编程 API 的软件系统
需要在本地环境中搭建可审计、受控的工具调用后端

关键词

工具调用框架, IPython 内核执行, 沙箱执行, 远程工具调用, 容器化执行

关键词

概述