# ms-agentframework
### Microsoft Agent Framework + MCP Protocol
> 🤖 **Production-ready AI Agent Server** | 生產級 AI 代理伺服器
[](https://www.python.org/downloads/)
[](LICENSE)
[](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>
