npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.0 - Mend

sinapse-ai 5.0.8 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/zh/guides/mcp/docker-gateway-tutorial.md DELETED Viewed

@@ -1,336 +0,0 @@
-# Docker Gateway MCP 教程
-> **EN** | [PT](../../pt/guides/mcp/docker-gateway-tutorial.md) | **ZH**
----
-Docker Gateway 是一个 MCP 服务器，充当 Claude Code 和多个运行在 Docker 容器内的 MCP 服务器之间的**桥梁**。
-**版本：** 1.0.0
-**最后更新：** 2026-01-28
----
-## 什么是 Docker Gateway?
-Docker Gateway 是一个 MCP 服务器，充当 Claude Code 和多个运行在 Docker 容器内的 MCP 服务器之间的**桥梁**。
-### 关键优势：无额外 Token 成本
-当 MCP 在 docker-gateway 内运行时，它们的工具定义被**封装**在容器中。这意味着：
-| 配置                       | Token 成本      | 上下文中的工具定义     |
-| -------------------------- | --------------- | ---------------------- |
-| 直接在 ~/.claude.json 中   | 每个 MCP 增加   | 是的，所有工具架构可见 |
-| 在 docker-gateway 内       | **无额外成本**  | 在容器中封装           |
-**原因？** Claude Code 仅看到 docker-gateway 工具（`mcp-add`、`mcp-find` 等），而不是容器内每个 MCP 的单个工具。实际工具通过网关调用。
----
-## 前置要求
-- **Docker Desktop** 4.37+ 已安装且正在运行
-- **Claude Code** CLI 已安装
-- 所需 MCP 服务的 API 密钥
----
-## 步骤 1：初始化 Docker MCP 工具包
-```bash
-# 初始化目录系统
-docker mcp catalog init
-# 验证初始化
-docker mcp catalog ls
-```
-**预期输出：**
-```
-docker-mcp: Docker MCP Catalog
-```
-目录包含 313+ 个可用的 MCP 服务器。
----
-## 步骤 2：浏览可用服务器
-```bash
-# 列出所有可用服务器
-docker mcp catalog show docker-mcp
-# 搜索特定服务器
-docker mcp catalog show docker-mcp | grep -i apify
-docker mcp catalog show docker-mcp | grep -i exa
-```
----
-## 步骤 3：启用 MCP 服务器
-```bash
-# 启用你想要使用的服务器
-docker mcp server enable apify-mcp-server
-docker mcp server enable exa
-docker mcp server enable context7
-# 列出已启用的服务器
-docker mcp server ls
-```
----
-## 步骤 4：配置 API 密钥
-### 方法 1：使用 Docker MCP 秘密（可能有 bug）
-```bash
-# 设置秘密
-docker mcp secret set APIFY_TOKEN "your-apify-token"
-docker mcp secret set EXA_API_KEY "your-exa-api-key"
-```
-### 方法 2：直接编辑目录文件（推荐的解决方案）
-由于已知 bug（2025 年 12 月），秘密可能无法正确传递到容器。
-**解决方案：** 直接编辑 `~/.docker/mcp/catalogs/docker-mcp.yaml`：
-```yaml
-# 找到你的 MCP 条目并添加 env 值
-apify-mcp-server:
-  env:
-    - name: APIFY_TOKEN
-      value: 'apify_api_xxxxxxxxxxxxx'
-    - name: TOOLS
-      value: 'actors,docs,apify/rag-web-browser'
-exa:
-  env:
-    - name: EXA_API_KEY
-      value: 'your-exa-api-key-here'
-```
-⚠️ **安全注意：** 这会在本地文件中暴露凭证。设置适当的文件权限：
-```bash
-chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
-```
----
-## 步骤 5：配置 Claude Code
-将 docker-gateway 添加到 `~/.claude.json`：
-```json
-{
-  "mcpServers": {
-    "docker-gateway": {
-      "type": "stdio",
-      "command": "docker",
-      "args": ["mcp", "gateway", "run"]
-    }
-  }
-}
-```
-或使用 Claude CLI：
-```bash
-claude mcp add docker-gateway -s user -- docker mcp gateway run
-```
----
-## 步骤 6：验证设置
-```bash
-# 检查通过网关可用的工具
-docker mcp tools ls
-# 预期输出显示网关工具 + 已启用服务器工具
-# 示例：58 个工具（7 个网关 + 来自已启用服务器的 51 个）
-```
-在 Claude Code 中：
-```bash
-# 列出 MCP 状态
-claude mcp list
-# 应该显示：
-# docker-gateway: docker mcp gateway run - ✓ Connected
-```
----
-## 使用 Docker Gateway
-### 可用的网关工具
-| 工具                | 描述                       |
-| ------------------- | -------------------------- |
-| `mcp-add`           | 将 MCP 服务器添加到当前会话 |
-| `mcp-find`          | 在目录中搜索服务器          |
-| `mcp-remove`        | 从会话中删除 MCP 服务器     |
-| `mcp-exec`          | 从已启用的服务器执行工具    |
-| `mcp-config-set`    | 配置 MCP 服务器设置         |
-| `code-mode`         | 创建组合的 JavaScript 工具 |
-| `mcp-create-profile` | 保存当前网关状态           |
-### 访问已启用服务器的工具
-服务器启用后，它们的工具可通过网关访问：
-```
-# Apify 工具（通过 docker-gateway）
-mcp__docker-gateway__search-actors
-mcp__docker-gateway__call-actor
-mcp__docker-gateway__apify-slash-rag-web-browser
-# EXA 工具（通过 docker-gateway）
-mcp__docker-gateway__web_search_exa
-mcp__docker-gateway__company_research
-# Context7 工具（通过 docker-gateway）
-mcp__docker-gateway__resolve-library-id
-mcp__docker-gateway__query-docs
-```
----
-## 完整示例配置
-### ~/.claude.json
-```json
-{
-  "mcpServers": {
-    "desktop-commander": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@wonderwhy-er/desktop-commander"]
-    },
-    "docker-gateway": {
-      "type": "stdio",
-      "command": "docker",
-      "args": ["mcp", "gateway", "run"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@anthropic/mcp-playwright"]
-    }
-  }
-}
-```
-### 结果
-```
-用户 MCP（4 个服务器）：
-├── desktop-commander  ✓ 已连接
-├── docker-gateway     ✓ 已连接  (58 个工具在内部)
-├── playwright         ✓ 已连接
-└── n8n-mcp           ✓ 已连接
-在 docker-gateway 内部：
-├── apify-mcp-server   (7 个工具)
-├── exa                (8 个工具)
-├── context7           (2 个工具)
-└── + 网关工具         (7 个工具)
-```
----
-## 故障排除
-### 网关无法启动
-```bash
-# 检查 Docker 是否正在运行
-docker info
-# 检查网关日志
-docker mcp gateway run --verbose
-```
-### 工具显示为"(N prompts)"而不是"(N tools)"
-这表示身份验证失败。使用解决方案：
-```bash
-# 使用硬编码凭证直接编辑目录
-nano ~/.docker/mcp/catalogs/docker-mcp.yaml
-```
-### 找不到服务器
-```bash
-# 更新目录
-docker mcp catalog update
-# 验证服务器是否存在
-docker mcp catalog show docker-mcp | grep -i "server-name"
-```
-### 重置所有内容
-```bash
-# 禁用所有服务器
-docker mcp server reset
-# 重置目录
-docker mcp catalog reset
-# 重新初始化
-docker mcp catalog init
-```
----
-## 最佳实践
-### 1. 对基于 API 的 MCP 使用 docker-gateway
-将这些放在 docker-gateway 内（不需要主机访问）：
-- Apify（网络抓取 API）
-- EXA（搜索 API）
-- Context7（文档 API）
-- 任何云/SaaS 集成
-### 2. 保持主机访问 MCP 直接连接
-在 ~/.claude.json 中直接保持这些：
-- desktop-commander（需要主机文件/终端访问）
-- playwright（需要主机浏览器）
-- 文件系统 MCP
-### 3. 保护你的凭证
-```bash
-# 设置限制性权限
-chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
-chmod 700 ~/.docker/mcp/
-# 从不提交这些文件
-echo "~/.docker/mcp/" >> ~/.gitignore_global
-```
----
-## 相关文档
-- [Desktop Commander MCP 指南](./desktop-commander.md)
-- [MCP 全局设置指南](../mcp-global-setup.md)
-- [Docker MCP 设置](../../docker-mcp-setup.md)
----
-_Docker Gateway MCP 教程 v1.0.0 - SINAPSE 框架_