Nage MCP Skill

让 AI agent（OpenClaw / HermesAgent / Claude Code / Cursor / 其他 MCP 兼容平台）能通过标准 MCP 协议读写你的 Nage 物品清单。

版本：配套 Nage v1.4.0+（MCP Server 全套 18 工具）

🎯 30 秒接入

1. 生成 MCP token：登录 Nage → 顶栏头像 → MCP 令牌 → 新建令牌（选作用域：只读 / 可写）→ 复制完整 token

2. 配置平台（以 Claude Code 为例）：

   # 在你的项目根目录建 .mcp.json
   cat > .mcp.json <<'EOF'
   {
     "mcpServers": {
       "nage": {
         "type": "http",
         "url": "https://nage.example.com/api/mcp",   // ← 替换成你的 Nage 实例地址
         "headers": { "Authorization": "Bearer nage_mcp_<你的 token>" }
       }
     }
   }
   EOF

3. 装 skill：

   平台	装法
   Claude Code	复制 SKILL.md 内容到 .claude/skills/nage/SKILL.md
   Cursor	Cursor → Settings → Rules → Add new rule → 粘贴 SKILL.md
   OpenClaw	见下方 OpenClaw 详细步骤
   HermesAgent	见下方 HermesAgent 详细步骤
   其他 MCP 客户端	只需要 mcp.json + SKILL.md（prompt 注入）

OpenClaw 详细步骤

OpenClaw 的 skill 是单文件 + YAML frontmatter，MCP server 在 ~/.openclaw/openclaw.json 里另外声明（不在 skill 内）：

# 1. 装 skill
mkdir -p ~/.openclaw/workspace/skills/nage
cp platforms/openclaw/SKILL.md ~/.openclaw/workspace/skills/nage/SKILL.md

# 2. 设环境变量（frontmatter 的 requires.env 会校验这两个变量，没设 skill 不会加载）
export NAGE_MCP_URL='https://nage.example.com/api/mcp'   # ← 替换成你的 Nage 实例地址
export NAGE_MCP_TOKEN=nage_mcp_<你的 token>

# 3. 注册 MCP server
openclaw mcp set nage "{\"url\":\"$NAGE_MCP_URL\",\"transport\":\"streamable-http\",\"headers\":{\"Authorization\":\"Bearer $NAGE_MCP_TOKEN\"}}"

# 4. 验证
openclaw mcp status nage

完整说明（含 streamable-http / Bearer 选型理由）见 platforms/openclaw/SKILL.md 顶部「📦 在 OpenClaw 上安装」。

HermesAgent 详细步骤

HermesAgent 的 skill 也是单文件 + YAML frontmatter（比 OpenClaw 多一个必填 version 字段）。MCP server 配置在 ~/.hermes/config.yaml 的 mcp_servers 块（不在 skill 内）：

# 1. 装 skill（按 category 分目录）
mkdir -p ~/.hermes/skills/inventory/nage
cp platforms/hermes-agent/SKILL.md ~/.hermes/skills/inventory/nage/SKILL.md

# 2. 设环境变量（持久化到 ~/.hermes/.env，不用每次 export）
echo "NAGE_MCP_URL='https://nage.example.com/api/mcp'" >> ~/.hermes/.env   # ← 替换成你的 Nage 实例地址
echo 'NAGE_MCP_TOKEN=nage_mcp_<你的 token>' >> ~/.hermes/.env

# 3. 把 mcp_servers.nage 块合并进 ~/.hermes/config.yaml（最外层）
#    如果你已有 mcp_servers 块，把 nage: 那一段合并进去；没有就整段贴：

mcp_servers:
  nage:
    url: "${NAGE_MCP_URL}"
    headers:
      Authorization: "Bearer ${NAGE_MCP_TOKEN}"

# 4. 验证（新开 terminal）
hermes chat
# 问: Tell me which MCP-backed tools are available right now.

HermesAgent 的 frontmatter 没有 requires.env 强制机制（不像 OpenClaw），所以 NAGE_MCP_URL / NAGE_MCP_TOKEN 没设时 skill 仍会加载，agent 调 MCP 时连接失败才报缺失。自己保证 .env 里有。

${VAR} 在 HermesAgent 的 url / headers 中是连接时解析（不是启动时），所以改 .env 后 /reload-mcp 即可生效。

完整说明见 platforms/hermes-agent/SKILL.md 顶部「📦 在 HermesAgent 上安装」。

4. 测试：跟 agent 说 "列出我的 Nage 空间"，应该看到你的空间列表。

📦 文件结构

nage-skill/
├── README.md              ← 你正在读
├── SKILL.md               ← 核心：system prompt / agent 行为
├── mcp.json              ← 标准 MCP server 配置
├── CLAUDE.md             ← 未来 Claude 会话读这个了解项目背景
├── CHANGELOG.md
├── LICENSE                ← GPL v3（跟 Nage 同）
├── platforms/
│   ├── claude-code/      ← Claude Code 集成（.mcp.json + SKILL.md）
│   ├── cursor/           ← Cursor 集成（rule 格式）
│   ├── openclaw/         ← OpenClaw 集成（带 frontmatter 的 SKILL.md）
│   └── hermes-agent/     ← HermesAgent 集成（带 frontmatter 的 SKILL.md）
└── examples/
    ├── audit-expiring.md  ← 演示：保质期审计
    ├── add-item.md        ← 演示：加物品
    └── batch-update.md    ← 演示：批量操作

🔧 配置项

mcp.json 用 ${VAR} 占位，环境变量在启动 agent 之前设置：

字段	环境变量	说明
url	NAGE_MCP_URL	你的 Nage 实例地址，结尾 /api/mcp（必填）
headers.Authorization	NAGE_MCP_TOKEN	nage_mcp_<43 字符 token>（必填，在 Nage → MCP 令牌 页生成）

3 种设置方式（选一）：

# 方式 A：临时 export（当前 shell 有效）—— NAGE_MCP_URL 替换成你的真实地址
export NAGE_MCP_URL='https://nage.example.com/api/mcp'
export NAGE_MCP_TOKEN=nage_mcp_xxxxxxxx...

# 方式 B：写进 ~/.zshrc / ~/.bashrc（永久）—— 记得把 nage.example.com 换成你的真实地址
echo "export NAGE_MCP_URL='https://nage.example.com/api/mcp'" >> ~/.zshrc
echo 'export NAGE_MCP_TOKEN=nage_mcp_xxxxxxxx...' >> ~/.zshrc

# 方式 C：用 direnv（项目级，进了项目目录自动加载）
cp .env.example .env
# 编辑 .env 填值（.env.example 里 NAGE_MCP_URL 留空，等你填）
# 配合 direnv 自动加载

变量未设置时：

• NAGE_MCP_URL 未设 → Claude Code 解析 config 时找不到变量，直接报错（不会用任何占位 URL）
• NAGE_MCP_TOKEN 未设 → Claude Code 解析 config 失败，直接报错

Nage 端：.env 里的 PUBLIC_URL 必须正确配，否则反代后的 Origin 校验会拒绝请求。

🔐 鉴权与作用域

概念	说明
token 粒度	per-user（一个 token 对应一个用户的所有空间访问权）
scope 二档	reader（只读）/ editor（可写）；reader 调写工具 → -32002
空间隔离	所有读/写工具都要传 spaceId；非空间成员 → -32001
速率限制	默认 60 req/min/token；超限 → -32003（带 Retry-After 头）

agent 遇到 -32001 提示用户确认 spaceId；遇到 -32002 提示用户换 editor token。

📋 18 个工具速查

类别	工具	说明
空间	list_spaces	列出 caller 有访问权的所有空间
读	list_locations / list_categories / list_tags / search_items / get_item	各种读操作
物品写	create_item / update_item / delete_item	需要 editor scope
位置写	create_location / update_location / delete_location	需要 editor scope
分类写	create_category / update_category / delete_category	需要 editor scope
标签写	create_tag / update_tag / delete_tag	需要 editor scope

完整参数表见 Nage 文档 docs/mcp-integration.md（本 skill 不重复，避免漂移）。

📝 写 agent system prompt 用的核心规则（节选自 SKILL.md）

1. 先 list_spaces 拿 spaceId（其他工具都依赖它）
2. 不要假设 id 顺序，所有 ID 都通过 search / list 拿
3. 所有 update_* 是 partial update：缺字段=不变；显式 null=清空；显式值=改
4. 限速 60 req/min，批量超过 60 个要分多次（建议每次 50 个 + 1 秒 sleep）
5. 错误码：-32000 token / -32001 空间 / -32002 scope / -32003 限速 / -32602 入参 / -32603 内部
6. 图片 URL 也需 auth（fetch 时带 Bearer 或 cookie）

完整版见 SKILL.md。

🤝 与 Nage 同步

• Nage 主项目：faninx/Nage
• 工具定义在 Nage 仓库的 src/lib/mcp/tools/* 单一来源
• 当 Nage 加/改/删工具时，本 skill 不需要改（agent 通过 MCP tools/list 自动看到最新工具）
• 需要改 SKILL.md 的情况：行为规则变化、错误处理改进、新的工作流

🛠️ 开发

# 1. 启一个 Nage 实例供测试
cd ../Nage
pnpm dev  # http://localhost:3000

# 2. 在 Nage → MCP 令牌 生成一个 token（scope: editor 方便测全）

# 3. 编辑 mcp.json 填 token，测试 skill 工作流
cd ../nage-skill
$EDITOR mcp.json

# 4. 提交
git add -A
git commit -m "..."

📜 License

GPL v3（与 Nage 主项目保持一致）。详见 LICENSE。