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 - 开源垃圾邮件过滤

⚠️ 重要提示

本服务器专为防御性安全分析而设计。它不提供发送电子邮件、生成垃圾邮件内容或任何攻击性安全操作的功能。所有操作都会被记录并可审计。