MCP Customer Server cho Claude Desktop

Author: Tra, Nguyen
Email: [email protected]
SDT: 84937766469

📋 Mục lục

• 1. Cài đặt và chuẩn bị
• 2. Thiết lập biến môi trường
• 3. Cấu hình Claude Desktop
• 4. Các phương pháp kết nối
• 5. Tính năng có sẵn
• 6. AI Integration
• 7. Memory Integration
• 8. AWS Bedrock Integration
• 9. Kiểm tra hoạt động
• 10. Troubleshooting
• 11. Lưu ý bảo mật

1. Cài đặt và chuẩn bị

# Cài đặt dependencies
npm install

# Link package để sử dụng với npx
npm link

2. Thiết lập biến môi trường

Cách 1: Sử dụng file .env (Khuyến nghị cho development)

Tạo file .env trong thư mục gốc của dự án:

# Server Configuration
PORT=3000
MCP_HTTP_PORT=3001
GRPC_PORT=30000

# Elasticsearch Configuration
ELASTIC_NODE=http://localhost:9200
ELASTIC_INDEX=customers
ELASTIC_AUTH=true
ELASTIC_USERNAME=your_username
ELASTIC_PASSWORD=your_password
ELASTIC_SSL=false

# Logging Configuration
LOG_NODE=http://localhost:9200
LOG_USERNAME=your_username
LOG_PASSWORD=your_password

# Redis Configuration
REDIS_PORT=6379
REDIS_HOST=localhost
REDIS_PASSWORD=your_redis_password

# AI Configuration - Vendor Agnostic
AI_PROVIDER=gemini
AI_TEMPERATURE=0.7
AI_MAX_TOKENS=1024

# Google Gemini
GOOGLE_API_KEY=your_google_api_key
GEMINI_MODEL=gemini-2.0-flash

# OpenAI GPT
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4o-mini
OPENAI_ORGANIZATION=your_org_id

# Anthropic Claude
ANTHROPIC_API_KEY=your_anthropic_api_key
CLAUDE_MODEL=claude-3-haiku-20240307

# AWS Bedrock - Dual Authentication Support
AWS_REGION=us-east-1
BEDROCK_MODEL=anthropic.claude-3-haiku-20240307-v1:0
BEDROCK_API_KEY=your_bedrock_api_key
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key

Cách 2: Thiết lập trực tiếp trong Claude Desktop config

Sử dụng file cấu hình claude_desktop_config_example.json.

3. Cấu hình Claude Desktop

Vị trí file cấu hình:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

4. Các phương pháp kết nối

🔌 Phương pháp 1: Stdio Connection (Khuyến nghị)

{
  "mcpServers": {
    "mcp_customer_server": {
      "command": "npx",
      "args": ["mcp-customer-server"]
    }
  }
}

🌐 Phương pháp 2: HTTP Connection

Khởi động HTTP server:

npm run http

Cấu hình Claude Desktop:

{
  "mcpServers": {
    "mcp_customer_server": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

🚀 Phương pháp 3: HTTP Stream Connection (Mới)

HTTP Stream sử dụng Server-Sent Events (SSE) để cung cấp kết nối real-time với hiệu suất cao hơn.

Khởi động HTTP Stream server:

npm run http:stream

Cấu hình Claude Desktop:

{
  "mcpServers": {
    "mcp_customer_server": {
      "url": "http://localhost:3001/mcp",
      "transport": "sse"
    }
  }
}

Ưu điểm của HTTP Stream:

• ✅ Real-time streaming: Phản hồi nhanh hơn
• ✅ Better performance: Giảm latency
• ✅ Connection persistence: Kết nối bền vững
• ✅ Error recovery: Tự động reconnect

🔧 Phương pháp 4: Với biến môi trường tùy chỉnh

{
  "mcpServers": {
    "mcp_customer_server": {
      "command": "npx",
      "args": ["mcp-customer-server"],
      "env": {
        "ELASTIC_NODE": "http://your-elasticsearch:9200",
        "ELASTIC_USERNAME": "your_username",
        "ELASTIC_PASSWORD": "your_password",
        "REDIS_HOST": "your-redis-host",
        "REDIS_PASSWORD": "your_redis_password",
        "GOOGLE_API_KEY": "your_google_api_key",
        "AI_PROVIDER": "gemini"
      }
    }
  }
}

5. Tính năng có sẵn

Server cung cấp 3 tools chính:

🔍 1. search_customers

Tìm kiếm khách hàng theo tên, mã KH, hoặc số điện thoại

Tìm kiếm khách hàng tên "Nguyen Van A"

📦 2. search_products

Tìm kiếm sản phẩm theo tên hoặc mã hàng

Tìm sản phẩm "iPhone"

📊 3. get_sales_statistics

Lấy thống kê doanh số bán hàng theo ngày và cửa hàng

Xem thống kê doanh số hôm nay

6. 🤖 AI Integration

Server được tích hợp với vendor-agnostic AI architecture hỗ trợ nhiều AI providers:

Supported AI Providers:

• Google Gemini (gemini-2.0-flash)
• OpenAI GPT (gpt-4o-mini)
• Anthropic Claude (claude-3-haiku)
• AWS Bedrock (Multi-model support)

Tính năng AI:

• Smart Customer Search: Tìm kiếm khách hàng với AI analysis
• Intelligent Summarization: Tóm tắt hội thoại bằng AI
• AI Consultation: Tư vấn và phân tích khách hàng thông minh
• Context-Aware Responses: Phản hồi dựa trên lịch sử hội thoại

Test AI Integration:

npm run test:langchain
npm run test:ai
npm run test:bedrock

7. 💾 Memory Integration

Hệ thống đã tích hợp memory.service.js để lưu trữ và truy xuất lịch sử hội thoại:

Features:

• ✅ Conversation History: Lưu trữ lịch sử hội thoại theo session
• ✅ Context Preservation: Duy trì ngữ cảnh qua các cuộc hội thoại
• ✅ Memory Compression: Tự động nén lịch sử để tối ưu hiệu suất
• ✅ Redis Integration: Sử dụng Redis để lưu trữ nhanh

Memory Flow:

1. Retrieve History: getHistory(sessionId)
2. AI Processing: Sử dụng history trong AI response
3. Save Memory: saveMemory(sessionId, context, history)

8. ☁️ AWS Bedrock Integration

AWS Bedrock đã được tích hợp với enterprise-grade security:

Supported Models:

• Anthropic Claude (claude-3-haiku, claude-3-sonnet)
• Amazon Titan
• AI21 Labs Jurassic
• Cohere Command

Authentication Methods:

| Method | Configuration | Pros | Cons | |--------|---------------|------|------| | API Key | BEDROCK_API_KEY | ✅ Simple setup | ⚠️ Key management | | AWS Credentials | AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY | ✅ Full AWS integration | ⚠️ Complex setup |

Features:

• ✅ Multi-Region Support: Deploy across AWS regions
• ✅ Enterprise Security: AWS IAM integration
• ✅ Cost Optimization: Pay-per-use pricing
• ✅ Compliance Ready: SOC, HIPAA, GDPR

9. Kiểm tra hoạt động

🧪 Script kiểm tra tự động:

node test-claude-desktop-connection.js

🔧 Test thủ công với Stdio:

# Test SDK
node src/test/test-mcp-sdk.js

# Test từng bước
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node bin/mcp-sdk.js

# Test tools list
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node bin/mcp-sdk.js

# Test search
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_customers","arguments":{"query":"test"}}}' | node bin/mcp-sdk.js

🌐 Test HTTP server:

# Khởi động HTTP server
npm run http

# Test health check
curl http://localhost:3001/health

# Test MCP endpoint
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

🚀 Test HTTP Stream server:

# Khởi động HTTP Stream server
npm run http:stream

# Test health check
curl http://localhost:3001/health

# Test SSE endpoint
curl -N -H "Accept: text/event-stream" http://localhost:3001/mcp

🔄 Test tất cả services:

# Khởi động tất cả services cùng lúc
npm run start:all

# Test individual services
npm run test:http
npm run test:sdk
npm run test:ai
npm run test:bedrock
npm run test:langchain

10. Troubleshooting

❌ Lỗi Zod validation (đã sửa):

• Vấn đề: Claude Desktop hiển thị lỗi invalid_union, invalid_type, ZodError
• Nguyên nhân: Server cũ không tương thích với MCP SDK phiên bản cũ
• Giải pháp: Đã cập nhật sử dụng bin/mcp-sdk.js với MCP SDK chính thức

❌ Lỗi JSON format:

• Đảm bảo không có console.log nào trong code làm lẫn JSON response
• Kiểm tra log trong Claude Desktop để xem lỗi cụ thể

❌ Lỗi kết nối Elasticsearch/Redis:

• Kiểm tra các service đang chạy
• Xác minh thông tin đăng nhập trong .env
• Kiểm tra network connectivity

❌ Lỗi AI Provider:

• Xác minh API keys hợp lệ
• Kiểm tra quota và billing
• Thử đổi AI_PROVIDER sang provider khác

❌ Lỗi MCP Protocol:

• Đảm bảo sử dụng MCP SDK version mới nhất
• Kiểm tra log trong Claude Desktop
• Restart Claude Desktop sau khi thay đổi config

❌ Lỗi HTTP Stream:

• Kiểm tra port 3001 không bị chiếm dụng
• Xác minh SSE transport được hỗ trợ
• Test với curl để kiểm tra SSE endpoint

11. 🔒 Lưu ý bảo mật

• Không commit file .env vào git
• Sử dụng environment variables trong production
• Rotate API keys định kỳ
• Giới hạn quyền truy cập database
• Sử dụng HTTPS trong production
• Implement rate limiting cho API endpoints
• Monitor và log tất cả API calls

📚 Available Scripts

# Development
npm start              # Khởi động main server
npm run dev           # Development mode với nodemon
npm run grpc          # Khởi động gRPC server

# MCP Servers
npm run http          # HTTP MCP server
npm run http:stream   # HTTP Stream MCP server (SSE)
npm run start:all     # Khởi động tất cả services

# Testing
npm test              # Chạy tất cả tests
npm run test:http     # Test HTTP MCP
npm run test:sdk      # Test MCP SDK
npm run test:ai       # Test AI service
npm run test:bedrock  # Test AWS Bedrock
npm run test:langchain # Test LangChain integration

🎯 Quick Start

1. Clone và cài đặt:

   git clone <repository>
   cd mcp-customer-server
   npm install && npm link

2. Cấu hình environment:

   cp .env.example .env
   # Chỉnh sửa .env với thông tin của bạn

3. Test connection:

   node test-claude-desktop-connection.js

4. Cấu hình Claude Desktop:

   • Copy nội dung từ claude_desktop_config_example.json
   • Paste vào file cấu hình Claude Desktop
   • Restart Claude Desktop

5. Test trong Claude Desktop:

   Tìm kiếm khách hàng tên "Nguyen"

📞 Hỗ trợ

Nếu gặp vấn đề, vui lòng liên hệ:

• Email: [email protected]
• Phone: 84937766469
• GitHub Issues: Tạo issue trong repository

Phiên bản: 1.0.1
Cập nhật cuối: 2025-01-04
MCP Protocol: 2024-11-05