MCP Client Skill#

version: 0.1.0

MCP (Model Context Protocol) 客户端技能，用于连接和管理外部 MCP 服务器。

功能特性#

• 多传输支持: stdio、SSE (Server-Sent Events)
• 完整协议实现: 工具调用、资源读取、提示词获取
• 安全控制: 权限验证、敏感操作确认、审计日志
• 错误处理: 自动重试、详细错误码
• 事件系统: 连接状态、工具调用事件监听

安装#

bash

# 进入技能目录
cd skills/mcp-client

# 安装依赖
npm install

配置#

编辑 src/mcp-config.json 配置 MCP 服务器：

json

{
  "filesystem": {
    "id": "filesystem",
    "name": "Filesystem Server",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
    "description": "本地文件系统访问"
  },
  "github": {
    "id": "github",
    "name": "GitHub Server",
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_TOKEN": "your-token-here"
    },
    "description": "GitHub API 集成"
  }
}

使用方法#

命令行#

bash

# 列出已配置的服务器
npm run mcp list

# 连接到服务器
npm run mcp connect filesystem

# 列出可用工具
npm run mcp tools filesystem

# 调用工具
npm run mcp call filesystem read_file '{"path": "./package.json"}'

# 读取文件
npm run mcp read ./package.json

# 列出目录
npm run mcp ls ./src

# 搜索文件
npm run mcp search "*.js"

# 查看审计日志
npm run mcp audit

JavaScript API#

javascript

import { OpenClawMCPSkill } from './src/mcp-skill.js';

// 创建技能实例
const skill = new OpenClawMCPSkill({
  autoApprove: false,        // 是否需要用户批准
  requireApproval: true,     // 强制要求批准
  autoApprovePatterns: ['*:read_*'],  // 自动批准模式
  blockedPatterns: ['*:delete_*']     // 禁止模式
});

// 列出服务器
skill.listServers();

// 连接到服务器
await skill.connect('filesystem');

// 获取服务器信息
const info = await skill.getServerInfo('filesystem');
console.log(info);

// 列出工具
const tools = await skill.listTools('filesystem');

// 调用工具
const result = await skill.callTool('filesystem', 'read_file', {
  path: './package.json'
});

// 快捷方法
const content = await skill.readFile('./package.json');
const listing = await skill.listDirectory('./src');
const matches = await skill.searchFiles('*.js');

// 批准工具（后续调用无需确认）
skill.approveTool('filesystem', 'read_file', true);

// 获取审计日志
const logs = skill.getAuditLog(100);

// 关闭所有连接
await skill.closeAll();

直接使用客户端#

javascript

import { MCPClient, MCPServerConfig, MCPClientConfig } from './src/client.js';
import { SecureMCPClient } from './src/secure-client.js';

// 基础客户端
const client = new MCPClient(new MCPClientConfig({
  name: 'my-client',
  autoApprove: true
}));

// 安全客户端（带审计和重试）
const secureClient = new SecureMCPClient(
  new MCPClientConfig(),
  {
    requireApproval: true,
    blockedPatterns: ['*:delete_*']
  }
);

// 配置服务器
const serverConfig = new MCPServerConfig({
  id: 'my-server',
  name: 'My Server',
  type: 'stdio',
  command: 'node',
  args: ['server.js']
});

// 连接
await client.connect(serverConfig);

// 获取能力
const capabilities = await client.getServerCapabilities('my-server');

// 列出工具
const tools = await client.listTools('my-server');

// 调用工具
const result = await client.callTool('my-server', 'tool_name', {
  arg1: 'value1'
});

// 列出资源
const resources = await client.listResources('my-server');

// 读取资源
const resource = await client.readResource('my-server', 'file:///path');

// 列出提示词
const prompts = await client.listPrompts('my-server');

// 获取提示词
const prompt = await client.getPrompt('my-server', 'prompt_name', {
  arg1: 'value1'
});

// 事件监听
client.on('connected', (data) => {
  console.log('Connected:', data.serverId);
});

client.on('toolCalled', (data) => {
  console.log('Tool called:', data.toolName);
});

client.on('resourceRead', (data) => {
  console.log('Resource read:', data.resourceUri);
});

// 断开连接
await client.disconnect('my-server');

支持的 MCP 服务器#

stdio 类型#

• @modelcontextprotocol/server-filesystem - 文件系统访问
• @modelcontextprotocol/server-github - GitHub API
• @modelcontextprotocol/server-postgres - PostgreSQL 数据库
• @modelcontextprotocol/server-sqlite - SQLite 数据库

SSE 类型#

• 任何支持 MCP SSE 协议的服务器
• 配置示例：

json

{
  "id": "remote-server",
  "name": "Remote MCP Server",
  "type": "sse",
  "url": "http://localhost:3000/sse",
  "headers": {
    "Authorization": "Bearer token"
  }
}

安全特性#

权限控制#

• 工具调用需要用户批准（可配置）
• 资源访问需要用户批准
• 敏感路径自动检测（.env、.git、/etc/passwd 等）

审计日志#

javascript

// 获取审计日志
const logs = client.getAuditLog(100);

// 日志格式
{
  timestamp: Date,
  action: 'tool_call' | 'resource_read' | 'connect' | ...,
  details: { ... }
}

错误处理#

javascript

try {
  await client.callTool('server', 'tool', args);
} catch (error) {
  console.log(error.code);      // 错误码
  console.log(error.message);   // 错误消息
  console.log(error.details);   // 详细信息
}

错误码：

• CONNECTION_FAILED - 连接失败
• CONNECTION_NOT_FOUND - 未找到连接
• TOOL_EXECUTION_FAILED - 工具执行失败
• RESOURCE_READ_FAILED - 资源读取失败
• PERMISSION_DENIED - 权限拒绝
• UNSUPPORTED_TRANSPORT - 不支持的传输类型

测试#

bash

# 运行所有测试
npm test

# 运行基础测试
npm run test

# 运行安全测试
npm run test:security

# 运行集成测试（需要实际 MCP 服务器）
npm run test:filesystem

项目结构#

text

skills/mcp-client/
├── src/
│   ├── client.js        # 基础 MCP 客户端
│   ├── secure-client.js # 带安全控制的客户端
│   ├── mcp-skill.js     # OpenClaw 技能接口
│   └── mcp-config.json  # 服务器配置
├── test/
│   ├── client.test.js       # 基础功能测试
│   ├── security.test.js     # 安全控制测试
│   ├── mcp-servers.test.js  # 集成测试
│   └── github-server.js     # GitHub 服务器测试
├── package.json
├── SKILL.md
└── README.md

依赖#

• @modelcontextprotocol/sdk - 官方 MCP SDK
• zod - 类型验证（可选）

协议版本#

• MCP Protocol: 2024-11-05
• SDK Version: ^1.0.0

许可证#

MIT