AI导哈

模型上下文协议服务器

一个全面的模型上下文协议（MCP）服务器，提供集中通信、服务编排、负载均衡、高级错误处理、实时WebSocket通信、性能优化、安全功能和全面的监控能力。

  • by Surya07102000
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Surya07102000/Notes-MCP-Server

使用说明

增强型MCP服务器

一个全面的模型上下文协议（MCP）服务器，具有集中通信、服务编排、负载平衡、高级错误处理、实时WebSocket通信、性能优化、安全功能和全面的监控功能。

🎯 项目状态

✅ 功能齐全，可投入生产 -增强型MCP服务器已完成并成功运行！

  • ✅ 100%测试成功率 -全部12个端到端测试通过
  • ✅ 所有第1阶段功能均已实施和测试
  • ✅ 已实施并测试所有第2阶段高级功能
  • ✅ 服务器启动时没有错误
  • ✅ 所有7项核心服务+4项高级服务已注册并投入运营
  • ✅ 5个可用的笔记管理工具
  • ✅ 负载平衡和连接池处于活动状态
  • ✅ 错误处理和恢复系统正在运行
  • ✅ 实时WebSocket通信工作
  • ✅ 性能优化功能已激活
  • ✅ 已实施和测试的安全功能
  • ✅ 全面的监控和分析操作
  • ✅ MCP协议通信已验证
  • ✅ 文件操作正常工作
  • ✅ 生产就绪，配备全面的测试套件

特性

🚀 核心功能（第一阶段）

  • 集中通信：用于服务编排的统一通信层
  • 服务编排：先进的服务管理和协调
  • 负载平衡：多种负载平衡策略（循环、最少连接、加权等）
  • 连接池：通过健康监测进行高效的连接管理
  • 模块化架构：将关注点与基于服务的设计彻底分离

🛡️ 可靠性和性能

  • 断路器型式：自动故障检测和恢复
  • 错误处理：全面的错误分类和恢复策略
  • 请求/响应管理：高级响应格式化和缓存
  • 健康监测：实时服务健康检查和指标
  • 优雅地关闭：通过资源清理来清理服务终止

🔧 中间件和配置

  • 中间件系统：用于请求/响应处理的可插拔中间件
  • 配置管理：基于环境的配置和验证
  • 速率限制：内置速率限制和请求限制
  • CORS支持：跨源资源共享配置
  • 日志记录：使用Winston进行结构化日志记录

🌐 高级功能（第2阶段）

  • 实时WebSocket通信：实时聊天、通知和房间管理
  • 性能优化：高级缓存（LRU、TTL）、压缩、异步处理
  • 安全功能：JWT身份验证、输入验证、速率限制、IP阻止
  • 综合监控：实时指标、系统监控、业务分析
  • 端到端测试：自动化测试套件，成功率100%

🔧 第二阶段服务

  • WebSocket管理器：实时通信、聊天室、通知
  • 性能优化器：LRU缓存、TTL缓存、Gzip压缩、异步处理
  • 安全经理：JWT身份验证、输入验证、速率限制、IP阻止
  • 监控分析：实时指标、系统监控、业务分析、警报

建筑

┌─────────────────────────────────────────────────────────────┐
│                    Enhanced MCP Server                     │
├─────────────────────────────────────────────────────────────┤
│  Security Layer (JWT Auth, Input Validation, Rate Limiting)│
├─────────────────────────────────────────────────────────────┤
│  Middleware Layer (CORS, Compression, Request Processing)  │
├─────────────────────────────────────────────────────────────┤
│  Request Handler (MCP Protocol Implementation)             │
├─────────────────────────────────────────────────────────────┤
│  Service Orchestration Layer                               │
│  ├── Communication Manager                                 │
│  ├── Service Registry                                      │
│  └── Load Balancer                                         │
├─────────────────────────────────────────────────────────────┤
│  Advanced Services Layer (Phase 2)                        │
│  ├── WebSocket Manager (Real-time Communication)          │
│  ├── Performance Optimizer (Caching, Compression)         │
│  ├── Security Manager (Auth, Validation, Monitoring)      │
│  └── Monitoring & Analytics (Metrics, Alerts, Reports)    │
├─────────────────────────────────────────────────────────────┤
│  Infrastructure Layer                                      │
│  ├── Connection Pool                                       │
│  ├── Error Handler                                         │
│  └── Response Manager                                      │
├─────────────────────────────────────────────────────────────┤
│  Tools Layer (Notes Management)                           │
└─────────────────────────────────────────────────────────────┘

安装

  1. 克隆存储库：
git clone <repository-url>
cd notes-mcp-server
  1. 安装依赖项：
npm install
  1. 配置服务器（可选）：
# The server comes with a default config.json file
# Edit config.json with your settings if needed
  1. 初始化Git存储库（如果尚未完成）：
git init
git add .
git commit -m "Initial commit: Enhanced MCP Server"

📁 项目文件

核心文件

  • src/server.js -主服务器实现
  • src/config/index.js -配置管理
  • config.json -服务器配置
  • package.json -依赖关系和脚本

服务

  • src/services/CommunicationManager.js -服务编排
  • src/services/ResponseManager.js -响应处理
  • src/services/ErrorHandler.js -错误管理
  • src/services/ConnectionPool.js -连接池
  • src/services/LoadBalancer.js -负载平衡
  • src/services/ServiceRegistry.js -服务注册表
  • src/services/WebSocketManager.js -实时WebSocket通信
  • src/services/PerformanceOptimizer.js -性能优化和缓存
  • src/services/SecurityManager.js -安全性、身份验证和确认
  • src/services/MonitoringAnalytics.js -监控、指标和分析

工具

  • src/tools/listNotes.js -列表注释工具
  • src/tools/readNote.js -阅读笔记工具
  • src/tools/createNote.js -创建笔记工具
  • src/tools/updateNote.js -更新笔记工具
  • src/tools/deleteNote.js -删除笔记工具

测试和文件

  • tests/run-e2e.js -端到端测试流道
  • tests/e2e/TestSuite.js -全面的测试套件
  • quick-test.js -快速测试脚本
  • test-simple.js -高级测试脚本
  • test-client.js -MCP测试客户端
  • README.md -本文件
  • TESTING_GUIDE.md -详细的测试说明
  • PHASE2_FEATURES.md -第2阶段特征文件
  • .gitignore -Git忽略规则

自动生成

  • notes/ -Notes存储目录（自动创建）
  • node_modules/ -依赖关系（由npm install创建）

快速开始

服务器已准备好开箱即用！只需从以下内容开始：

npm start

您应该看到如下输出：

2025-09-12T10:12:33.679Z [INFO] Service registered: tool-list-notes (list-notes)
2025-09-12T10:12:33.685Z [INFO] Service registered: tool-read-note (read-note)
2025-09-12T10:12:33.685Z [INFO] Service registered: tool-create-note (create-note)
2025-09-12T10:12:33.685Z [INFO] Service registered: tool-update-note (update-note)
2025-09-12T10:12:33.685Z [INFO] Service registered: tool-delete-note (delete-note)
2025-09-12T10:12:33.686Z [INFO] Service registered: communication-manager (Communication Manager)
2025-09-12T10:12:33.686Z [INFO] Service registered: load-balancer (Load Balancer)
2025-09-12T10:12:33.688Z [INFO] Starting Enhanced MCP Server...
2025-09-12T10:12:34.364Z [INFO] Enhanced MCP Server started successfully
2025-09-12T10:12:34.365Z [INFO] Server: enhanced-notes-mcp-server v2.0.0
2025-09-12T10:12:34.366Z [INFO] Notes directory: ./notes
2025-09-12T10:12:34.367Z [INFO] Registered tools: 5
2025-09-12T10:12:34.367Z [INFO] Registered services: 7

🧪 测试

全面的端到端测试

以100%的成功率运行完整的测试套件：

npm test

这将验证所有12个测试类别：

  • ✅ 服务器启动 -服务器初始化和启动
  • ✅ 服务注册 -全部7项核心服务+4项高级服务
  • ✅ MCP协议通信 -JSON-RPC协议处理
  • ✅ 工具执行 -所有5个笔记管理工具
  • ✅ 文件操作 -文件创建、读取和管理
  • ✅ 错误处理 -错误场景和恢复
  • ✅ 演出 -响应时间和吞吐量
  • ✅ 安全 -身份验证和验证功能
  • ✅ WebSocket通信 -实时通信
  • ✅ 负载平衡 -负载分配和平衡
  • ✅ 监控 -指标收集和分析
  • ✅ 优雅地关闭 -清理服务器终止

预期测试结果

🚀 Enhanced MCP Server - End-to-End Test Runner
================================================
🧪 Starting End-to-End Test Suite
=====================================
🔍 Running: Server Startup
✅ Server Startup: PASSED (2454ms)
🔍 Running: Service Registration
✅ Service Registration: PASSED (1ms)
🔍 Running: MCP Protocol Communication
✅ MCP Protocol Communication: PASSED (12ms)
🔍 Running: Tool Execution
✅ Tool Execution: PASSED (7ms)
🔍 Running: File Operations
✅ File Operations: PASSED (2006ms)
🔍 Running: Error Handling
✅ Error Handling: PASSED (4ms)
🔍 Running: Performance
✅ Performance: PASSED (2017ms)
🔍 Running: Security
✅ Security: PASSED (4ms)
🔍 Running: WebSocket Communication
✅ WebSocket Communication: PASSED (1009ms)
🔍 Running: Load Balancing
✅ Load Balancing: PASSED (1ms)
🔍 Running: Monitoring
✅ Monitoring: PASSED (1ms)
🔍 Running: Graceful Shutdown
✅ Graceful Shutdown: PASSED (13ms)

📊 Test Results Summary
========================
✅ Passed: 12
❌ Failed: 0
📈 Success Rate: 100.0%

🎉 All tests passed! The enhanced MCP server is working perfectly.

快速测试

为了快速验证：

node quick-test.js

高级测试

详细测试：

node test-simple.js

用法

启动服务器

# Production mode
npm start

# Development mode with auto-reload
npm run dev

# Health check
npm run health

配置

服务器可以通过以下方式配置 config.json 或环境变量：

{
  "server": {
    "name": "enhanced-notes-mcp-server",
    "version": "2.0.0",
    "maxConnections": 100,
    "timeout": 30000
  },
  "services": {
    "orchestration": {
      "enabled": true,
      "maxConcurrentRequests": 50,
      "requestTimeout": 10000
    }
  },
  "middleware": {
    "rateLimit": {
      "enabled": true,
      "windowMs": 900000,
      "maxRequests": 100
    }
  }
}

环境变量

  • PORT：服务器端口（默认值：3000）
  • HOST：服务器主机（默认：localhost）
  • LOG_LEVEL：日志记录级别（默认值：info）
  • NOTES_DIR：Notes目录路径（默认：./Notes）

api参考

MCP工具

服务器提供以下MCP工具：

list-notes

列出所有可用的笔记。

参数： 无

答复：

{
  "content": [
    {
      "type": "text",
      "text": "[\"note1.txt\", \"note2.txt\"]"
    }
  ]
}

read-note

阅读特定笔记的内容。

参数：

  • noteName （string）：笔记文件的名称

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Note content here..."
    }
  ]
}

create-note

创建新笔记。

参数：

  • noteName （string）：笔记文件的名称
  • text （string）：注释内容

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Note 'noteName' created successfully."
    }
  ]
}

update-note

更新现有注释。

参数：

  • noteName （string）：笔记文件的名称
  • text （string）：注释的新内容

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Note 'noteName' updated successfully."
    }
  ]
}

delete-note

删除注释。

参数：

  • noteName （string）：笔记文件的名称

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Note 'noteName' deleted successfully."
    }
  ]
}

服务管理

服务注册中心

服务器维护所有可用服务的注册表：

// Get all services
const services = serviceRegistry.getAllServices();

// Get services by type
const toolServices = serviceRegistry.getServicesByType('tool');

// Get service health
const health = serviceRegistry.getRegistryHealth();

负载平衡

支持多种负载平衡策略：

  • 轮询：平均分配请求
  • 最少连接：活动连接最少的服务路线
  • 加权轮询算法：考虑服务重量
  • 最短响应时间：通往响应最快服务的路线
  • 基于优先级：基于服务优先级的路线
  • 随机：随机选择
// Set load balancing strategy
loadBalancer.setStrategy('least-connections');

健康监测

服务器提供全面的健康监控：

// Get overall health status
const health = server.getHealthStatus();

// Get service-specific health
const serviceHealth = serviceRegistry.getRegistryHealth();
const loadBalancerHealth = loadBalancer.getHealthStatus();

错误处理

服务器实现了复杂的错误处理：

错误类型

  • 服务错误：SERVICE_NOT_FOUND、SERVICE_UNAVAILABLE、SERVICE_TIMEOUT
  • 验证错误：VALIDATION_ERROR，INVALID_PARAMETERS
  • 身份验证错误：未经授权，禁止
  • 系统错误：内部错误，资源耗尽
  • 断路器错误：断路器_开路

恢复策略

  • 重试：使用指数回退自动重试
  • 后备方案：具有回退响应的优雅降级
  • 断路器：故障时自动隔离服务

监控和指标

响应统计

const stats = responseManager.getResponseStats();
// Returns: total, successful, failed, successRate, averageResponseTime

误差度量

const errorStats = errorHandler.getErrorMetrics();
// Returns: total, byType, byService, recent errors

连接池统计信息

const poolStats = connectionPool.getStats();
// Returns: total, available, busy, utilization percentage

发展

项目结构

enhanced-notes-mcp-server/
├── src/
│   ├── config/
│   │   └── index.js              # Configuration management
│   ├── middleware/
│   │   └── index.js              # Middleware system
│   ├── services/
│   │   ├── CommunicationManager.js  # Service orchestration
│   │   ├── ResponseManager.js       # Response handling
│   │   ├── ErrorHandler.js          # Error management
│   │   ├── ConnectionPool.js        # Connection pooling
│   │   ├── LoadBalancer.js          # Load balancing
│   │   ├── ServiceRegistry.js       # Service registry
│   │   ├── WebSocketManager.js      # Real-time WebSocket communication
│   │   ├── PerformanceOptimizer.js  # Performance optimization and caching
│   │   ├── SecurityManager.js       # Security, authentication, validation
│   │   └── MonitoringAnalytics.js   # Monitoring, metrics, analytics
│   ├── tools/
│   │   ├── listNotes.js         # List notes tool
│   │   ├── readNote.js          # Read note tool
│   │   ├── createNote.js        # Create note tool
│   │   ├── updateNote.js        # Update note tool
│   │   └── deleteNote.js        # Delete note tool
│   ├── logger.js                # Logging configuration
│   └── server.js                # Main server implementation
├── tests/
│   ├── e2e/
│   │   └── TestSuite.js         # Comprehensive end-to-end test suite
│   └── run-e2e.js               # End-to-end test runner
├── notes/                       # Notes storage directory (auto-created)
├── config.json                  # Server configuration
├── package.json                 # Project dependencies and scripts
├── README.md                    # This documentation
├── TESTING_GUIDE.md            # Detailed testing instructions
├── PHASE2_FEATURES.md          # Phase 2 features documentation
├── quick-test.js               # Quick test script
├── test-simple.js              # Advanced test script
├── test-client.js              # MCP client for testing
└── .gitignore                  # Git ignore rules

可用脚本

# Start the server
npm start

# Start with auto-reload (development)
npm run dev

# Run comprehensive end-to-end tests
npm test

# Run quick test
npm run test:quick

# Run simple test
npm run test:simple

# Run MCP client test
node test-client.js

# Health check
npm run health

# Start monitoring dashboard
npm run monitor

# Security audit
npm run security

添加新工具

  1. 在中创建新的工具文件 src/tools/:
export default function myTool(DATA_DIR) {
  return {
    name: "my-tool",
    description: "Description of my tool",
    aliases: ["myTool", "my_tool"],
    inputSchema: {
      type: "object",
      properties: {
        param1: { type: "string", description: "Parameter description" }
      },
      required: ["param1"]
    },
    execute: async ({ param1 }) => {
      // Tool implementation
      return {
        content: [{ type: "text", text: "Tool result" }]
      };
    }
  };
}
  1. 在中注册该工具 src/server.js:
import myTool from "./tools/myTool.js";

// Add to toolsList
this.toolsList = [
  // ... existing tools
  myTool(this.dataDir),
];

添加新服务

  1. 创建服务类：
class MyService {
  constructor() {
    this.name = 'MyService';
    this.version = '1.0.0';
  }
  
  async healthCheck() {
    return true;
  }
}
  1. 注册服务：
serviceRegistry.registerService({
  id: 'my-service',
  name: 'My Service',
  type: 'custom',
  version: '1.0.0',
  healthCheck: async () => myService.healthCheck()
});

🔧 Git设置

初始化Git仓库

# Initialize git repository
git init

# Add all files
git add .

# Create initial commit
git commit -m "Initial commit: Enhanced MCP Server with centralized communication and service orchestration"

# Add remote origin (replace with your repository URL)
git remote add origin <your-repository-url>

# Push to remote
git push -u origin main

Git工作流

# Check status
git status

# Add specific files
git add src/server.js

# Commit changes
git commit -m "Update server implementation"

# Push changes
git push origin main

# Create feature branch
git checkout -b feature/new-tool

# Merge feature branch
git checkout main
git merge feature/new-tool

Git忽略了什么

这 .gitignore 文件不包括：

  • node_modules/ -依赖关系
  • notes/ -用户笔记（包含敏感数据）
  • *.log -日志文件
  • .env* -环境文件
  • coverage/ -测试覆盖率
  • IDE文件(.vscode/, .idea/)
  • 操作系统文件(.DS_Store, Thumbs.db)
  • 临时文件(*.tmp, *.temp)

📄 许可证

ISC许可证

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/amazing-feature
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交您的更改： git commit -m 'Add amazing feature'
  6. 推到分支： git push origin feature/amazing-feature
  7. 提交拉取请求

🆘 支持

对于问题和疑问：

  • 在存储库中创建问题
  • 检查 TESTING_GUIDE.md 用于故障排除
  • 查看日志以了解错误详细信息

🎯 路线图

✅ 已完成的功能

  • [x] WebSocket支持实时通信
  • [x] 身份验证和授权（JWT）
  • [x] API速率限制和节流
  • [x] 指标和监控仪表板
  • [x] 性能优化和缓存
  • [x] 全面的安全功能
  • [x] 端到端测试套件
  • [x] 实时分析和监控

🚀 未来的增强功能

  • []用于持久存储的数据库集成
  • []Docker容器化
  • []Kubernetes部署清单
  • []GraphQL API支持
  • []微服务架构
  • []分布式缓存（Redis）
  • []消息队列（RabbitMQ/Apache Kafka）
  • []先进的AI/ML集成
  • []多租户支持
  • []高级报告和仪表板

相关 MCP