1claw MCP 服务端

关键词

秘密管理密钥 vault工具执行会话鉴权安全上下文

使用说明（Markdown 格式）

  • 项目简介

    • 这是一个完整的 MCP 服务器实现，基于 FastMCP 构建，向 MCP 客户端提供对 1claw Vault 的“只在需要时获取密钥与凭证”的上下文服务，并提供多种工具以读取、写入、共享密钥、创建 vault 等功能。服务器支持本地 stdio 模式与 HTTP 流式传输模式，具备会话级别认证和按会话分离的能力。

  • 主要功能点

    • MCP 服务端实现：完整实现 MCP 的请求/响应处理入口，支持工具、资源与提示相关功能的注册与执行。
    • 资源管理：通过 vault://secrets 等资源暴露，支持按会话上下文加载数据。
    • 工具集合：包括列出密钥、获取/存储秘密、描述秘密、创建和列出 Vault、授权、共享等多种工具，以及一些扩展工具（如 simulate_transaction、submit_transaction）。
    • 会话与认证：支持 stdio 与 httpStream 两种传输模式；httpStream 模式提供逐会话认证，stdio 模式通过环境变量提供静态或自动发现的凭据。
    • 安全与合规性：目标是在调用时就获取密钥，避免在上下文中长期保留；错误处理对常见状态给出友好提示。
    • 扩展性：通过工厂模式注册工具，便于按需添加新的工具。

  • 安装步骤

    • 安装依赖并构建：
      • 进入项目目录后执行安装与构建流程（使用你熟悉的包管理工具，例如 pnpm、npm、yarn）；
      • 构建完成后即可运行 MCP 服务器。
    • 运行方式
      • 本地 stdio（默认）：直接启动服务器，它会通过环境变量配置认证信息并对本地客户端提供服务；
      • httpStream（托管模式）：通过 HTTP 流传输对外暴露服务，需要在请求头中提供 Authorization: Bearer <token> 和 X-Vault-ID 来进行鉴权与定位 Vault。
    • 运行参数与环境变量示例
      • 运行时可通过以下环境变量进行配置：
        • MCP_TRANSPORT：传输模式，stdio 或 httpStream
        • PORT：httpStream 模式下的监听端口
        • ONECLAW_BASE_URL：1claw API 基础地址
        • ONECLAW_VAULT_ID：若使用 stdio，默认 vault 的 ID
        • ONECLAW_AGENT_ID、ONECLAW_AGENT_API_KEY、ONECLAW_AGENT_TOKEN：用于 stdio 的不同认证方式

  • 服务器配置（MCP 客户端需要的连接信息，作为参考配置，不属于服务器端代码）

    • 说明：MCP 客户端需要提供一个 json 配置，用于指定服务器名称、启动命令和参数等，以便与 MCP 服务器建立连接。下列字段来自仓库实现的服务器端信息，请据此配置客户端连接信息。
    • 配置示例（JSON）： { "server": "1claw", "description": "1claw MCP 服务端（Vault 密钥与工具访问）", "command": "node", "args": ["packages/mcp/dist/index.js"], "transport": "stdio", "env": { "ONECLAW_VAULT_ID": "<你的 vault-id>", "ONECLAW_AGENT_ID": "<你的 agent-id（可选，若使用 api_key 认证）>", "ONECLAW_AGENT_API_KEY": "<你的 ocv_ key>", "ONECLAW_BASE_URL": "https://api.1claw.xyz" } }
    • 说明
      • server：服务器在 MCP 客户端侧的名称标识，建议与服务端的 name 保持一致（此处为 1claw）。
      • command/args：启动 MCP 服务器的命令及参数，客户端需要据此启动与服务器交互。
      • transport：传输模式，stdio 为本地直连，httpStream 为托管/远程传输。
      • env/认证信息：根据实际部署选择不同的认证方式（agent-id + api-key，或静态 token），并设置相应的 vault id。

  • 基本使用方法

    • 启动服务器后，LLM 客户端通过配置的 MCP 服务器连接信息访问工具、读取资源和渲染提示模板。
    • 可通过工具如 list_secrets、get_secret、put_secret、describe_secret 等获取、管理密钥与凭证。
    • 使用 hosted 模式时，通过 Authorization Bearer 头和 X-Vault-ID 头进行会话鉴权与 Vault 定位。
    • 客户端与服务器之间的交互遵循 JSON-RPC 风格的请求/响应，具体调用细节请参考 MCP 客户端的调用规范。

  • 备注

    • 项目默认提供多种工具与资源，便于在 LLM 环境中实现安全、按需的凭证访问与操作。

服务器信息

访问项目