Spamassassin MCP

SpamAssassin MCP服务器

一个安全的容器化模型上下文协议（MCP）服务器，集成了SpamAssassin用于防御性电子邮件安全分析。此服务器为Claude Code提供了全面的电子邮件分析功能，同时保持了严格的安全边界。

 ](https://golang.org/) ](https://www.docker.com/) 

🛡️ 安全第一设计

仅防御作战 -此服务器专门提供安全分析功能：

• ✅ 垃圾邮件检测和分析
• ✅ 发件人信誉检查
• ✅ 规则测试和验证
• ✅ 配置检查
• ❌ 没有电子邮件发送/中继功能
• ❌ 无恶意内容生成
• ❌ 没有攻击性安全工具

🚀 快速开始

先决条件

• Docker和Docker Compose
• 支持MCP的Claude代码

1.构建和启动

# Clone or create the project directory
cd spamassassin-mcp

# Optional: Copy and customize configuration
cp .env.example .env
# Edit .env to customize ports and settings

# Build and start the containers
docker compose up -d

# Check health
docker compose logs spamassassin-mcp

1.替代方案：使用预构建图像

# Pull the latest image from Docker Hub
docker pull your-dockerhub-username/spamassassin-mcp:latest

# Run the container
docker run -d \
  --name spamassassin-mcp \
  -p 8081:8080 \
  your-dockerhub-username/spamassassin-mcp:latest

2.连接克劳德代码

# Connect to containerized server (SSE transport)
# Server URL: http://localhost:8081/mcp

# Or for direct connection (stdio transport)
./mcp-server

3.测试集成

# Scan a sample email
/scan_email --content "Subject: Test Email

This is a test email for spam analysis."

# Check sender reputation
/check_reputation --sender "test@example.com"

# Get current configuration
/get_config

🔧 可用工具

电子邮件分析

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 server entry point
├── go.mod                  # Go module definition
├── Dockerfile              # Multi-stage container build
├── docker-compose.yml      # Service orchestration
├── internal/
│   ├── config/            # Configuration management
│   ├── handlers/          # MCP tool handlers
│   └── spamassassin/      # SpamAssassin client wrapper
├── configs/
│   └── config.yaml        # Server configuration
├── scripts/
│   ├── entrypoint.sh      # Container initialization
│   └── health-check.sh    # Health monitoring
└── README.md

⚙️ 配置

环境变量

安全设置

服务器包括全面的安全措施：

• 速率限制：60个请求/分钟，突发10个
• 输入验证：电子邮件格式和大小验证
• 内容消毒：安全处理电子邮件内容
• 集装箱安全：非根执行，只读文件系统
• 网络隔离：自定义网桥网络
• 资源限制：内存和CPU限制

🔍 使用示例

基本电子邮件扫描

# Simple spam check
/scan_email --content "$(cat suspicious_email.eml)"

# Detailed analysis with Bayes
/scan_email --content "$(cat email.eml)" --verbose --check_bayes

信誉分析

# Check sender reputation
/check_reputation --sender "unknown@suspicious-domain.com"

# Check domain and IP
/check_reputation --domain "suspicious-domain.com" --ip "192.168.1.100"

规则开发

# Test custom rules
/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."]'

乐谱分析

# Get detailed score explanation
/explain_score --email_content "Subject: Free Money!\n\nClaim your prize now!"

🏥 健康监测

健康检查端点

该容器包括自动健康检查：

# Check container health
docker-compose exec spamassassin-mcp /usr/local/bin/health-check.sh

# View health status
docker ps

日志和监控

# View server logs
docker compose logs -f spamassassin-mcp

# Monitor resource usage
docker stats spamassassin-mcp

# Test MCP connectivity (container mode)
curl -v http://localhost:8081/mcp

🔒 安全考虑

防御态势

• 服务器专门提供分析功能
• 没有电子邮件传输或中继功能
• 对所有端点进行输入验证和净化
• 限制利率以防止滥用
• 全面的审计跟踪日志记录

集装箱安全

• 以非root用户身份运行(spamassassin)
• 只读根文件系统
• 不允许新特权
• 实施资源限制
• 网络隔离

数据处理

• 没有持久存储电子邮件内容
• 仅作临时分析
• 可配置的保留策略
• GDPR/隐私合规设计

🚧 发展

从源头构建

# Install dependencies
go mod download

# Build binary
go build -o mcp-server main.go

# Run locally (requires SpamAssassin)
./mcp-server

测试

# Run with testing profile (includes spamd)
docker compose --profile testing up -d

# Test SpamAssassin connectivity
docker compose exec spamassassin-mcp timeout 2 bash -c 'echo >/dev/tcp/localhost/783'

# Test MCP server health
docker compose exec spamassassin-mcp /usr/local/bin/health-check.sh

🔧 故障排除

常见问题

容器重启循环

症状：容器不断重启，并显示“读取错误：EOF”

• 原因：stdio传输需要容器环境中的stdin输入
• 解决方案：服务器自动检测容器模式并使用SSE传输
• 验证：检查日志显示“使用SSE传输启动MCP服务器”

端口冲突

症状：“bind:地址已在使用中”

• 解决方案：修改 SA_MCP_HOST_PORT 在……里面 .env 文件
• 默认：服务器使用端口8081避免冲突

网络子网冲突

症状：“此地址空间上的池与其他池重叠”

• 解决方案：docker-compose.yml使用192.168.100.0/24网络
• 定制：如果冲突持续存在，请修改网络部分

健康检查失败

症状：容器标记为不健康

• 验证：运行 /usr/local/bin/health-check.sh 手动地
• 常见修复：确保SpamAssassin守护进程正在运行
• 调试：检查 docker compose logs spamassassin-mcp

📚 文档

• api参考 -完整的MCP工具文档
• 部署指导 -生产部署说明
• 安全指南 -安全架构和最佳实践
• 开发指南 -贡献和开发设置
• 配置参考 -完整的配置选项

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔄 带有GitHub操作的CI/CD

本项目使用GitHub Actions进行持续集成和部署：

1. Docker构建和推送：在推送时自动构建Docker镜像并将其推送到Docker Hub main 分支和标签
2. 测试Docker镜像：对Docker镜像运行测试，以确保其正确构建和运行
3. 更新Docker Hub概述：README.md更改时自动更新Docker Hub存储库描述

设置Docker Hub发布

要使用Docker Hub发布工作流，请执行以下操作：

1. 如果您还没有Docker Hub帐户，请创建一个

1. 生成Docker Hub访问令牌：

- 登录Docker Hub - 转到帐户设置>安全 - 点击“新建访问令牌” - 给它一个描述性的名称（例如，“GitHub Actions”） - 将权限设置为“读写” - 复制生成的令牌（您将不会再看到它）

1. 将Docker Hub凭据设置为GitHub Secrets：

- 转到您的GitHub存储库设置 - 点击“秘密和变量”>“操作” - 添加两个新的存储库机密： - DOCKER_USERNAME：您的Docker Hub用户名 - DOCKER_PASSWORD：您的Docker Hub访问令牌（您刚才创建的令牌）

1. 推到 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概述：

# Generate Docker Hub overview
./scripts/extract-dockerhub-info.sh

# Or use the manual update script with your credentials
./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的官方CLI
• SpamAssassin 的 -开源垃圾邮件过滤

______________________________________________________________________

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