关键词

Vault集成密钥管理加密服务LLM工具调用上下文服务

项目简介

Vault MCP 密钥管理服务是一个基于 FastAPI 构建的后端应用，旨在作为 Model Context Protocol (MCP) 服务器，为大型语言模型 (LLM) 客户端提供与 HashiCorp Vault 交互的标准化接口。它允许 LLM 客户端通过结构化的 API 访问、管理密钥、执行加密操作、获取动态数据库凭证和 SSH 证书，从而为 LLM 应用提供安全、可扩展的上下文服务。

主要功能点

  • 资源托管与管理: 以 'kv://{subject}/{path}' 方案托管和管理 Agent 专属的 KV v2 密钥路径，支持读取、写入、列表、删除等操作，并强制执行Agent命名空间隔离。
  • 工具注册与执行: 提供了丰富的工具集，LLM 客户端可以通过 MCP 协议调用这些工具：
    • KV 密钥管理: 创建、读取、更新、删除、列出、恢复（undelete）、销毁（destroy）密钥版本。
    • Transit 加密服务: 支持数据的加密、解密、签名、验证、重加密（rewrap）及随机字节生成。
    • 数据库动态凭证: 颁发、续期、撤销动态数据库凭证。
    • SSH 证书签名: 生成 SSH OTP 凭证和签署 SSH 公钥。
  • Prompt 模板定义与渲染: 定义了用于 'kv_read' 和 'kv_write' 等操作的 Prompt 模板，支持 LLM 客户端生成可定制的交互模式。
  • 多传输协议支持: 支持通过 HTTP JSON-RPC ('POST /mcp/rpc') 和标准输入输出 (Stdio) 两种方式与客户端通信。同时提供 SSE (Server-Sent Events) 通道 ('GET /mcp/sse') 用于服务器向客户端发送实时通知。
  • 多重认证与安全: 支持 API Key、JWT (HS256/RS256) 和 mTLS (通过反向代理头) 等多种认证方式。提供 Agent 命名空间隔离、请求级子 Token 签发、内存限速等安全机制。
  • 可观测性: 集成了 Prometheus 指标 ('/metrics') 和可选的 OpenTelemetry 跟踪，支持结构化日志输出。

安装步骤

  1. 克隆仓库:

    git clone https://github.com/geopolitis/MCP-f-Secrets.git
cd MCP-f-Secrets

  2. 设置 Python 环境:

    python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

  3. 启动本地 HashiCorp Vault (开发环境): 为了方便测试和开发，可以使用 Docker Compose 启动一个本地 Vault 实例。

    cd local-vault
docker compose up -d
cd ..

    这将启动一个预配置的 Vault，包含 KV v2 密钥存储、Transit 密钥和示例策略。

  4. 运行服务器:

    • 最简单的方式: 
      python main.py
# 默认监听 127.0.0.1:8089，调试日志级别
    • 使用 Uvicorn (推荐): 
      python -m uvicorn main:app --reload --host 0.0.0.0 --port 8089 --log-level debug

  5. 健康检查 (可选): 服务器启动后，可以进行简单的健康检查：

    curl http://127.0.0.1:8089/healthz
# 预期输出: {"ok": true, "time": "..."}

服务器配置

MCP 客户端需要知道如何连接到 MCP 服务器。以下是针对两种主要传输协议（Stdio 和 HTTP）的 MCP 服务器配置信息，适用于 MCP 客户端集成。

  1. Stdio 传输配置 (客户端直接启动服务器进程)

    {
  "serverName": "Vault MCP Secrets Server (Stdio)",
  "command": "python",
  "args": [
    "scripts/mcp_stdio.py"
  ],
  "env": {
    "SUBJECT": "agent_api",
    "LOG_LEVEL": "info"
  },
  "transport": "stdio",
  "description": "通过标准输入输出与Vault MCP服务器通信，适用于需要隔离进程的客户端，SUBJECT环境变量定义了客户端的身份。"
}

    参数注释:

    • 'serverName': 服务器的标识名称。
    • 'command': 启动 MCP 服务器进程的可执行文件（例如 'python'）。
    • 'args': 传递给 'command' 的命令行参数列表。在这里是运行 'scripts/mcp_stdio.py' 脚本。
    • 'env': 传递给服务器进程的环境变量。'SUBJECT' 定义了此客户端在 Vault 中的身份前缀，'LOG_LEVEL' 控制日志级别。
    • 'transport': 指明使用的传输协议，此处为 'stdio'。
    • 'description': 配置的简要说明。

  2. HTTP 传输连接信息 (客户端连接已运行的服务器)

    对于 HTTP 传输，MCP 客户端通常连接到一个已经运行的服务器实例。MCP 客户端配置中通常不包含 'command' 和 'args' 来启动 HTTP 服务器，而是直接提供连接 URL 和认证信息。

    • MCP RPC URL: 'http://127.0.0.1:8089/mcp/rpc'
    • MCP SSE URL (可选): 'http://127.0.0.1:8089/mcp/sse'
    • 认证头信息 (根据配置选择一种):
      • API Key: '{"X-API-Key": "dev-api-key"}' (假设 'dev-api-key' 已在服务器配置中映射到 'agent_api')
      • JWT: '{"Authorization": "Bearer <YOUR_JWT_TOKEN>"}'
      • mTLS (通过代理头): '{"X-SSL-Client-S-DN": "CN=agent_mtls,OU=dev", "X-SSL-Client-Verify": "SUCCESS"}'

基本使用方法

  1. 通过 MCP 协议调用工具 (例如 HTTP JSON-RPC): 使用 'curl' 模拟一个 MCP 客户端，进行 'kv.write' 和 'kv.read' 操作。

    # 写入一个密钥
curl -X POST http://127.0.0.1:8089/mcp/rpc \
     -H 'X-API-Key: dev-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
           "jsonrpc": "2.0",
           "id": "w1",
           "method": "tools/call",
           "params": {
             "name": "kv.write",
             "arguments": {"path": "configs/demo", "data": {"foo": "bar"}}
           }
         }'

# 读取密钥
curl -X POST http://127.0.0.1:8089/mcp/rpc \
     -H 'X-API-Key: dev-api-key' \
     -H 'Content-Type: application/json' \
     -d '{
           "jsonrpc": "2.0",
           "id": "r1",
           "method": "tools/call",
           "params": {
             "name": "kv.read",
             "arguments": {"path": "configs/demo"}
           }
         }'

  2. 使用示例客户端脚本 (Stdio): 运行 'scripts/mcp_stdio_driver.py' 可以端到端地测试 Stdio 传输。

    SUBJECT=agent_api python scripts/mcp_stdio_driver.py --mode full --path configs/stdio_test

  3. 通过 LangChain 代理集成: 项目提供了 LangChain 代理的示例，展示了如何将 MCP 服务器暴露的工具集成到 LLM 应用中。

    # 例如，运行一个使用 API Key 的 LangChain 代理
VAULT_MCP_API_KEY=dev-api-key python examples/langchain_agent/agent.py --input "Create a secret at configs/llm-agent with {\"greeting\":\"hello\"} then read it back."

关键词

Vault集成, 密钥管理, 加密服务, LLM工具调用, 上下文服务

信息

分类

AI与计算

访问项目