Cowork MCP Server

@cowork/mcp服务器

人类代理协作原语作为MCP服务器

为任何AI代理添加信任、交接和问责制。生产就绪实施 协同工作协议.

______________________________________________________________________

状态

v0.1.1--完成第1、2和3周✅ | 准备好发布npm

从源代码安装： npm install && npm run build && npm run start npm注册表： 质量测试后1周内到达

______________________________________________________________________

这有什么作用

14 MCP工具 为任何AI代理添加协作原语：

______________________________________________________________________

安装

方案1：地方发展（立即实施）✅

git clone https://github.com/kamesh231/human-agent-cowork-mcp-server.git
cd human-agent-cowork-mcp-server
npm install
npm run build
npm run start

预期产量：

🤝 COWORK MCP Server v0.1.0 started
   Auth: open mode (demo) | Mode: suggest | Trust default: 0.3

克劳德桌面版

编辑 ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cowork": {
      "command": "node",
      "args": ["/full/path/to/human-agent-cowork-mcp-server/build/index.js"]
    }
  }
}

重新启动克劳德桌面→ 协作工具出现了。

克劳德代码

claude mcp add cowork node "$(pwd)/build/index.js"

选项2：全局npm（第3周后推出）⏳

# Not yet available. Will work after npm publish:
npm install -g @cowork/mcp-server

______________________________________________________________________

如何实现

步骤1--演示模式（无身份验证）

默认情况下，服务器在 开放模式 --任何 agent_id 已接受，不需要令牌。

npm run start
# Auth: open mode (demo) | Mode: suggest | Trust default: 0.3

所有13个工具立即可用。适合原型制作。

步骤2--注册您的代理（封闭式身份验证）

生成令牌并将其添加到 cowork.config.yaml:

# Generate token + hash for each agent
node -e "
const {generateToken, hashToken} = require('./build/auth.js');
const t = generateToken();
console.log('token:', t);
console.log('hash:', hashToken(t));
"

# cowork.config.yaml
agents:
  - id: "sales-agent"
    token: "sk-cowork-abc123..."     # Dev: plaintext in config
  - id: "support-agent"
    token: "sk-cowork-xyz789..."

服务器输出更改为： Auth: closed mode (2 agents)

生产方式： 使用 token_hash 而不是 token 并通过以下方式加载明文令牌 .env

步骤3——将每个代理映射到其策略

⏳ 第3周功能——即将推出。 目前，所有代理商都共享全球政策。

它解决的问题是： 有了一个全球政策和多个代理，你无法回答“哪个 为哪个代理人解雇了保单？“你无法证实这一点 sales-agent 受CRM规则约束 当 support-agent 获取支持规则，或测试两者在同一域中共享策略。

三段式设计 （策略定义一次，由映射中的ID引用）：

# Section 1 — Named rule sets. Define once, share across many agents.
policies:
  - id: "crm-write-policy"
    description: "Standard write access for CRM fields"
    rules:
      - field: "deal_stage"
        constraint: "high_risk"        # always requires human review
      - field: "amount"
        constraint: "value_range"
        min: 0
        max: 500000
      - field: "commission"
        constraint: "readonly"
        reason: "Finance team only"

  - id: "support-write-policy"
    description: "Write access for support ticket fields"
    rules:
      - field: "priority"
        constraint: "enum"
        values: ["low", "medium", "high", "critical"]
      - field: "billing_*"
        constraint: "readonly"
        reason: "Billing fields require finance approval"

# Section 2 — Agent identity only. No rules embedded here.
agents:
  - id: "sales-agent"
    token: "sk-cowork-..."
  - id: "support-agent"
    token: "sk-cowork-..."

# Section 3 — Explicit three-way join: who × where × which rules
mappings:
  - agent_id: "sales-agent"
    domain: "crm.deals"
    policy_id: "crm-write-policy"

  - agent_id: "support-agent"
    domain: "support.tickets"
    policy_id: "support-write-policy"

  # 2 agents → 1 policy: support-agent uses same CRM rules as sales-agent
  - agent_id: "support-agent"
    domain: "crm.deals"
    policy_id: "crm-write-policy"

  # 1 agent → 2 policies: sales-agent has support rules when working tickets
  - agent_id: "sales-agent"
    domain: "support.tickets"
    policy_id: "support-write-policy"

阻塞行为： 如果代理在没有的域中提出建议 mappings 入口，提案 被阻止并升级到请求许可的人。没有沉默的退路。

提案回复将包括启动哪项政策：

{
  "proposal_id": "uuid",
  "mode": "suggest",
  "trust_level": 0.3,
  "high_risk_field": true,
  "policy_id": "crm-write-policy",
  "policy_description": "Standard write access for CRM fields",
  "policy_rules_checked": 3,
  "mapping_found": true
}

这使得政策归因 可测试的: assert(response.policy_id === "crm-write-policy") 无论哪个代理人提出建议，都是明确的。

为什么不使用RBAC？ 结构看起来很相似（用户→ role → 许可）但语义 差异：这里的策略是动态的，相同的策略会产生 escalate, suggest，或 act 基于代理人获得的信任分数。RBAC是二进制的（允许/拒绝）。COWORK是梯度 （考虑到这位经纪人的往绩，现在有多大的自主权）。看 WEEK3_PLAN.md 以了解完整的设计原理。

步骤4--配置信任和权限（全局默认值）

# cowork.config.yaml

trust:
  default_level: 0.3              # All agents start supervised
  auto_promote_after: 20          # Promote after 20 approvals
  auto_promote_threshold: 0.8     # At 80%+ approval rate
  auto_demote_after: 3            # 3 consecutive overrides → demotion
  decay_per_day: 0.01             # Trust decays 1%/day without activity (⏳ Week 3)

authority:
  default_mode: "suggest"
  volume_cap: 50                  # Max proposals/hour per agent (⏳ enforced in Week 3)
  high_risk_fields:               # Global: always require human review
    - "deal_stage"
    - "owner"
    - "commission"
    - "utm_*"
    - "billing_*"
    - "password"
    - "permissions"

第五步——联系你的代理人

// Agent proposes before acting
const proposal = await cowork_propose({
  agent_id: "sales-agent",
  agent_token: "sk-cowork-...",
  domain: "crm.deals",
  action: "update_deal",
  target: "deal_12345",
  proposed_change: JSON.stringify({ deal_stage: "closed_won" }),
  confidence: 0.92,
  reasoning: "All criteria met: budget approved, stakeholder consensus",
  field: "deal_stage"
});

// Handle the three operating modes
if (proposal.mode === "act") {
  // Trust ≥ 0.8, proceed autonomously
  await db.update("deals", "deal_12345", { deal_stage: "closed_won" });

} else if (proposal.mode === "suggest") {
  // Trust 0.5–0.8, or field is high-risk — wait for human review
  // deal_stage is in high_risk_fields, so always lands here
  notify.send(`📋 Awaiting review: ${proposal.proposal_id}`);

} else {
  // Trust  0) {
  const handoff = callback.pending_handoffs[0];
  if (handoff.hand_back === true) {
    // Human handed work back with instructions
    console.log("Instructions:", handoff.instructions);
    // "Check for written stakeholder confirmation before proceeding"

    // Verify constraint and try again
    if (stakeholders_confirmed) {
      await cowork_propose({ /* same proposal */ });
    }
  }
}

人流

// Human sees escalated work in dashboard
const status = await cowork_status({ agent_id: "sales-agent" });
// Shows pending handoffs with agent's reasoning and context

// Human resolves with instructions
await cowork_resolve_handoff({
  handoff_id: "uuid",
  resolution: "approved",
  hand_back: true,  // Agent can continue
  instructions: "Proceed only if both stakeholders have written confirmation in the deal notes"
});

// Agent's next cowork_check_handoff call returns this instruction
// Agent can now take informed action or ask clarifying questions

______________________________________________________________________

本协议解决的真实案例

CRM数据完整性（HubSpot案例）

CRM案例研究描述了一个具有完全写访问权限的代理，该代理会悄无声息地损坏以下对象的数据 3周。根本原因：没有字段限制，没有卷上限，没有审批流。

COWORK提供什么：

• high_risk_fields 阻止直接写入deal_stage、commission、utm\_\*
• volume_cap 以每小时50个提案的速度暂停代理（在第3周执行）
• cowork_propose 在任何写入操作之前创建一个暂存层
• cowork_override 分类原因创建了一个反馈循环

支持切换故障（对讲机案例）

50%的对话需要人工切换。每次交接都会失去背景——人类 重新阅读完整的成绩单，客户重复了一遍。

COWORK提供什么：

• cowork_handoff 承载结构化语境：理性、自信、尝试
• 按域信任(support.tickets 与...分开 billing.issues)
• cowork_resolve_handoff 让人手根据指令进行回拨（第3周回拨）

跨环境上下文丢失

两个代理（Claude Desktop+Claude Code）共享一个文件系统，但不共享决策状态。 em dash事件：Claude Desktop在不知情的情况下批准了80个替代品 *为什么* 它们被制造出来了。

COWORK提供什么：

• cowork_handoff 上下文数据包携带 *决策状态*，而不仅仅是输出状态
• cowork_log 和 actor: "agent" 环境做出改变的属性
• 时间线事件允许重建跨环境序列

______________________________________________________________________

测试

自动化测试套件（Jest）✅

npm test

49项测试，4个类别，全部通过：

信任和模式确定（10次测试）

• 初始信任默认为0.3→ 模式=升级
• 高风险字段（交易阶段）→ 模式=不顾信任而建议
• 信任0.85→ 模式=动作（自主）
• 批准增加信任+0.02
• 使用严重性倍数（高：1.5倍）覆盖会正确降低信任度
• 连续3次覆盖会触发降级
• 正确应用信任衰减（每天1%）
• 20次批准后，汽车推广的批准率达到80%

策略映射和归因（17项测试）

• 2个代理+1个政策：销售代理和支持代理都使用crm编写政策
• 1个代理+2个策略：销售代理在crm.deals中使用crm写入策略，在support.tickets中使用支持写入策略
• 未映射的域返回mapping_found=false（正常升级）
• 评估的策略约束：高风险、只读、值范围、枚举、正则表达式
• 通配符匹配有效（billing\_\*匹配billing_amount、billing_status）
• 响应中的策略归因：Policy_id、Policy_description、rules_checked

身份验证（10次测试）

• 销售代理令牌根据配置进行验证
• 无效令牌引发AuthError
• 打开模式接受任何agent_id
• 关闭模式拒绝未知代理
• 令牌生成和哈希工作正常

集成（12次测试）

• 具有身份验证+策略解析的完整共享工作_角色流
• 执行音量上限（50/小时），并提供音量维持反馈
• 高风险现场检测+政策规则检查计数
• 切换回叫循环：升级→ 解决→ 代理民意调查→ 继续
• 模式确定既尊重高风险检查，也尊重基于信任的检查

覆盖

npm test -- --coverage

为所有14个工具生成覆盖率报告。当前覆盖率：核心路径的92%。

MCP检查员（交互式）

npm run inspect

打开基于浏览器的工具，手动调用14个工具中的任何一个，查看实时响应，检查数据库状态。

______________________________________________________________________

建筑

生产特点：

• ✅ 所有信任突变 BEGIN EXCLUSIVE SQLite事务（无TOCTU竞赛）
• ✅ 在所有14个工具上使用带有Zod输入验证的完整TypeScript
• ✅ 显式策略映射（三方连接），并响应归因
• ✅ 开放模式用于原型制作，封闭模式用于生产
• ✅ 哨兵追踪中的SHA-256哈希链（防篡改）
• ✅ 在建议时间执行交易量上限并提供反馈
• ✅ 信任衰退懒洋洋地应用于阅读（没有背景工作）

______________________________________________________________________

协议对齐

详细信息： 协议_忽略.md

______________________________________________________________________

第3周实施✅

详细计划和实施说明： WEEK3_PLAN.md

准备好了什么：

• ✅ 14个工具功能齐全
• ✅ 实现了36/38个COWORK协议原语（95%）
• ✅ 生产就绪：SQLite事务、原子信任突变、Zod验证
• ✅ 49项自动化测试全部通过
• ✅ 策略属性可测试（响应中的Policy_id）
• ✅ 响应中的容量上限反馈（Volume_remaining字段）
• ✅ 切换回叫环路完全运行

什么被推迟到v0.2.0：

• 质量指标收集（图元#37）
• 结构化推理模式（原语#38）

______________________________________________________________________

存储

• 默认：SQLite位于 ./cowork.db
• 表格：建议、信任核心、行动、覆盖、移交、时间表、审核日志
• 访问: sqlite3 cowork.db 或使用 cowork_status 和 cowork_audit_trail 工具
• 哨兵痕迹：单独数据库位于 ./cowork-traces.db 使用哈希链

______________________________________________________________________

链接

• COWORK协议规范: https://github.com/kamesh231/cowork-protocol
• 此Repo: https://github.com/kamesh231/human-agent-cowork-mcp-server
• 第3周计划: WEEK3_PLAN.md
• 协议对齐: 协议_忽略.md

______________________________________________________________________

许可证

麻省理工学院——在商业或开源项目中自由使用。