Skip to content

Commit 8909ff3

Browse files
johnlannijohnlanni
authored
docs: clarify MCP and SKILLS relationship in 1.0.6 release blog (#308)
1 parent 8ab5137 commit 8909ff3

2 files changed

Lines changed: 136 additions & 18 deletions

File tree

‎blog/hiclaw-1.0.6-release.md‎

Lines changed: 68 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,49 @@ In HiClaw 1.0.6, both Manager and Workers use mcporter to interact with MCP serv
5252

5353
---
5454

55+
## MCP and SKILLS: Complementary, Not Competing
56+
57+
Before diving into HiClaw's MCP integration architecture, it's worth clarifying the **relationship between MCP and SKILLS**.
58+
59+
### HiClaw's Open Skills Ecosystem
60+
61+
HiClaw supports an **open SKILLS marketplace** through [skills.sh](https://skills.sh), as well as **enterprise self-hosted SKILLS marketplaces** via Nacos. SKILLS are scenario-oriented, iterable capability packages:
62+
63+
- **Scenario-oriented**: Combine atomic tools into complete business workflows
64+
- **Continuously evolving**: Optimize and improve based on real-world experience
65+
- **Knowledge accumulation**: Include best practices, error handling, and parameter descriptions
66+
67+
### MCP's Role in the Ecosystem
68+
69+
MCP is **not meant to replace SKILLS** — it serves as a **complement to the SKILLS ecosystem**, enabling rapid conversion of existing APIs into standardized agent-usable tools. MCP's core value lies in:
70+
71+
- **Clear constraints and specifications**: More rigorous tool definitions and type constraints
72+
- **Permission governance system**: Reuse MCP's authentication/authorization capabilities (MCP Server-level permission management, tool-level supported in Enterprise Edition)
73+
- **Batch conversion capability**: Especially in enterprise scenarios, Higress-based MCP gateway capabilities enable painless batch conversion of existing APIs into MCP tools with fine-grained management
74+
75+
### mcporter as a Bridge
76+
77+
Through CLI tools like mcporter, HiClaw achieves **re-orchestration and organization of MCP tools**, forming iterable SKILLs:
78+
79+
```
80+
MCP Tools (Atomic Capabilities)
81+
↓ mcporter orchestration
82+
SKILLs (Scenario-based Capability Packages)
83+
↓ Practical usage
84+
SKILL Iterative Optimization
85+
```
86+
87+
### SKILL + MCP = 1+1 > 2
88+
89+
The best practice for both is:
90+
91+
- **SKILLs handle scenario evolution**: Adapt to actual business scenarios, continuously iterate on skill composition logic and best practices
92+
- **MCP handles fine-grained permission control**: Align with business capabilities for MCP Server and tool permission governance and credential management
93+
94+
This complementary relationship achieves the **SKILL + MCP 1+1 > 2 effect**: Enterprises can enjoy the rich capabilities of the open SKILLS marketplace while maintaining secure, fine-grained permission control over internal APIs through the MCP gateway.
95+
96+
---
97+
5598
## The Architecture: How It All Works
5699

57100
Here's the complete flow when you want to add a new API tool for your workers:
@@ -60,7 +103,7 @@ Here's the complete flow when you want to add a new API tool for your workers:
60103
┌─────────────────────────────────────────────────────────────────────────────┐
61104
│ YOU (Human) │
62105
│ │
63-
│ "Add a weather API: GET https://api.weather.com/v1/forecast?city={city}" │
106+
│ "Add a stock index API: GET https://api.finance.com/v1/index?symbol={symbol}"│
64107
│ "Auth via X-API-Key header, here's my key: sk_xxx" │
65108
└────────────────────────────────────┬────────────────────────────────────────┘
66109
│
@@ -69,19 +112,19 @@ Here's the complete flow when you want to add a new API tool for your workers:
69112
│ MANAGER CLAW │
70113
│ │
71114
│ 1. Generates MCP Server YAML config from your description │
72-
│ 2. Runs setup-mcp-server.sh weather "sk_xxx" --yaml-file /tmp/weather.yaml │
73-
│ 3. Verifies with mcporter: mcporter call weather.get_forecast city=Tokyo │
74-
│ 4. Notifies Workers: "New MCP server 'weather' is ready" │
115+
│ 2. Runs setup-mcp-server.sh stock-index "sk_xxx" --yaml-file /tmp/stock.yaml │
116+
│ 3. Verifies with mcporter: mcporter call stock-index.get_index symbol=000001.SH │
117+
│ 4. Notifies Workers: "New MCP server 'stock-index' is ready" │
75118
└────────────────────────────────────┬────────────────────────────────────────┘
76119
│
77120
▼
78121
┌─────────────────────────────────────────────────────────────────────────────┐
79122
│ HIGRESS AI GATEWAY │
80123
│ │
81124
│ ┌─────────────────────────────────────────────────────────────────────┐ │
82-
│ │ MCP Server: weather-mcp-server │ │
125+
│ │ MCP Server: stock-index-mcp-server │ │
83126
│ │ ├─ Real Credential: sk_xxx (STORED SECURELY, NEVER EXPOSED) │ │
84-
│ │ ├─ Tool: get_forecast(city: string) → weather data │ │
127+
│ │ ├─ Tool: get_index(symbol: string) → stock index data │ │
85128
│ │ └─ Authorized Consumers: manager, worker-alice, worker-bob │ │
86129
│ └─────────────────────────────────────────────────────────────────────┘ │
87130
│ │
@@ -96,20 +139,36 @@ Here's the complete flow when you want to add a new API tool for your workers:
96139
│ │
97140
│ 1. Receives notification from Manager │
98141
│ 2. Pulls updated mcporter config from MinIO │
99-
│ 3. Discovers tools: mcporter list weather --schema │
100-
│ 4. Tests tool: mcporter call weather.get_forecast city=Shanghai │
142+
│ 3. Discovers tools: mcporter list stock-index --schema │
143+
│ 4. Tests tool: mcporter call stock-index.get_index symbol=000001.SH │
101144
│ 5. Generates SKILL.md based on understanding │
102145
│ 6. Ready to use in future tasks! │
103146
│ │
104147
│ ┌─────────────────────────────────────────────────────────────────────┐ │
105148
│ │ Worker's View: │ │
106149
│ │ ├─ Has: Consumer token (like an "ID badge") │ │
107-
│ │ ├─ Can do: Call weather.get_forecast via gateway │ │
150+
│ │ ├─ Can do: Call stock-index.get_index via gateway │ │
108151
│ │ └─ Cannot do: See the real API key sk_xxx │ │
109152
│ └─────────────────────────────────────────────────────────────────────┘ │
110153
└─────────────────────────────────────────────────────────────────────────────┘
111154
```
112155

156+
Once configured, the Manager can view the list of tools under the MCP Server in the **Higress Console** and perform further permission management:
157+
158+
![Higress MCP Tool Management Interface](https://img.alicdn.com/imgextra/i3/O1CN01armHyk1Lc9XTGz7ZX_!!6000000001319-2-tps-1452-849.png)
159+
160+
Through the console, you can:
161+
- View all tools contained in the MCP Server
162+
- Configure MCP Server-level access permissions for each Consumer (Worker)
163+
- Monitor tool invocation and performance metrics
164+
- Dynamically adjust permission policies without restarting services
165+
166+
> **Permission Management Notes**:
167+
> - **Higress Open Source**: Supports **MCP Server-level** permission management (e.g., Worker A can access the entire `stock-index` MCP Server)
168+
> - **Higress Enterprise Edition**: Supports **tool-level** permission management (e.g., Worker A can only call `stock-index.get_index`, but not `stock-index.update_index`)
169+
>
170+
> HiClaw 1.0.6 implements MCP Server-level security isolation based on the open-source version, which already meets the permission control requirements of most enterprise scenarios.
171+
113172
**Key Security Principle: Workers never see real credentials.**
114173

115174
Even if a worker is completely compromised, an attacker only gets a consumer token that:

‎blog/zh-cn/hiclaw-1.0.6-release.md‎

Lines changed: 68 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,49 @@ mcporter call github.search_repositories query="hiclaw" limit=5
5252

5353
---
5454

55+
## MCP 与 SKILLS：互补而非替代
56+
57+
在了解 HiClaw 的 MCP 集成架构前，有必要先澄清 **MCP 和 SKILLS 的关系**。
58+
59+
### HiClaw 的开放技能生态
60+
61+
HiClaw 通过对接 [skills.sh](https://skills.sh) 支持**开放的 SKILLS 市场**，并且支持对接 **Nacos 的企业自建 SKILLS 市场**。SKILLS 是面向实际场景的、可迭代的能力包装：
62+
63+
- **场景导向**：将多个原子工具组合成完整的业务流程
64+
- **持续演进**：基于实战经验不断优化和改进
65+
- **知识沉淀**：包含最佳实践、错误处理、参数说明
66+
67+
### MCP 在生态中的定位
68+
69+
MCP 并不是要取代 SKILLS，而是作为 **SKILLS 生态中的补充**，用于快速将已有的 API 转换成标准的 Agent 可使用的工具。MCP 的核心价值在于：
70+
71+
- **明确的约束和规范**：对工具有着更严格的定义和类型约束
72+
- **权限治理体系**：可以复用 MCP 的认证鉴权能力（MCP Server 粒度的权限管理，企业版支持工具粒度）
73+
- **批量转换能力**：尤其在企业场景下，基于 Higress 的 MCP 网关能力可以无痛地将大量存量 API 批量转换成 MCP 工具，实现精细化管理
74+
75+
### mcporter 的桥接作用
76+
77+
通过 mcporter 这样的 CLI 工具，HiClaw 实现了 **MCP 工具的重新编排和组织**，形成可迭代的 SKILL：
78+
79+
```
80+
MCP 工具（原子能力）
81+
↓ mcporter 编排
82+
SKILL（场景化能力包）
83+
↓ 实战使用
84+
SKILL 迭代优化
85+
```
86+
87+
### SKILL + MCP = 1+1 > 2
88+
89+
两者的最佳实践是：
90+
91+
- **SKILL 负责场景演进**：贴合实际业务场景，不断迭代技能的组合逻辑和最佳实践
92+
- **MCP 负责细粒度权限管控**：贴合业务能力做好 MCP Server 和工具的权限治理与凭证管理
93+
94+
这种互补关系实现了 **SKILL + MCP 1+1 大于 2 的效果**：企业既能享受开放 SKILLS 市场的丰富能力，又能通过 MCP 网关对企业内部 API 实现安全、精细的权限管控。
95+
96+
---
97+
5598
## 架构：一切如何运作
5699

57100
当你想为 Worker 添加一个新的 API 工具时，完整流程如下：
@@ -60,7 +103,7 @@ mcporter call github.search_repositories query="hiclaw" limit=5
60103
┌─────────────────────────────────────────────────────────────────────────────┐
61104
│ 你（人类） │
62105
│ │
63-
│ "添加一个天气 API：GET https://api.weather.com/v1/forecast?city={city}" │
106+
│ "添加一个股票指数 API：GET https://api.finance.com/v1/index?symbol={symbol}"│
64107
│ "通过 X-API-Key header 认证，这是我的 key：sk_xxx" │
65108
└────────────────────────────────────┬────────────────────────────────────────┘
66109
│
@@ -69,19 +112,19 @@ mcporter call github.search_repositories query="hiclaw" limit=5
69112
│ MANAGER CLAW │
70113
│ │
71114
│ 1. 根据你的描述生成 MCP Server YAML 配置 │
72-
│ 2. 运行 setup-mcp-server.sh weather "sk_xxx" --yaml-file /tmp/weather.yaml │
73-
│ 3. 用 mcporter 验证：mcporter call weather.get_forecast city=Tokyo │
74-
│ 4. 通知 Worker："新 MCP 服务器 'weather' 已就绪" │
115+
│ 2. 运行 setup-mcp-server.sh stock-index "sk_xxx" --yaml-file /tmp/stock.yaml │
116+
│ 3. 用 mcporter 验证：mcporter call stock-index.get_index symbol=000001.SH │
117+
│ 4. 通知 Worker："新 MCP 服务器 'stock-index' 已就绪" │
75118
└────────────────────────────────────┬────────────────────────────────────────┘
76119
│
77120
▼
78121
┌─────────────────────────────────────────────────────────────────────────────┐
79122
│ HIGRESS AI GATEWAY │
80123
│ │
81124
│ ┌─────────────────────────────────────────────────────────────────────┐ │
82-
│ │ MCP Server: weather-mcp-server │ │
125+
│ │ MCP Server: stock-index-mcp-server │ │
83126
│ │ ├─ 真实凭证: sk_xxx（安全存储，永不暴露） │ │
84-
│ │ ├─ 工具: get_forecast(city: string) → 天气数据 │ │
127+
│ │ ├─ 工具: get_index(symbol: string) → 股票指数数据 │ │
85128
│ │ └─ 授权消费者: manager, worker-alice, worker-bob │ │
86129
│ └─────────────────────────────────────────────────────────────────────┘ │
87130
│ │
@@ -96,20 +139,36 @@ mcporter call github.search_repositories query="hiclaw" limit=5
96139
│ │
97140
│ 1. 收到 Manager 的通知 │
98141
│ 2. 从 MinIO 拉取最新的 mcporter 配置 │
99-
│ 3. 发现工具：mcporter list weather --schema │
100-
│ 4. 测试工具：mcporter call weather.get_forecast city=Shanghai │
142+
│ 3. 发现工具：mcporter list stock-index --schema │
143+
│ 4. 测试工具：mcporter call stock-index.get_index symbol=000001.SH │
101144
│ 5. 基于理解生成 SKILL.md │
102145
│ 6. 后续任务中即可使用该工具！ │
103146
│ │
104147
│ ┌─────────────────────────────────────────────────────────────────────┐ │
105148
│ │ Worker 的视角： │ │
106149
│ │ ├─ 拥有：Consumer token（就像一张"工牌"） │ │
107-
│ │ ├─ 可以：通过网关调用 weather.get_forecast │ │
150+
│ │ ├─ 可以：通过网关调用 stock-index.get_index │ │
108151
│ │ └─ 不可以：看到真实的 API key sk_xxx │ │
109152
│ └─────────────────────────────────────────────────────────────────────┘ │
110153
└─────────────────────────────────────────────────────────────────────────────┘
111154
```
112155

156+
配置完成后，Manager 可以在 **Higress 控制台**查看 MCP Server 下的工具列表，并进行进一步的权限管理：
157+
158+
![Higress MCP 工具管理界面](https://img.alicdn.com/imgextra/i3/O1CN01armHyk1Lc9XTGz7ZX_!!6000000001319-2-tps-1452-849.png)
159+
160+
通过控制台，你可以：
161+
- 查看 MCP Server 包含的所有工具
162+
- 为每个 Consumer（Worker）配置 MCP Server 级别的访问权限
163+
- 监控工具调用情况和性能指标
164+
- 动态调整权限策略，无需重启服务
165+
166+
> **权限管理说明**：
167+
> - **Higress 开源版**：支持 **MCP Server 粒度**的权限管理（例如：Worker A 可以访问整个 `stock-index` MCP Server）
168+
> - **Higress 企业版**：支持 **工具粒度**的权限管理（例如：Worker A 只能调用 `stock-index.get_index`，但不能调用 `stock-index.update_index`）
169+
>
170+
> HiClaw 1.0.6 基于开源版实现了 MCP Server 级别的安全隔离，已能满足大部分企业场景的权限管控需求。
171+
113172
**核心安全原则：Worker 永远看不到真实凭证。**
114173

115174
即使 Worker 被完全攻破，攻击者也只能获得一个 consumer token：

0 commit comments

Comments
 (0)