关键词

LLM工具终端命令上下文服务JSON-RPC服务器

使用说明

项目简介

mcpserve 是一个简单的 MCP (Model Context Protocol) 服务器实现，专注于提供工具 (Tools) 功能，特别是执行终端命令的能力。它允许大型语言模型（LLM）客户端通过标准化的 MCP 协议，安全地调用服务器端的 shell 命令，从而扩展 LLM 与操作系统交互的能力。

主要功能点

  • 工具注册与执行: 通过 '@mcp.tool()' 装饰器可以轻松注册 Python 函数为 MCP 工具，客户端可以调用这些工具执行特定任务。本例中提供了一个 'shell_command' 工具，允许执行任意 shell 命令。
  • JSON-RPC 协议: 服务器遵循 MCP 协议，使用 JSON-RPC 与客户端通信，接收请求并返回响应。
  • Server-Sent Events (SSE) 传输: 支持 SSE 传输协议，实现服务器向客户端推送事件和响应。
  • API Key 认证: 通过简单的 API Key 认证机制 (x-api-key header) 保护服务器接口，防止未授权访问。
  • 可配置性: 服务器端口、日志级别等可通过 settings 字典进行配置。

安装步骤

  1. 环境准备: 确保已安装 Python 3.6 或更高版本。
  2. 安装依赖: 虽然此示例代码非常简单，但根据 'fastmcp' 的实际情况，可能需要安装一些依赖。通常情况下，运行以下命令安装 'python-dotenv' 即可（如果 '.env' 文件用于配置环境变量）： 
    pip install python-dotenv
    如果 'fastmcp' 有其他依赖，也需要一并安装。 (请注意：此示例代码非常精简，实际 'fastmcp' 框架可能需要更多依赖，请参考 'fastmcp' 库的安装说明。)
  3. 配置环境变量 (可选): 如果需要使用 API Key 认证，请在项目根目录下创建 '.env' 文件，并添加 'MCP_API_KEY' 环境变量，例如： 
    MCP_API_KEY=your_secret_api_key
    如果不需要 API Key 认证，或者想使用默认的 'test1234'，则可以跳过此步骤。

服务器配置

MCP 客户端需要配置连接到 mcpserve 服务器的信息。以下是一个 JSON 格式的配置示例，用于指导 MCP 客户端如何连接和使用此服务器：

{
  "server name": "Terminal",
  "command": "python",
  "args": [ "mcp/main.py" ],
  "transport": "sse",
  "description": "提供终端命令执行工具的MCP服务器",
  "auth": {
    "type": "apiKey",
    "key": "x-api-key",
    "value": "your_secret_api_key"
  },
  "tools": [
    {
      "name": "shell_command",
      "description": "执行 shell 命令",
      "parameters": {
        "type": "object",
        "properties": {
          "command": {
            "type": "string",
            "description": "要执行的 shell 命令"
          }
        },
        "required": ["command"]
      }
    }
  ]
}

配置参数说明:

  • '"server name"': 服务器名称，这里设置为 "Terminal"，与代码中 'FastMCP(name="Terminal", ...)' 一致。
  • '"command"': 启动服务器的命令，这里使用 'python' 解释器。
  • '"args"': 启动命令的参数，指向服务器主程序 'mcp/main.py'。 (请根据实际 'main.py' 文件路径调整)
  • '"transport"': 使用的传输协议，这里设置为 '"sse"' (Server-Sent Events)，与代码中 'mcp.run(transport="sse")' 一致。
  • '"description"': 服务器的简要描述，方便客户端用户了解服务器功能。
  • '"auth"': 认证配置，如果服务器启用了 API Key 认证，则需要配置此项。
    • '"type": "apiKey"': 认证类型为 API Key。
    • '"key": "x-api-key"': API Key 放在 HTTP Header 的 'x-api-key' 字段中。
    • '"value": "your_secret_api_key"': 实际的 API Key 值。请替换为你在 '.env' 文件中设置的 'MCP_API_KEY' 值，或者如果使用默认值，则设置为 'test1234'。 如果未启用认证，可以移除整个 '"auth"' 部分。
  • '"tools"': 服务器提供的工具列表。
    • 每个工具包含 '"name"' (工具名称，与 '@mcp.tool()' 装饰的函数名一致), '"description"' (工具描述), 和 '"parameters"' (工具参数的 JSON Schema 定义)。
    • 'shell_command' 工具接受一个名为 'command' 的字符串参数，用于指定要执行的 shell 命令。

注意: MCP 客户端需要能够解析并使用此 JSON 配置信息来连接和调用 mcpserve 服务器提供的工具。

基本使用方法

  1. 启动服务器: 在 mcpserve 仓库目录下，运行命令 'python mcp/main.py' 即可启动 MCP 服务器。服务器默认监听 8005 端口。
  2. 配置 MCP 客户端: 在你的 MCP 客户端应用中，根据上面提供的服务器配置 JSON，配置连接到 mcpserve 服务器。你需要确保客户端能够发送带有正确 API Key (如果启用) 的 MCP 请求到 'http://服务器IP:8005' (如果使用 SSE 传输)。
  3. 调用工具: 客户端可以使用 MCP 协议定义的工具调用方法，调用 'shell_command' 工具，并传递 'command' 参数来执行 shell 命令。 例如，客户端可以发送请求调用 'shell_command' 工具并执行 'ls -l' 命令来列出当前目录的文件。

安全提示: 'shell_command' 工具具有潜在的安全风险，因为它允许 LLM 客户端执行任意 shell 命令。在生产环境中使用时，请务必谨慎，并考虑更细粒度的权限控制和安全措施，例如限制可执行的命令、进行输入验证和沙箱环境等。

信息

分类

桌面与硬件

访问项目