Spamassassin MCP

🚀 SpamAssassin MCP Server

SpamAssassinを統合した、安全なコンテナ化されたModel Context Protocol (MCP) サーバーで、防御的なメールセキュリティ分析を提供します。このサーバーは、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

✨ 主な機能

🛡️ セキュリティを重視した設計

防御的な操作のみ - このサーバーは専らセキュリティ分析機能を提供します:

• ✅ メールスパム検出と分析
• ✅ 送信者の評判チェック
• ✅ ルールのテストと検証
• ✅ 設定の検査
• ❌ メール送信/中継機能はありません
• ❌ 悪意のあるコンテンツ生成は行いません
• ❌ 攻撃的なセキュリティツールは使用しません

📦 インストール

環境変数

セキュリティ設定

このサーバーには包括的なセキュリティ対策が組み込まれています:

• レート制限: 1分間に60リクエスト、バースト10
• 入力検証: メール形式とサイズの検証
• コンテンツサニタイズ: メールコンテンツの安全な処理
• コンテナセキュリティ: 非ルート実行、読み取り専用ファイルシステム
• ネットワーク分離: カスタムブリッジネットワーク
• リソース制限: メモリとCPUの制約

💻 使用例

基本的なメールスキャン

# 簡単なスパムチェック
/scan_email --content "$(cat suspicious_email.eml)"

# Bayesを使用した詳細分析
/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!"

🏥 ヘルスモニタリング

ヘルスチェックエンドポイント

コンテナには自動ヘルスチェックが組み込まれています:

# コンテナのヘルスをチェック
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 を確認する

📚 ドキュメント

• APIリファレンス - 完全な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" をクリックします
   • 2つの新しいリポジトリシークレットを追加します:
     • 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

🔗 関連プロジェクト

• Model Context Protocol - 公式MCP仕様
• Claude Code - Claudeの公式CLI
• SpamAssassin - オープンソースのスパムフィルタリング

⚠️ 重要提示

このサーバーは防御的なセキュリティ分析のみを目的として設計されています。メールの送信、スパムコンテンツの生成、または攻撃的なセキュリティ操作の機能は提供しません。すべての操作はログに記録され、監査可能です。