MCP AI Summary Demo
專案概述
這是一個 Model Context Protocol (MCP) 學習範例專案，展示如何建立一個 MCP Server 來：
- 📊 從資料庫或 API 取得 JSON 資料
- 📝 使用結構化 Prompt 模板，將資料帶入佔位符
- 🤖 透過本地 Ollama Gemma 3 4B 生成 AI 摘要
- 🔒 內建資料遮罩功能，保護敏感個資
🎯 什麼是 MCP？
Model Context Protocol (MCP) 是一個開放標準，用於連接 AI 應用程式與外部系統。
想像 MCP 就像是 AI 世界的 USB-C 接口：
┌─────────────────┐ MCP 協議 ┌─────────────────┐
│ AI 客戶端 │◄─────────────►│ MCP Server │
│ (Claude 等) │ │ (你的程式碼) │
└─────────────────┘ └─────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 資料庫 │ │ API │ │ 檔案系統 │
└──────────┘ └──────────┘ └──────────┘MCP 的三大核心概念
| 概念 | 說明 | 範例 |
|---|---|---|
| Resources | 提供可讀取的資料 | 資料庫記錄、設定檔 |
| Tools | 提供可執行的功能 | 查詢資料、生成報告 |
| Prompts | 預定義的 Prompt 模板 | 摘要模板、分析模板 |
📁 專案結構
MCP_AI_Summary_demo/
├── pyproject.toml # Python 專案設定
├── .env.example # 環境變數範例
├── .gitignore # Git 忽略規則
├── README.md # 本說明文件
├── test_local.py # 本地測試腳本
│
├── src/
│ ├── __init__.py # 模組初始化
│ ├── server.py # 🚀 MCP Server 主程式
│ ├── config.py # ⚙️ 設定管理
│ ├── data_source.py # 📊 資料來源（DB/API）
│ ├── prompts.py # 📝 Prompt 模板系統
│ ├── ollama_client.py # 🤖 Ollama 整合
│ └── security.py # 🔒 資料遮罩
│
└── data/
└── demo.db # SQLite 資料庫（自動建立）🚀 快速開始
1. 環境準備
# 安裝 uv（Python 套件管理器）
irm https://astral.sh/uv/install.ps1 | iex
# 進入專案目錄
cd MCP_AI_Summary_demo
# 建立虛擬環境並安裝相依套件
uv venv
.\.venv\Scripts\Activate.ps1
uv sync2. 設定環境變數
# 複製環境變數範例
Copy-Item .env.example .env
# 編輯 .env 檔案（可選）3. 安裝並啟動 Ollama
# 下載並安裝 Ollama: https://ollama.com/download
# 拉取 Gemma 3 4B 模型
ollama pull gemma3:4b
# 啟動 Ollama 服務（通常會自動啟動）
ollama serve4. 測試功能
# 執行本地測試腳本
uv run python test_local.py🔧 設定 MCP Client
VS Code 設定
在 VS Code 使用者設定或 .vscode/mcp.json 中加入：
{
"mcp": {
"servers": {
"ai-summary": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\gn012\\OneDrive\\Desktop\\MCP_AI_Summary_demo",
"run",
"python",
"-m",
"src.server"
]
}
}
}
}Claude Desktop 設定
編輯 %APPDATA%\Claude\claude_desktop_config.json：
{
"mcpServers": {
"ai-summary": {
"command": "uv",
"args": [
"--directory",
"C:\\Users\\gn012\\OneDrive\\Desktop\\MCP_AI_Summary_demo",
"run",
"python",
"-m",
"src.server"
]
}
}
}📝 使用方式
可用的 Tools
| 工具名稱 | 功能 | 參數 |
|---|---|---|
query_employees | 查詢員工資料 | department, limit |
query_projects | 查詢專案資料 | status, limit |
fetch_api_data | 從 API 取得資料 | endpoint, limit |
generate_summary | 生成 AI 摘要 | template_name, data, extra_vars |
answer_question | 基於資料回答問題 | question, data_source_type, filters |
check_ollama_status | 檢查 Ollama 狀態 | 無 |
list_prompt_templates | 列出可用模板 | 無 |
可用的 Prompt 模板
| 模板名稱 | 用途 | 變數 |
|---|---|---|
data_summary | 通用資料摘要 | data |
employee_analysis | 員工資料分析 | department, employees |
project_status | 專案狀態報告 | projects, current_date |
api_data_summary | API 資料摘要 | source, data_type, data, focus_areas |
qa_with_context | 基於資料問答 | context_data, question |
custom_summary | 自訂摘要 | custom_instructions, data |
範例對話
在 AI 客戶端中，你可以這樣使用：
使用者：查詢研發部的員工資料
AI：（呼叫 query_employees tool）
找到 2 位研發部員工...
使用者：幫我分析這些員工資料
AI：（呼叫 generate_summary tool，使用 employee_analysis 模板）
根據資料分析...🔒 企業安全考量
資料遮罩功能
本專案內建資料遮罩機制，自動保護敏感欄位：
# 原始資料
{"email": "test@example.com", "phone": "0912-345-678"}
# 遮罩後
{"email": "t**t@example.com", "phone": "09******78"}預設遮罩欄位
email- 電子郵件phone- 電話號碼ssn- 社會安全號碼credit_card- 信用卡號password- 密碼
設定自訂遮罩
在 .env 中設定：
ENABLE_DATA_MASKING=true
MASKED_FIELDS=email,phone,ssn,credit_card,password,身分證字號本地部署優勢
使用 Ollama 在本地執行 LLM，資料不會傳送到外部：
┌──────────────────────────────────────────────────────────────┐
│ 企業內部網路 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ MCP Client │────▶│ MCP Server │────▶│ Ollama │ │
│ │ (AI 助理) │ │ (本專案) │ │ (本地 LLM) │ │
│ └─────────────┘ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ 企業資料庫 │ │
│ └─────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
❌ 資料不外流📚 MCP 架構詳解
通訊流程
1. Client 啟動 MCP Server（透過 stdio）
2. Client 發送初始化請求
3. Server 回應支援的功能（tools, resources, prompts）
4. Client 可以：
- 讀取 Resources 取得資料
- 呼叫 Tools 執行功能
- 使用 Prompts 取得預定義模板
5. Server 處理請求並回傳結果本專案的資料流
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client │ │ MCP Server │ │ Data Source │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
│ query_employees │ │
│─────────────────▶│ │
│ │ SQL Query │
│ │──────────────────▶│
│ │ │
│ │ Raw Data │
│ │◀──────────────────│
│ │ │
│ │ ┌───────────────┐ │
│ │ │ Data Masking │ │
│ │ └───────────────┘ │
│ │ │
│ Masked Data │ │
│◀─────────────────│ │
│ │ │
│ generate_summary│ │
│─────────────────▶│ │
│ │ ┌───────────────┐ │
│ │ │ Prompt Render │ │
│ │ └───────────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────────┐ │
│ │ │ Ollama │ │
│ │ └───────────────┘ │
│ │ │
│ AI Summary │ │
│◀─────────────────│ │🔧 進階設定
使用其他 LLM 模型
修改 .env：
# 使用其他 Ollama 模型
OLLAMA_MODEL=llama3:8b
# 或連接遠端 Ollama
OLLAMA_BASE_URL=http://192.168.1.100:11434連接企業內部 API
# 替換為企業內部 API
API_BASE_URL=https://api.yourcompany.internal使用其他資料庫
目前使用 SQLite，可擴展為：
# 在 data_source.py 中添加其他資料庫連接
# 例如 PostgreSQL、MySQL 等❓ 常見問題
Q: Ollama 無法連接？
# 確認 Ollama 是否執行中
ollama list
# 如果沒有，啟動服務
ollama serveQ: 模型不存在？
# 拉取模型
ollama pull gemma3:4bQ: 資料庫找不到？
資料庫會在首次執行時自動建立於 data/demo.db。
Q: 如何新增自訂 Prompt 模板？
在 src/prompts.py 的 _register_default_templates 方法中添加：
self.register(PromptTemplate(
name="my_template",
description="我的自訂模板",
template="""{{instruction}}
資料：{{data}}
請處理以上資料。"""
))📖 學習資源
📄 授權
MIT License - 歡迎自由使用與修改