dashclaw

@dashclaw/mcp-server

用于 DashClaw 治理的 MCP 服务。通过 Model Context Protocol 提供 17 个治理工具、2 个仅限 stdio 的支持工具和 3 个只读资源：评估策略、记录证据、调用已注册的功能、等待审批，以及读取决策账本。兼容 Claude Code、Claude Desktop、Claude Managed Agents 和任何兼容 MCP 的客户端。

只有同时设置 DASHCLAW_URL 和 DASHCLAW_API_KEY 时，才会注册治理工具；如果只设置了其中一个，服务不会注册任何工具，并会向 stderr 发出警告。

快速开始

Claude Code / Cowork（stdio）

npx -y @dashclaw/mcp-server --url https://your-dashclaw.vercel.app --key oc_live_xxx --agent-id claude-code

或者添加到 MCP 配置中（Claude Code 使用 .mcp.json，也可以使用 claude mcp add）：

{
  "mcpServers": {
    "dashclaw": {
      "command": "npx",
      "args": ["-y", "@dashclaw/mcp-server"],
      "env": {
        "DASHCLAW_URL": "https://your-dashclaw.vercel.app",
        "DASHCLAW_API_KEY": "oc_live_xxx",
        "DASHCLAW_AGENT_ID": "claude-code"
      }
    }
  }
}

Claude Desktop 主聊天：不要使用 stdio。 Desktop 使用内置的 Node 运行本地 MCP 服务，这会导致此服务崩溃。请改用 OAuth 自定义连接器——无需本地进程，可在聊天和 Cowork 中使用。

关于 DASHCLAW_AGENT_ID： 这是显示在 /fleet、/decisions 和其他所有治理界面上的名称。如果省略，服务会根据 MCP 协议的 clientInfo.name 自动生成 agent_id（例如，Claude Desktop 对应 claude-ai，Cursor 对应 cursor-vscode），以避免调用与其他 Agent 的记录无声地混在一起。不过，为了让仪表板更易读，实际使用时最好设置为 claude-desktop 这类便于人识别的名称。显式配置始终优先于自动生成的值。

Claude Managed Agents（Streamable HTTP）

如果你正在运行 DashClaw，MCP 端点已内置在 /api/mcp：

agent = client.beta.agents.create(
    name="Governed Agent",
    model="claude-sonnet-4-6",
    tools=[{"type": "agent_toolset_20260401"}],
    mcp_servers=[{
        "type": "url",
        "url": "https://your-dashclaw.vercel.app/api/mcp",
        "headers": {"x-api-key": "oc_live_xxx"},
        "name": "dashclaw"
    }],
)

Claude Desktop

请使用 OAuth 自定义连接器（见下一节）——这是经过验证的 Desktop 聊天、网页和 Cowork 接入方式，无需安装。旧的一键式 .mcpb 程序包已弃用：它使用 Desktop 内置的 Node 运行 stdio 服务，会反复崩溃。如果你仍安装了通过该程序包安装的 dashclaw 扩展，请先将其卸载（Settings → Extensions），然后再添加连接器。

Claude 自定义连接器（远程，OAuth）

可将自托管的 DashClaw 添加为 Claude 自定义连接器，无需在界面中填写 API 密钥——Claude 的连接器流程要求使用 OAuth，而非请求头：

1. 在 Claude 中：Settings → Connectors → Add custom connector。
2. 粘贴 https://<your-instance>/api/mcp。
3. Claude 会发现 /.well-known/oauth-protected-resource，通过 DCR 注册，并打开你的 DashClaw 登录页和授权确认页面。
4. 授权后，17 个治理工具将显示出来，并限定在你的工作区范围内。

支持 Free/Pro/Max/Team/Enterprise（Free 最多可添加一个自定义连接器）。 旧版 x-api-key 方式（Managed Agents）保持不变。

通过 marketplace 安装插件（skills）

若要同时在 Claude 应用中加载 DashClaw skills（治理协议 + 平台智能）：Customize → Plugins → "+" → Add marketplace → github: ucsandman/DashClaw，然后安装 dashclaw 插件。

工具（17 个治理工具 + 2 个 stdio 支持工具）

按领域分组。规范定义请参阅 src/tools.ts。

核心治理（9 个）——守护 / 记录 / 调用循环，以及发现和会话生命周期。

工具	描述
dashclaw_guard	在执行高风险操作前评估策略
dashclaw_record	将操作记录到审计追踪中
dashclaw_invoke	通过服务端的守护、审批、执行声明、效果和结果接缝，执行已注册的能力
dashclaw_capabilities_list	发现可用的 API
dashclaw_policies_list	查看生效中的治理策略
dashclaw_wait_for_approval	阻塞等待人工处理审批
dashclaw_session_start	注册 Agent 会话
dashclaw_session_end	关闭 Agent 会话
dashclaw_session_retro	读取会话自身的可辩护性回顾（clean/review/flagged 状态）

**会话关联：**调用 dashclaw_session_start 后，服务端会自动将该会话的 ID 标记到同一连接（stdio）中的每条 dashclaw_record 上。在 dashclaw_record 中传入 session_id 可覆盖此值；也可在 HTTP 传输（POST /api/mcp）中显式指定归属，此时每个请求均为无状态请求。

强制执行边界

dashclaw_guard、dashclaw_record 和 dashclaw_wait_for_approval 都是 协作式工具。它们会返回策略和审计状态，但是否遵守仍由 MCP 主机或模型 决定。若需要对普通 MCP 工具设置机械式门禁，请使用主机拦截钩子。

dashclaw_invoke 是有限效果接缝。DashClaw 持有已注册的能力 配置，根据当前策略评估精确的调用内容，记录该调用，强制执行审批，并在进行外部调用前 以原子方式声明一次执行尝试。审批和计划授权在该声明时消耗，而不是在更早的守护评估时消耗。如果执行已完成，但无法记录结果，工具会报告执行状态未知， 并且不会将重试描述为安全操作。请先与外部系统核对。

回顾（2 个）——记录假设；近期受治理操作账本。

工具	描述
dashclaw_assumption_record	记录支撑某项操作但尚未验证的假设
dashclaw_decisions_recent	近期受治理操作账本

Agent 身份（1 个）——由操作员批准，将未识别的 Agent 配对到已注册身份。

工具	描述
dashclaw_pair	注册 Agent 身份：在本地生成密钥对，并将公钥提交到 /api/pairings

团队任务（3 个）——创建团队任务、追加 Agent 间时间线事件、更新任务状态。

工具	描述
dashclaw_task_create	创建团队任务——每次多 Agent /team 运行对应一条记录
dashclaw_task_event	向团队任务时间线追加一个事件（委派、回复、状态、需要审批、结果、错误、完成）
dashclaw_task_update	更新团队任务：状态转换和已存储的传输会话 ID

计划（2 个）——提交预检计划，供操作员通过单卡审核，并轮询其审核状态。预览和审核响应是证据；实际操作会重新评估，任何授权仅在执行声明时消耗。

工具	描述
dashclaw_plan_submit	提交有序步骤列表以供预检审核；获批步骤将成为范围受限、会过期的授权，且仅在执行声明时消耗
dashclaw_plan_status	检查已提交计划的总体判定和各步骤判定

由 DashClaw 门控的 stdio 工具（2 个）

仅由 src/tools/index.ts 在本地 stdio 服务上注册；与治理工具集使用相同的 DASHCLAW_URL + DASHCLAW_API_KEY 凭据进行门控：

工具	描述
dashclaw_status	检查 DashClaw 门控配置和可达性
export_dashclaw_evidence	导出带有 DashClaw 守护 / 证据元数据的本地审计条目

资源（3）

URI	描述
dashclaw://policies	当前生效的策略集
dashclaw://agent/{agent_id}/history	最近的操作历史（最近 50 条）
dashclaw://status	实例运行状况和运行指标

配置

在 MCP 客户端的 env 块中设置这些变量（首选方式——仅作用于服务进程，终端中不可见），也可以在 Shell 中设置。带注释的模板位于 .env.example。

CLI 参数	环境变量	默认值	描述
--url	DASHCLAW_URL	http://localhost:3000	DashClaw 实例 URL——设置 DASHCLAW_API_KEY 后，将启用治理工具集
--key	DASHCLAW_API_KEY	（空）	API 密钥（前缀为 oc_live_）
--agent-id	DASHCLAW_AGENT_ID	（空）	默认 Agent ID（为空时，根据 MCP clientInfo.name 自动派生）
	DASHCLAW_MODE	authoritative	DashClaw 门控模式（仅支持 authoritative）
	DASHCLAW_LOCAL_HOME	<cwd>/.dashclaw-local	本地状态的存储位置（参见下方的“存储”）
	DASHCLAW_TIMEOUT_MS	30000	DashClaw API 请求超时
	DASHCLAW_LOCK_STALE_MS	30000	本地状态文件的过期文件锁阈值
	DASHCLAW_AUDIT_MAX_ENTRIES	（不限）	保留的审计条目上限

CLI 参数的优先级高于环境变量。

注意： 此服务读取 DASHCLAW_URL（而非 DASHCLAW_BASE_URL）；DashClaw 仓库中的钩子和 CLI 则读取 DASHCLAW_BASE_URL。

存储

优先使用本地存储，工作目录下的 .dashclaw-local/ 中保存状态 （可通过 DASHCLAW_LOCAL_HOME 覆盖）。使用纯 JSON 格式——可供人阅读、 可比较差异，且不依赖原生组件：

文件	内容
state.json	本地默认工作区
audit.log	仅追加的 JSONL 审计记录，由 DashClaw 证据工具读取

此处绝不会写入密钥——令牌保存在环境中，并在调用时读取。

许可证

Apache-2.0。此软件包包含来自上游 Apache-2.0 项目的代码——署名信息请参见 NOTICE。

发布

更新 mcp-server/package.json 中的 version 后，在仓库根目录运行：

npm run release:mcp

一条命令即可完成所有操作，重复运行始终安全（已发布的步骤会跳过）：

1. 将 server.json 的版本同步到 package.json（如果文件有更改，请提交更改）。
2. 发布到 npm——浏览器会打开，提示你使用安全密钥进行 2FA 验证。
3. 通过 mcp-publisher 发布到官方 MCP Registry——如果已保存的 GitHub 令牌过期，它会重新运行设备流程登录（在 github.com/login/device 输入打印出的代码），然后重试。

一次性前置条件：运行 npm login，并安装官方的 mcp-publisher 二进制文件，下载地址为 modelcontextprotocol/registry releases——绝不要运行 npm i -g mcp-publisher，该名称已被无关软件包抢注。