Spamassassin MCP

🚀 SpamAssassin MCP 服務器

這是一個安全的、容器化的模型上下文協議（MCP）服務器，集成了 SpamAssassin 用於進行防禦性的電子郵件安全分析。該服務器為 Claude Code 提供全面的電子郵件分析能力，同時保持嚴格的安全邊界。

🚀 快速開始

前提條件

• Docker 和 Docker Compose
• 支持 MCP 的 Claude Code

1. 構建並啟動

# 克隆或創建項目目錄
cd spamassassin-mcp

# 可選：複製並自定義配置
cp .env.example .env
# 編輯 .env 以自定義端口和設置

# 構建並啟動容器
docker compose up -d

# 檢查健康狀態
docker compose logs spamassassin-mcp

1. 替代方案：使用預構建鏡像

# 從 Docker Hub 拉取最新鏡像
docker pull your-dockerhub-username/spamassassin-mcp:latest

# 運行容器
docker run -d \
  --name spamassassin-mcp \
  -p 8081:8080 \
  your-dockerhub-username/spamassassin-mcp:latest

2. 連接 Claude Code

# 連接到容器化服務器（SSE 傳輸）
# 服務器 URL: http://localhost:8081/mcp

# 或者直接連接（stdio 傳輸）
./mcp-server

3. 測試集成

# 掃描示例電子郵件
/scan_email --content "Subject: Test Email

This is a test email for spam analysis."

# 檢查發件人信譽
/check_reputation --sender "test@example.com"

# 獲取當前配置
/get_config

✨ 主要特性

• 安全優先設計：僅提供安全分析功能，不涉及郵件發送、中繼或惡意內容生成。
• 多種分析工具：支持郵件掃描、發件人信譽檢查、規則測試等功能。
• 詳細配置：通過環境變量和配置文件進行靈活配置。
• 健康監測：提供自動健康檢查和日誌監控功能。
• 安全考慮：具備輸入驗證、內容清理、速率限制等安全措施。
• 開發支持：支持從源代碼構建和測試。
• 文檔完善：提供 API 參考、部署指南、安全指南等詳細文檔。

📦 安裝指南

構建並啟動

# 克隆或創建項目目錄
cd spamassassin-mcp

# 可選：複製並自定義配置
cp .env.example .env
# 編輯 .env 以自定義端口和設置

# 構建並啟動容器
docker compose up -d

# 檢查健康狀態
docker compose logs spamassassin-mcp

替代方案：使用預構建鏡像

# 從 Docker Hub 拉取最新鏡像
docker pull your-dockerhub-username/spamassassin-mcp:latest

# 運行容器
docker run -d \
  --name spamassassin-mcp \
  -p 8081:8080 \
  your-dockerhub-username/spamassassin-mcp:latest

💻 使用示例

基礎用法

基本郵件掃描

# 簡單垃圾郵件檢查
/scan_email --content "$(cat suspicious_email.eml)"

# 結合貝葉斯的詳細分析
/scan_email --content "$(cat email.eml)" --verbose --check_bayes

信譽分析

# 檢查發件人信譽
/check_reputation --sender "unknown@suspicious-domain.com"

# 檢查域名和 IP
/check_reputation --domain "suspicious-domain.com" --ip "192.168.1.100"

高級用法

規則開發

# 測試自定義規則
/test_rules --rules "header LOCAL_TEST Subject =~ /test/i
describe LOCAL_TEST Test rule
score LOCAL_TEST 2.0" --test_emails '["Subject: test email\n\nThis is a test."]'

分數分析

# 獲取詳細分數解釋
/explain_score --email_content "Subject: Free Money!\n\nClaim your prize now!"

📚 詳細文檔

• API 參考 - 完整的 MCP 工具文檔
• 部署指南 - 生產部署說明
• 安全指南 - 安全架構和最佳實踐
• 開發指南 - 貢獻和開發設置
• 配置參考 - 完整的配置選項

🔧 技術細節

可用工具

郵件分析

scan_email

分析郵件內容的垃圾郵件概率和規則匹配情況。

參數：

• content（必需）：包括郵件頭的原始郵件內容
• headers（可選）：要分析的額外郵件頭
• check_bayes（可選）：包括貝葉斯分析
• verbose（可選）：返回詳細的規則解釋

示例：

{
  "content": "Subject: Urgent Action Required\\n\\nClick here to claim your prize!",
  "verbose": true,
  "check_bayes": true
}

check_reputation

檢查發件人信譽和域名/IP 黑名單。

參數：

• sender（必需）：發件人電子郵件地址
• domain（可選）：發件人域名
• ip（可選）：發件人 IP 地址

explain_score

詳細解釋垃圾郵件分數的計算方式。

配置管理

get_config

獲取當前 SpamAssassin 配置和狀態。

update_rules

更新 SpamAssassin 規則定義（僅防禦性更新）。

參數：

• source（可選）：規則源（官方/自定義）
• force（可選）：即使最近已更新也強制更新

規則測試

test_rules

在安全環境中針對示例郵件測試自定義規則。

參數：

• rules（必需）：自定義規則定義
• test_emails（必需）：要測試的示例郵件數組

項目結構

spamassassin-mcp/
├── main.go                 # MCP 服務器入口點
├── go.mod                  # Go 模塊定義
├── Dockerfile              # 多階段容器構建
├── docker-compose.yml      # 服務編排
├── internal/
│   ├── config/            # 配置管理
│   ├── handlers/          # MCP 工具處理程序
│   └── spamassassin/      # SpamAssassin 客戶端包裝器
├── configs/
│   └── config.yaml        # 服務器配置
├── scripts/
│   ├── entrypoint.sh      # 容器初始化
│   └── health-check.sh    # 健康監測
└── README.md

配置

環境變量

屬性	詳情
SA_MCP_HOST_PORT	容器部署的主機端口，默認值為 8081
SA_MCP_LOG_LEVEL	日誌級別（debug, info, warn, error），默認值為 info
SA_MCP_SERVER_BIND_ADDR	服務器綁定地址（容器內部），默認值為 0.0.0.0:8080
SA_MCP_SPAMASSASSIN_HOST	SpamAssassin 守護進程主機，默認值為 localhost
SA_MCP_SPAMASSASSIN_PORT	SpamAssassin 守護進程端口，默認值為 783
SA_MCP_SPAMASSASSIN_THRESHOLD	垃圾郵件分數閾值，默認值為 5.0
SA_MCP_SECURITY_MAX_EMAIL_SIZE	最大郵件大小（10MB），默認值為 10485760
UPDATE_RULES	是否在啟動時更新 SpamAssassin 規則，默認值為 false
MCP_TRANSPORT	傳輸模式（auto, stdio, sse），默認值為 auto

安全設置

• 速率限制：每分鐘 60 個請求，突發請求為 10 個
• 輸入驗證：驗證郵件格式和大小
• 內容清理：安全處理郵件內容
• 容器安全：以非根用戶執行，使用只讀文件系統
• 網絡隔離：使用自定義橋接網絡
• 資源限制：設置內存和 CPU 約束

健康監測

健康檢查端點

容器包含自動健康檢查：

# 檢查容器健康狀態
docker-compose exec spamassassin-mcp /usr/local/bin/health-check.sh

# 查看健康狀態
docker ps

日誌和監測

# 查看服務器日誌
docker compose logs -f spamassassin-mcp

# 監測資源使用情況
docker stats spamassassin-mcp

# 測試 MCP 連接性（容器模式）
curl -v http://localhost:8081/mcp

安全考慮

防禦姿態

• 服務器僅提供分析功能
• 無郵件傳輸或中繼功能
• 所有端點進行輸入驗證和清理
• 速率限制以防止濫用
• 全面日誌記錄用於審計跟蹤

容器安全

• 以非根用戶（spamassassin）運行
• 只讀根文件系統
• 不允許新權限
• 實施資源限制
• 網絡隔離

數據處理

• 不持久存儲郵件內容
• 僅進行臨時分析
• 可配置保留策略
• 符合 GDPR/隱私設計

開發

從源代碼構建

# 安裝依賴
go mod download

# 構建二進制文件
go build -o mcp-server main.go

# 本地運行（需要 SpamAssassin）
./mcp-server

測試

# 使用測試配置文件運行（包括 spamd）
docker compose --profile testing up -d

# 測試 SpamAssassin 連接性
docker compose exec spamassassin-mcp timeout 2 bash -c 'echo >/dev/tcp/localhost/783'

# 測試 MCP 服務器健康狀態
docker compose exec spamassassin-mcp /usr/local/bin/health-check.sh

故障排除

常見問題

容器重啟循環

症狀：容器持續重啟，顯示 "read error: EOF"

• 原因：stdio 傳輸期望在容器環境中輸入 stdin
• 解決方案：服務器自動檢測容器模式並使用 SSE 傳輸
• 驗證：檢查日誌顯示 "Starting MCP server with SSE transport"

端口衝突

症狀：顯示 "bind: address already in use"

• 解決方案：修改 .env 文件中的 SA_MCP_HOST_PORT
• 默認值：服務器使用端口 8081 以避免衝突

網絡子網衝突

症狀：顯示 "Pool overlaps with other one on this address space"

• 解決方案：docker-compose.yml 使用 192.168.100.0/24 網絡
• 自定義：如果衝突仍然存在，修改網絡部分

健康檢查失敗

症狀：容器標記為不健康

• 驗證：手動運行 /usr/local/bin/health-check.sh
• 常見修復：確保 SpamAssassin 守護進程正在運行
• 調試：檢查 docker compose logs spamassassin-mcp

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🔄 使用 GitHub Actions 進行 CI/CD

本項目使用 GitHub Actions 進行持續集成和部署：

1. Docker 構建和推送：在推送到 main 分支和打標籤時，自動構建 Docker 鏡像並推送到 Docker Hub。
2. 測試 Docker 鏡像：在 Docker 鏡像上運行測試，確保其正確構建和運行。
3. 更新 Docker Hub 概述：當 README.md 更改時，自動更新 Docker Hub 倉庫描述。

設置 Docker Hub 發佈

要使用 Docker Hub 發佈工作流：

1. 如果還沒有 Docker Hub 賬戶，請創建一個。
2. 生成 Docker Hub 訪問令牌：
   • 登錄 Docker Hub。
   • 轉到賬戶設置 > 安全。
   • 點擊 "New Access Token"。
   • 給它一個描述性名稱（例如，"GitHub Actions"）。
   • 將權限設置為 "Read & Write"。
   • 複製生成的令牌（之後將無法再次查看）。
3. 將 Docker Hub 憑證設置為 GitHub 機密：
   • 轉到 GitHub 倉庫設置。
   • 點擊 "Secrets and variables" > "Actions"。
   • 添加兩個新的倉庫機密：
     • DOCKER_USERNAME：你的 Docker Hub 用戶名。
     • DOCKER_PASSWORD：你的 Docker Hub 訪問令牌（剛剛創建的令牌）。
4. 推送到 main 分支或創建以 v 開頭的標籤（例如，v1.0.0）：
   • 工作流將自動構建並將鏡像推送到 Docker Hub。

發佈的鏡像將在 https://hub.docker.com/r/YOUR_USERNAME/spamassassin-mcp 上可用，其中 YOUR_USERNAME 是你的 Docker Hub 用戶名。

鏡像標籤：

• latest - 主分支的最新構建
• vX.Y.Z - 特定版本的發佈標籤
• commit-SHA - 特定提交的構建

手動更新 Docker Hub 概述

你也可以手動生成 Docker Hub 概述：

# 生成 Docker Hub 概述
./scripts/extract-dockerhub-info.sh

# 或者使用手動更新腳本和你的憑證
./scripts/update-dockerhub-manual.sh your-docker-username your-docker-access-token

🤝 貢獻

歡迎貢獻！請閱讀我們的 貢獻指南，並確保所有更改都遵循安全優先、僅防禦性的設計原則。

📞 支持

如有問題和疑問：

1. 第一步：查看 故障排除指南
2. 查看日誌：docker-compose logs spamassassin-mcp
3. 健康檢查：docker-compose exec spamassassin-mcp /usr/local/bin/health-check.sh
4. 檢查 SpamAssassin 狀態：docker-compose exec spamassassin-mcp pgrep spamd

🔗 相關項目

• 模型上下文協議 - 官方 MCP 規範
• Claude Code - Claude 的官方 CLI
• SpamAssassin - 開源垃圾郵件過濾

⚠️ 重要提示

本服務器專為防禦性安全分析而設計。它不提供發送電子郵件、生成垃圾郵件內容或任何攻擊性安全操作的功能。所有操作都會被記錄並可審計。