ms-agentframework

Microsoft Agent Framework + MCP Protocol

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

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

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

或分步驟執行 | Or step by step

# 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

# 測試所有工具 | 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

# 安裝開發依賴 | 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

# 建置映像 | 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
• MCP 協議 | MCP Protocol
• Codex CLI 整合 | Codex CLI Integration
• 部署指南 | Deployment Guide

🔌 Codex CLI 整合 | Codex CLI Integration

配置方式 | Configuration

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

路徑 | Path: ~/Library/Application Support/Claude/claude_desktop_config.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

# 測試連接 | 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

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

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

# 執行所有測試 | 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:

# 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 了解詳情。

Contributions are welcome! Please read CONTRIBUTING.md for details.

📄 授權 | License

MIT 授權 - 詳見 LICENSE 檔案。

MIT License - see LICENSE for details.

🙏 致謝 | Acknowledgments

• Microsoft Agent Framework - 微軟代理框架 | Microsoft's agent framework
• Model Context Protocol - MCP 協議規範 | MCP protocol specification
• FastAPI - 現代網頁框架 | Modern web framework
• Agent Lucy - 參考實作 | Reference implementation

📞 支援 | Support

• 問題回報 | Issues: GitHub Issues
• 討論區 | Discussions: GitHub 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