AI Assistant Server

MCP (Model Context Protocol) Server cho AI Assistant, được xây dựng với FastMCP và quản lý bằng uv.

🚀 Tính năng

• ✅ FastMCP: Framework hiện đại cho MCP server
• ✅ Tools: Các công cụ để tương tác với AI agent backend
• ✅ Weather Tool: Lấy thông tin thời tiết thời gian thực 🌤️
• ✅ Resources: Truy cập thông tin agent và conversations
• ✅ Prompts: Các prompt templates có sẵn
• ✅ Async Support: Hoàn toàn asynchronous
• ✅ Type Safe: Type hints đầy đủ

📋 Yêu cầu

• Python 3.10+
• uv (Python package manager)
• Backend API đang chạy (port 8000)

🛠️ Cài đặt với UV

1. Cài đặt UV (nếu chưa có)

# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

2. Tạo virtual environment và cài đặt dependencies

cd MCP
uv venv
.venv\Scripts\activate
uv pip install -e .

hoặc cài đặt trực tiếp:

uv pip install fastmcp python-dotenv pydantic httpx aiofiles

3. Cấu hình environment variables

copy .env.example .env

Cập nhật file .env:

BACKEND_API_URL=http://localhost:8000
OPENAI_API_KEY=your_key_here
WEATHER_API_KEY=your_openweathermap_key_here  # Optional - for weather tool

Note: Weather tool hoạt động ngay cả khi không có WEATHER_API_KEY. Nó sẽ tự động dùng wttr.in (miễn phí). API key chỉ cần thiết nếu muốn độ chính xác cao hơn.

🚀 Chạy MCP Server

Với UV (khuyên dùng)

uv run server.py

hoặc

.venv\Scripts\activate
python server.py

Development mode

uv run server.py --reload

📡 MCP Server Capabilities

Tools (Công cụ)

1. chat_with_agent

   • Gửi tin nhắn đến AI agent
   • Tham số: message, conversation_id (optional), user_id (optional)

2. get_conversation_history

   • Lấy lịch sử hội thoại
   • Tham số: conversation_id

3. get_agent_status

   • Lấy trạng thái hiện tại của agent
   • Không cần tham số

4. get_agent_graph

   • Lấy cấu trúc LangGraph workflow
   • Không cần tham số

5. delete_conversation

   • Xóa một hội thoại
   • Tham số: conversation_id

6. health_check

   • Kiểm tra sức khỏe backend API
   • Không cần tham số

7. get_current_weather 🌤️

   • Lấy thông tin thời tiết hiện tại cho một thành phố
   • Tham số: city (bắt buộc), country_code (optional), units (optional)
   • Ví dụ: get_current_weather("Hanoi", "VN", "metric")

8. get_weather_forecast 🌦️

   • Lấy dự báo thời tiết 1-5 ngày
   • Tham số: city (bắt buộc), country_code (optional), days (1-5), units (optional)
   • Ví dụ: get_weather_forecast("Ho Chi Minh", "VN", 3)

Resources (Tài nguyên)

1. agent://info

   • Thông tin chi tiết về agent

2. agent://status

   • Trạng thái hoạt động của agent

3. conversations://list

   • Danh sách các hội thoại (placeholder)

Prompts (Prompt Templates)

1. casual_chat - Trò chuyện thông thường
2. technical_help - Hỗ trợ kỹ thuật
3. creative_writing - Viết sáng tạo
4. code_review - Review code

💡 Ví dụ sử dụng

Từ MCP Client

# Sử dụng tool chat_with_agent
result = await client.call_tool(
    "chat_with_agent",
    arguments={
        "message": "What is LangGraph?",
        "user_id": "user_123"
    }
)

# Lấy thông tin thời tiết 🌤️
weather = await client.call_tool(
    "get_current_weather",
    arguments={
        "city": "Hanoi",
        "country_code": "VN",
        "units": "metric"
    }
)

# Lấy thông tin agent
info = await client.read_resource("agent://info")

# Sử dụng prompt
messages = await client.get_prompt("technical_help")

Demo Weather Tool

# Chạy demo thời tiết
python3 demo_weather.py

# Hoặc chế độ tương tác
python3 demo_weather.py interactive

# Test
python3 tests/test_weather_tools.py

Cấu hình trong Claude Desktop

Thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "ai-assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\UIT\\SE347\\Seminar\\MCP",
        "run",
        "server.py"
      ],
      "env": {
        "BACKEND_API_URL": "http://localhost:8000"
      }
    }
  }
}

Cấu hình trong Cline (VS Code)

Thêm vào settings:

{
  "mcp.servers": {
    "ai-assistant": {
      "command": "uv",
      "args": [
        "--directory",
        "F:\\UIT\\SE347\\Seminar\\MCP",
        "run",
        "server.py"
      ],
      "env": {
        "BACKEND_API_URL": "http://localhost:8000"
      }
    }
  }
}

🧪 Testing

Test với MCP Inspector

# Cài đặt MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Chạy inspector
mcp-inspector uv --directory F:\UIT\SE347\Seminar\MCP run server.py

Test với curl

# Test backend trước
curl http://localhost:8000/health

# Rồi mới chạy MCP server
uv run server.py

📁 Cấu trúc Project

MCP/
├── server.py                    # Main MCP server file
├── pyproject.toml               # Project configuration (uv/pip)
├── .env                         # Environment variables
├── .env.example                 # Example env file
├── README.md                    # Documentation (this file)
├── WEATHER_SETUP.md             # 🌤️ Weather tool detailed guide
├── QUICKSTART_VI.md             # 🌤️ Vietnamese quick start
├── INSTALL.md                   # Installation guide
├── WEATHER_SUMMARY.md           # 🌤️ Weather tool summary
├── demo_weather.py              # 🌤️ Weather demo script
├── src/
│   └── mcp_server/
│       ├── tools/
│       │   ├── chat_tools.py    # Chat tools
│       │   ├── agent_tools.py   # Agent tools
│       │   └── weather_tools.py # 🌤️ Weather tools
│       ├── resources/           # MCP resources
│       ├── prompts/             # Prompt templates
│       ├── core/                # Core configuration
│       └── utils/               # Utilities
├── tests/
│   ├── test_chat_tools.py
│   └── test_weather_tools.py    # 🌤️ Weather tests
└── .gitignore

🔧 Phát triển thêm

Thêm Tool mới

@mcp.tool()
async def your_new_tool(param: str) -> Dict[str, Any]:
    """
    Description of your tool.
    
    Args:
        param: Parameter description
        
    Returns:
        Result description
    """
    # Your implementation
    return {"result": "data"}

Thêm Resource mới

@mcp.resource("custom://resource")
async def your_resource() -> str:
    """
    Get custom resource data.
    """
    return "Resource content"

Thêm Prompt mới

@mcp.prompt()
async def your_prompt() -> List[Dict[str, str]]:
    """
    Custom prompt template.
    """
    return [
        {
            "role": "user",
            "content": "Your prompt content"
        }
    ]

📚 Tài liệu

General:

• FastMCP Documentation
• MCP Specification
• UV Documentation

Weather Tool Documentation:

• 🌤️ QUICKSTART_VI.md - Hướng dẫn nhanh tiếng Việt
• 🌤️ WEATHER_SETUP.md - Chi tiết đầy đủ (EN + VN)
• 🌤️ WEATHER_SUMMARY.md - Tóm tắt và architecture
• 🌤️ INSTALL.md - Hướng dẫn cài đặt chi tiết

Weather API:

• OpenWeatherMap API - Primary API (optional)
• wttr.in - Fallback API (no key needed)

🐛 Troubleshooting

Lỗi "Backend is not healthy"

• Đảm bảo Backend API đang chạy trên port 8000
• Check: curl http://localhost:8000/health

Lỗi import fastmcp

uv pip install fastmcp

Lỗi connection refused

• Kiểm tra BACKEND_API_URL trong .env
• Đảm bảo không có firewall block

UV command not found

# Reinstall UV
irm https://astral.sh/uv/install.ps1 | iex

📝 License

MIT License