ClawHub

Mcp Client

MCP Tools

MCP Client skill connects and manages MCP servers via stdio or SSE, supporting tool calls, resource reads, prompts, permission control, auditing, and error h...

Install

openclaw skills install yuyonghao-mcp-client

MCP Client Skill

version: 0.1.0

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

功能特性

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

安装

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

# 安装依赖
npm install

配置

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

{
  "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 集成"
  }
}

使用方法

命令行

# 列出已配置的服务器
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

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();

直接使用客户端

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 协议的服务器
  • 配置示例：
{
  "id": "remote-server",
  "name": "Remote MCP Server",
  "type": "sse",
  "url": "http://localhost:3000/sse",
  "headers": {
    "Authorization": "Bearer token"
  }
}

安全特性

权限控制

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

审计日志

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

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

错误处理

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 - 不支持的传输类型

测试

# 运行所有测试
npm test

# 运行基础测试
npm run test

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

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

项目结构

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

More in MCP Tools