# ms-agentframework
### Microsoft Agent Framework + MCP Protocol

> 🤖 **Production-ready AI Agent Server** | 生產級 AI 代理伺服器

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Microsoft Agent Framework](https://img.shields.io/badge/Azure-Agent_Framework-0078D4)](https://github.com/microsoft/agents)

**ms-agentframework** 是 Microsoft Agent Framework 與 Model Context Protocol (MCP) 的生產級整合，提供 SSE/HTTP 串流傳輸。

**ms-agentframework** is a production-ready integration of Microsoft Agent Framework with Model Context Protocol (MCP), providing SSE/HTTP streamable transport.

## 🎬 示範影片 | Demo Video

<video width="100%" controls>
  <source src="https://github.com/jimmyliao/ms-agentframework/raw/main/docs/assets/agent-lucy.mp4" type="video/mp4">
  您的瀏覽器不支援影片播放。請<a href="https://github.com/jimmyliao/ms-agentframework/raw/main/docs/assets/agent-lucy.mp4">下載影片</a>觀看。
  Your browser does not support the video tag. Please <a href="https://github.com/jimmyliao/ms-agentframework/raw/main/docs/assets/agent-lucy.mp4">download the video</a>.
</video>

**示範內容** | **What the demo shows**:
- ✅ 工具自動載入與註冊 | Automatic tool loading and registration
- ✅ 即時查詢處理 | Real-time query processing
- ✅ 多工具協同使用 | Multi-tool collaboration
- ✅ 結果即時顯示 | Real-time result display

<details>
<summary>📸 示範截圖 | Demo Screenshots (點擊展開 | Click to expand)</summary>

示範影片展示了：
- ✅ 工具自動載入與註冊 | Automatic tool loading and registration
- ✅ 即時查詢處理 | Real-time query processing
- ✅ 多工具協同使用 | Multi-tool collaboration
- ✅ 結果即時顯示 | Real-time result display

The demo showcases:
- ✅ Automatic tool loading and registration
- ✅ Real-time query processing
- ✅ Multi-tool collaboration
- ✅ Real-time result display

</details>

## ✨ 特色 | Features

- ✅ **Microsoft Agent Framework** - 官方 Azure OpenAI 代理框架 | Official Azure OpenAI agent framework
- ✅ **MCP 協議** - AI 代理工具的標準協議 | Standard protocol for AI agent tools
- ✅ **SSE 傳輸** - Server-Sent Events 即時串流 | Server-Sent Events for real-time streaming
- ✅ **Python uv** - 現代化 Python 套件管理 | Modern Python package management
- ✅ **FastAPI** - 高效能異步網頁框架 | High-performance async web framework
- ✅ **生產就緒** - 包含 Docker、測試、監控 | Production ready with Docker, testing, monitoring

## 🚀 快速開始 | Quick Start

### 一行命令啟動 | One-Line Startup

```bash
# 完整設置並啟動 | Complete setup and start (推薦 | Recommended)
make quickstart
```

### 或分步驟執行 | Or step by step

```bash
# 1. 複製專案 | Clone repository
git clone https://github.com/jimmyliao/ms-agentframework.git
cd ms-agentframework

# 2. 一鍵設置安裝 | One-command setup
make quickstart

# 或手動分步 | Or manual steps:
# make setup    # 設置環境 | Setup environment
# make install  # 安裝依賴 | Install dependencies
# make run      # 啟動伺服器 | Start server
```

### 快速測試工具 | Quick Tool Testing

```bash
# 測試所有工具 | Test all tools
make demo-tools

# 或單獨測試 | Or test individually:
make demo-weather    # 天氣工具 | Weather tool
make demo-calc       # 計算器 | Calculator
make demo-stock      # 股票查詢 | Stock price
```

### 伺服器端點 | Server Endpoints

- SSE 端點 | SSE Endpoint: `http://localhost:8000/sse`
- 訊息端點 | Messages Endpoint: `http://localhost:8000/messages`
- 健康檢查 | Health Check: `http://localhost:8000/health`
- API 文件 | API Docs: `http://localhost:8000/docs`

## 📐 架構 | Architecture

MCP-MAF 實作三層架構 | MCP-MAF implements a three-layer architecture:

1. **獨立代理 | Standalone Agent** - 直接使用代理進行測試 | Direct agent usage for testing
2. **遠端 MCP (SSE) | Remote MCP (SSE)** - 生產伺服器模式 ⭐ | Production server mode ⭐
3. **STDIO MCP** - CLI 整合模式（可選）| CLI integration mode (optional)

```
┌──────────────────────────────────┐
│  Codex CLI / Gemini CLI          │
│  (MCP 客戶端 | MCP Client)       │
└────────────┬─────────────────────┘
             │ HTTP/SSE
             ↓
┌──────────────────────────────────┐
│  MCP-MAF Server (FastAPI)        │
│  - SSE Transport                 │
│  - JSON-RPC 2.0 Protocol         │
└────────────┬─────────────────────┘
             │
             ↓
┌──────────────────────────────────┐
│  Microsoft Agent Framework       │
│  - Azure OpenAI GPT-4.1          │
│  - Tool Management               │
└────────────┬─────────────────────┘
             │
             ↓
┌──────────────────────────────────┐
│  MCP 工具 | MCP Tools            │
│  - Weather Tool                  │
│  - Calculator Tool               │
│  - Stock Price Tool              │
└──────────────────────────────────┘
```

## 🛠️ 開發 | Development

```bash
# 安裝開發依賴 | Install dev dependencies
make install-dev

# 執行測試 | Run tests
make test

# 執行測試（含覆蓋率）| Run with coverage
make test-cov

# Lint 程式碼 | Lint code
make lint

# 格式化程式碼 | Format code
make format

# 開發伺服器（熱重載）| Development server (hot reload)
make dev
```

## 🐳 Docker

```bash
# 建置映像 | Build image
make docker-build

# 執行容器 | Run container
make docker-run

# 或使用 Docker Compose | Or use Docker Compose
make docker-up
make docker-down
```

## 📚 文件 | Documentation

- [架構概覽 | Architecture Overview](docs/ARCHITECTURE.md)
- [MCP 協議 | MCP Protocol](docs/MCP_PROTOCOL.md)
- [Codex CLI 整合 | Codex CLI Integration](docs/CODEX_INTEGRATION.md)
- [部署指南 | Deployment Guide](docs/DEPLOYMENT.md)

## 🔌 Codex CLI 整合 | Codex CLI Integration

### 配置方式 | Configuration

編輯 Claude Desktop 配置檔 | Edit Claude Desktop config:

**路徑 | Path**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-maf": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/jimmyliao/workspace/mcp-maf",
        "run",
        "uvicorn",
        "mcp_maf.server:app",
        "--host",
        "0.0.0.0",
        "--port",
        "8000"
      ]
    }
  }
}
```

### 使用方式 | Usage

```bash
# 測試連接 | Test connection
# 重啟 Claude Desktop 後工具將自動可用
# Tools will be available automatically after restarting Claude Desktop

# 使用範例 | Usage examples
# 在 Claude Desktop 中：| In Claude Desktop:
# "查詢台北天氣" | "What's the weather in Taipei?"
# "計算 123 * 456" | "Calculate 123 * 456"
# "查詢台積電股價（2330）" | "What's TSMC (2330) stock price?"
```

## 📖 使用範例 | Usage Examples

### 獨立代理 | Standalone Agent

```python
from mcp_maf import MCPMAFAgent

agent = MCPMAFAgent(
    azure_endpoint="your-endpoint",
    api_key="your-key",
    deployment_name="gpt-4.1"
)
await agent.initialize()

# 繁中範例 | Chinese example
response = await agent.run("台北的天氣如何？")
print(response)

# 英文範例 | English example
response = await agent.run("What's the weather in Taipei?")
print(response)
```

### SSE 客戶端 | SSE Client

```python
import httpx
import json

async with httpx.AsyncClient() as client:
    async with client.stream('GET', 'http://localhost:8000/sse') as response:
        async for line in response.aiter_lines():
            if line.startswith('data:'):
                data = json.loads(line[5:])  # 移除 'data:' 前綴 | Remove 'data:' prefix
                print(data)
```

## 🧪 測試 | Testing

```bash
# 執行所有測試 | Run all tests
make test

# 含覆蓋率報告 | With coverage report
make test-cov

# 執行特定測試檔案 | Run specific test file
uv run pytest tests/unit/test_protocol.py -v

# 監視模式 | Watch mode
make test-watch
```

## 📋 可用工具 | Available Tools

### 🌤️ 天氣工具 | Weather Tool

取得任何地點的即時天氣資訊。| Get current weather information for any location.

**用法 | Usage**: `get_weather(location: str)`

**範例 | Examples**:
- 繁中: `"台北的天氣如何？"`
- English: `"What's the weather in Taipei?"`

### 🧮 計算機工具 | Calculator Tool

執行數學運算。| Perform mathematical calculations.

**用法 | Usage**: `calculate(expression: str)`

**範例 | Examples**:
- 繁中: `"計算 123 乘以 456"`
- English: `"Calculate 123 * 456"`

### 📊 股票價格工具 | Stock Price Tool

查詢台灣證券交易所股票價格。| Query Taiwan stock prices from TWSE.

**用法 | Usage**: `get_stock_price(stock_code: str)`

**範例 | Examples**:
- 繁中: `"台積電（2330）的股價是多少？"`
- English: `"What's TSMC (2330) stock price?"`

**支援的股票 | Supported Stocks**:
- 2330 - 台積電 | TSMC
- 2454 - 聯發科 | MediaTek
- 2317 - 鴻海 | Hon Hai (Foxconn)
- 更多... | And more...

## 🔧 配置 | Configuration

環境變數在 `.env` 中配置 | Environment variables are configured in `.env`:

```bash
# Azure OpenAI（已配置）| Azure OpenAI (already configured)
AZURE_OPENAI_ENDPOINT=https://msfoundry-jimmyliao.openai.azure.com/
AZURE_OPENAI_API_KEY=***
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4.1

# 伺服器 | Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
LOG_LEVEL=INFO
```

## 📊 技術棧 | Tech Stack

### 核心技術 | Core Technologies
- **Python 3.11+** - 現代 Python | Modern Python
- **uv** - 快速套件管理器 | Fast package manager
- **FastAPI** - 異步網頁框架 | Async web framework
- **Uvicorn** - ASGI 伺服器 | ASGI server

### AI 與雲端 | AI & Cloud
- **Microsoft Agent Framework** - Azure AI 代理 | Azure AI agents
- **Azure OpenAI** - GPT-4.1 部署 | GPT-4.1 deployment
- **OpenAI SDK** - 後備 SDK | Fallback SDK

### 協議與傳輸 | Protocol & Transport
- **MCP (Model Context Protocol)** - 2024-11-05 規範 | 2024-11-05 spec
- **JSON-RPC 2.0** - 遠端程序調用 | Remote procedure calls
- **SSE (Server-Sent Events)** - 即時串流 | Real-time streaming

## 🤝 貢獻 | Contributing

歡迎貢獻！請閱讀 [CONTRIBUTING.md](CONTRIBUTING.md) 了解詳情。

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📄 授權 | License

MIT 授權 - 詳見 [LICENSE](LICENSE) 檔案。

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 致謝 | Acknowledgments

- [Microsoft Agent Framework](https://github.com/microsoft/agents) - 微軟代理框架 | Microsoft's agent framework
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP 協議規範 | MCP protocol specification
- [FastAPI](https://fastapi.tiangolo.com/) - 現代網頁框架 | Modern web framework
- [Agent Lucy](https://github.com/jimmyliao/agent-lucy) - 參考實作 | Reference implementation

## 📞 支援 | Support

- 問題回報 | Issues: [GitHub Issues](https://github.com/jimmyliao/ms-agentframework/issues)
- 討論區 | Discussions: [GitHub Discussions](https://github.com/jimmyliao/ms-agentframework/discussions)

## 📈 專案狀態 | Project Status

✅ 已完成 | Completed:
- [x] 基礎架構 | Core architecture
- [x] MCP 協議實作 | MCP protocol implementation
- [x] SSE 傳輸層 | SSE transport layer
- [x] 三個範例工具 | Three example tools
- [x] Docker 支援 | Docker support
- [x] 完整測試 | Complete testing
- [x] 文件撰寫 | Documentation

🚧 計劃中 | Planned:
- [ ] STDIO 傳輸 | STDIO transport
- [ ] 更多工具 | More tools
- [ ] CI/CD 管道 | CI/CD pipeline
- [ ] 效能優化 | Performance optimization

---

**版本 | Version**: 1.0.0
**作者 | Author**: Jimmy Liao
**用 ❤️ 打造 | Built with** ❤️ **使用 | using Microsoft Agent Framework and MCP Protocol**

**Co-Authored-By**: Agent-Lucy <hi@leapdesign.ai>