@人工智能功能套件/mcp客户群
共享MCP（模型上下文协议）客户端基类为VSCode扩展提供一致的超时处理、自动重新同步和连接状态管理。
特性
- 可配置超时：初始化与标准请求的超时值不同
- 自动重新同步：发生超时时的指数回退重试逻辑
- 连接状态管理：跟踪并通知侦听器连接状态更改
- 一致的错误处理：统一的错误消息和恢复选项
- 可扩展架构：扩展可以自定义的抽象基类
- 综合录井：带有时间戳和请求ID的结构化日志记录
- 诊断命令：用于解决连接问题的内置命令
安装
npm install @ai-capabilities-suite/mcp-client-base快速开始
import {
BaseMCPClient,
MCPClientConfig,
} from "@ai-capabilities-suite/mcp-client-base";
import * as vscode from "vscode";
// 1. Extend BaseMCPClient
export class MyMCPClient extends BaseMCPClient {
protected getServerCommand() {
return { command: "npx", args: ["-y", "@my-org/my-mcp-server"] };
}
protected getServerEnv() {
return { ...process.env };
}
protected async onServerReady() {
// Extension-specific initialization
}
}
// 2. Create and start the client
const outputChannel = vscode.window.createOutputChannel("My Extension", {
log: true,
});
const client = new MyMCPClient(outputChannel);
await client.start();
// 3. Use the client
const result = await client.callTool("my_tool", { param: "value" });文档
- API 参考 -完整的API文件
- 扩展BaseMCP客户端 -创建自定义MCP客户端指南
- 配置指南 -超时和重新同步配置
- 诊断命令 -故障排除和诊断工具
- 故障排除指南 -常见问题和解决方案
关键概念
连接状态
客户端通过状态机跟踪连接状态：
DISCONNECTED-未连接到服务器CONNECTING-正在尝试建立连接CONNECTED-已成功连接并准备就绪TIMEOUT_RETRYING-发生超时，正在尝试重新同步ERROR-发生不可恢复的错误
超时处理
不同的请求类型具有不同的超时值：
- 初始化：60秒（服务器启动可能很慢）
- 标准请求：30秒（正常操作）
- 工具列表：60秒（可能涉及发现）
重新同步
当初始化过程中发生超时时，客户端会自动尝试使用指数退避重新同步：
- 2秒后首次重试
- 3秒后第二次重试（2×1.5）
- 4.5秒后第三次重试（3×1.5）
使用示例
基本扩展
import { BaseMCPClient } from "@ai-capabilities-suite/mcp-client-base";
import * as vscode from "vscode";
export class MyMCPClient extends BaseMCPClient {
constructor(outputChannel: vscode.LogOutputChannel) {
super(outputChannel, {
timeout: {
initializationTimeoutMs: 60000,
standardRequestTimeoutMs: 30000,
toolsListTimeoutMs: 60000,
},
reSync: {
maxRetries: 3,
retryDelayMs: 2000,
backoffMultiplier: 1.5,
},
logging: {
logLevel: "info",
logCommunication: true,
},
});
}
protected getServerCommand() {
return {
command: "npx",
args: ["-y", "@my-org/my-mcp-server"],
};
}
protected getServerEnv() {
return { ...process.env };
}
protected async onServerReady() {
// Verify server is working
await this.callTool("health_check", {});
}
// Extension-specific methods
async doSomething(params: any): Promise {
return await this.callTool("my_tool", params);
}
}监控连接状态
const client = new MyMCPClient(outputChannel);
// Subscribe to state changes
const disposable = client.onStateChange((status) => {
console.log(`State: ${status.state}`);
console.log(`Message: ${status.message}`);
console.log(`Server Running: ${status.serverProcessRunning}`);
if (status.state === "ERROR") {
vscode.window.showErrorMessage(`Connection error: ${status.message}`);
}
});
await client.start();
// Later: cleanup
disposable.dispose();
client.stop();使用诊断命令
import { diagnosticCommands } from "@ai-capabilities-suite/mcp-client-base";
// Register your extension
diagnosticCommands.registerExtension({
name: "my-extension",
displayName: "My Extension",
client: myClient,
});
// Reconnect to server
await diagnosticCommands.reconnectToServer("my-extension");
// Restart server
await diagnosticCommands.restartServer("my-extension");
// Get diagnostics
const diag = diagnosticCommands.getDiagnostics("my-extension");
console.log(diagnosticCommands.formatDiagnostics(diag));
// Get all extensions status
const allDiag = diagnosticCommands.getAllDiagnostics();
console.log(diagnosticCommands.formatAllDiagnostics());配置
默认配置
{
timeout: {
initializationTimeoutMs: 60000, // 60 seconds
standardRequestTimeoutMs: 30000, // 30 seconds
toolsListTimeoutMs: 60000, // 60 seconds
},
reSync: {
maxRetries: 3, // 3 retry attempts
retryDelayMs: 2000, // 2 second initial delay
backoffMultiplier: 1.5, // 1.5x backoff multiplier
},
logging: {
logLevel: 'info', // info level logging
logCommunication: true, // log all communication
},
}自定义配置
const client = new MyMCPClient(outputChannel, {
timeout: {
initializationTimeoutMs: 120000, // 2 minutes for slow servers
standardRequestTimeoutMs: 45000, // 45 seconds for slow operations
},
reSync: {
maxRetries: 5, // More retry attempts
retryDelayMs: 1000, // Faster initial retry
backoffMultiplier: 2.0, // Aggressive backoff
},
logging: {
logLevel: "debug", // Verbose logging
logCommunication: true,
},
});建筑
该包由四个主要部分组成：
- BaseMCP客户端 -具有核心功能的抽象基类
- 超时管理器 -可配置的超时处理
- 连接状态管理器 -连接状态跟踪和通知
- 无效的管理器 -具有指数回退的自动重新同步
┌─────────────────────────────────────────────────────────────┐
│ @ai-capabilities-suite/mcp-client-base │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ BaseMCPClient (Abstract) │ │
│ │ ┌──────────────┐ ┌────────────────┐ ┌───────────┐ │ │
│ │ │ Timeout │ │ Re-sync Logic │ │ Request │ │ │
│ │ │ Manager │ │ │ │ Queue │ │ │
│ │ └──────────────┘ └────────────────┘ └───────────┘ │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ ConnectionStateManager │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
▲
│ extends
┌─────────────────┼─────────────────┐
│ │ │
┌─────────┴──────┐ ┌──────┴───────┐ ┌──────┴───────┐
│ MCPProcessClient│ │MCPScreenshot │ │MCPDebugger │
│ │ │ Client │ │ Client │
└─────────────────┘ └──────────────┘ └──────────────┘测试
该包包括全面的测试：
- 单元测试 -单独测试单个组件
- 基于属性的测试 -验证所有输入的正确性属性
- 集成测试 -测试完整的客户端生命周期
运行测试：
npm test贡献
欢迎投稿！请确保：
- 所有测试均通过
- 新功能包括测试
- 文档已更新
- 代码遵循现有样式
许可证
麻省理工学院