MCP客户端TypeScript-重构版
一个强大的企业级TypeScript客户端，用于使用本地LLM与模型上下文协议（MCP）服务器进行交互。此版本具有完全重构的架构，具有最佳实践、依赖注入、全面的错误处理和事件驱动设计。
🎯 主要特点
建筑与设计模式
- 🏗️ 依赖注入：IoC容器的关注点完全分离
- 📐 坚实的原则：接口隔离、依赖倒置和单一责任
- 🎭 结果模式：无例外的类型安全错误处理
- 📨 事件驱动架构：用于松耦合的发布/订阅消息
- 🔄 重试策略：可配置的指数/线性抖动回退
- ⚡ 断路器型式：优雅的退化和健康检查
增强的错误处理
- 🛡️ 自定义错误类：具有适当堆栈跟踪的分层错误类型
- 📊 错误上下文：包含原因和上下文的丰富错误信息
- 🔍 验证：基于Zod的配置和输入验证
- 🚨 故障弱化：强大的错误恢复和回退机制
可观测性和监测
- 📈 结构化日志记录：可配置的日志级别，带有上下文和子日志记录器
- 📊 事件跟踪：用于监视和调试的应用程序事件
- 🏥 健康检查：服务健康监测和诊断
- ⏱️ 性能指标：持续时间跟踪和绩效洞察
开发者体验
- 🔧 类型安全：全面的TypeScript类型和接口
- 🎛️ 配置管理：基于环境的配置，带有验证功能
- 🔌 插件架构：可扩展的服务容器和中间件
- 🧪 可测试性：依赖注入使单元测试变得容易
📁 项目结构
src/
├── application/ # Application layer and bootstrapping
│ ├── application-builder.ts # DI container configuration
│ └── mcp-client-app.ts # Main application class
├── config/ # Configuration management
│ ├── configuration.ts # Zod-based config validation
│ └── index.ts # Configuration exports
├── container/ # Dependency injection
│ └── service-container.ts # IoC container implementation
├── errors/ # Custom error classes
│ └── index.ts # Error hierarchy and utilities
├── events/ # Event-driven architecture
│ └── event-bus.ts # Pub/sub event bus
├── interfaces/ # Type definitions and contracts
│ └── index.ts # All interfaces and types
├── services/ # Business logic layer
│ ├── llm.ts # Enhanced LLM service
│ ├── mcp.ts # Enhanced MCP service
│ └── chat.ts # Interactive chat service
├── utils/ # Utility functions and helpers
│ ├── logger.ts # Enhanced logging system
│ ├── result.ts # Result pattern implementation
│ ├── retry-strategy.ts # Retry logic with backoff
│ └── server.ts # Server utility functions
└── index.ts # Application entry point🚀 快速开始
安装
npm install配置
创建一个 .env 使用您的配置文件：
cp .env.example .env编辑 .env 使用您的设置：
# Required: LLM Configuration
LOCAL_LLM_BASE_URL=http://localhost:11434/v1
LOCAL_LLM_MODEL=llama3.2:3b
LOCAL_LLM_API_KEY=not-needed
# Optional: Application Settings
CLIENT_NAME=my-mcp-client
CLIENT_VERSION=1.0.0
MAX_TOKENS=2000
# Optional: Logging Configuration
LOG_LEVEL=info
ENABLE_FILE_LOGGING=false
LOG_FILE_PATH=logs/mcp-client.log
# Optional: Server Configuration
CONNECTION_TIMEOUT=30000
RETRY_ATTEMPTS=3
RETRY_DELAY=1000构建并运行
# Build the project
npm run build
# Run with a server script
npm start path/to/server.js
# Development mode (auto-rebuild)
npm run dev path/to/server.py示例用法
# Using the included simple server
npm start simple-mcp-server.js
# Using a Python MCP server
npm start path/to/your/server.py
# With debug logging
LOG_LEVEL=debug npm start simple-mcp-server.js🛠️ 开发脚本
npm run build-将TypeScript构建为JavaScriptnpm run dev-构建并运行开发模式npm run clean-清理构建目录npm run rebuild-清洁建造和重建npm run lint-不发送文件的类型检查npm run validate-运行linting并构建验证npm run health-项目快速健康检查npm run check-deps-检查过时的依赖关系npm run update-deps-更新依赖关系
🏗️ 建筑深潜
依赖注入容器
应用程序使用自定义IoC容器来管理依赖关系：
// Service registration
container.registerSingleton(ServiceKeys.LOGGER, () => createLogger(config));
container.registerSingleton(ServiceKeys.LLM_SERVICE, () =>
new LLMService(config, logger, retryStrategy, eventBus)
);
// Service resolution
const llmService = container.resolve(ServiceKeys.LLM_SERVICE);错误处理的结果模式
操作返回，而不是抛出异常 Result:
const configResult = loadConfig();
if (configResult.failure) {
console.error('Configuration error:', configResult.error);
return;
}
const config = configResult.data;事件驱动架构
服务通过事件进行沟通：
// Publishing events
eventBus.publish({
type: 'connection.established',
timestamp: new Date(),
data: { serverPath, toolCount }
});
// Subscribing to events
eventBus.subscribe('tool.executed', (event) => {
logger.info('Tool executed', event.data);
});重试策略
具有指数回退的可配置重试逻辑：
const retryStrategy = RetryStrategyFactory.exponentialBackoff({
maxAttempts: 3,
baseDelay: 1000,
maxDelay: 30000,
backoffFactor: 2,
jitter: true
});
const result = await retryStrategy.execute(operation, {
operationName: 'connectToServer'
});📋 配置参考
所需的环境变量
LOCAL_LLM_BASE_URL-本地LLM API的基本URLLOCAL_LLM_MODEL-要使用的型号名称LOCAL_LLM_API_KEY-用于身份验证的API密钥
可选环境变量
应用程序设置
CLIENT_NAME-自定义客户端名称（默认：“mcp-client-cli”）CLIENT_VERSION-自定义客户端版本（默认：“1.0.0”）MAX_TOKENS-每个请求的最大令牌数（默认值：1000）
日志记录配置
LOG_LEVEL-日志记录级别：“调试”、“信息”、“警告”、“错误”（默认值：“信息”）ENABLE_FILE_LOGGING-启用文件日志记录（默认值：false）LOG_FILE_PATH-日志文件的路径（默认：无）
服务器配置
CONNECTION_TIMEOUT-连接超时（毫秒）（默认值：30000）RETRY_ATTEMPTS-重试次数（默认值：3）RETRY_DELAY-基本重试延迟（毫秒）（默认值：1000）
🔌 支持的LLM API
此客户端可与任何与OpenAI兼容的API配合使用：
- 没有 （建议用于当地开发）
- LM工作室
- 本地AI
- OpenAI API
- 任何与OpenAI兼容的端点
示例配置
本地（Local）
LOCAL_LLM_BASE_URL=http://localhost:11434/v1
LOCAL_LLM_MODEL=llama3.2:3b
LOCAL_LLM_API_KEY=not-neededLM工作室
LOCAL_LLM_BASE_URL=http://localhost:1234/v1
LOCAL_LLM_MODEL=your-model-name
LOCAL_LLM_API_KEY=not-neededOpenAI
LOCAL_LLM_BASE_URL=https://api.openai.com/v1
LOCAL_LLM_MODEL=gpt-4
LOCAL_LLM_API_KEY=your-openai-api-key🧪 测试和质量保证
代码质量
- TypeScript严格模式：全类型安全和编译时检查
- 接口隔离：合同和依赖关系界限清晰
- 错误处理：全面的错误类型和恢复策略
- 日志记录：具有可配置级别和上下文的结构化日志记录
架构验证
- 依赖注入：松耦合和高可测试性
- 事件驱动设计：具有发布/订阅消息的反应式架构
- 结果模式：无例外的类型安全错误处理
- 配置验证：基于Zod的模式验证
🚀 可扩展性
性能特点
- 连接池：高效的资源管理
- 重试逻辑：具有抖动的智能退避策略
- 健康检查：主动服务监控
- 故障弱化：容错操作
监测和可观察性
- 结构化日志记录：丰富的上下文和可搜索的日志
- 事件跟踪：应用程序行为洞察
- 性能指标：持续时间和成功率跟踪
- 错误分析：详细的错误上下文和模式
🔒 安全考虑
- 输入验证：对所有输入进行基于Zod的模式验证
- 错误清理：无信息泄露的安全错误消息
- 环境变量：安全配置管理
- 类型安全：针对常见漏洞的编译时间保证
📝 从以前版本迁移
重构后的版本在提供增强功能的同时保持了向后兼容性：
突破性变化
- 现在需要为服务注入施工人员
- 配置加载返回结果类型
- 错误处理使用结果模式而不是异常
迁移步骤
- 更新配置加载以处理结果类型
- 使用依赖注入容器进行服务解析
- 处理服务方法调用的结果类型
- 更新错误处理以使用结果模式
传统支持
旧的API仍然可以通过类型导出进行逐步迁移。
🤝 贡献
这个重构版本遵循企业级模式和实践：
- 坚实的原则：所有代码都遵循单一责任、开放/封闭、Liskov替换、接口隔离和依赖反转原则
- 清洁建筑：应用程序、域和基础架构层之间的明确分离
- 类型安全：具有严格模式的全面TypeScript覆盖率
- 错误处理：可预测错误处理的结果模式
- 测试：依赖注入实现了全面的单元测试
📄 许可证
国际协调委员会
🔗 需求
- Node.js>=18.0.0
- TypeScript 5.x
- 本地LLM服务器或兼容OpenAI的API
🌟 重构版本的新增功能
架构改进
- ✅ IoC容器的依赖注入
- ✅ 带有发布/订阅消息的事件驱动架构
- ✅ 类型安全错误处理的结果模式
- ✅ 采用指数回退的重试策略
- ✅ 通过Zod验证增强配置
开发者体验
- ✅ 使用子记录器和上下文进行结构化日志记录
- ✅ 全面的TypeScript类型和接口
- ✅ 健康检查和监测能力
- ✅ 优雅的关机和错误恢复
- ✅ 可扩展的插件就绪架构
可靠性和性能
- ✅ 连接超时和重试逻辑
- ✅ 用于服务呼叫的断路器模式
- ✅ 资源清理和内存管理
- ✅ 性能监控和指标
- ✅ 全面的错误分类和处理
这个重构版本代表了一个生产就绪的企业级实现，适用于复杂的应用程序和集成。