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