エンリッチメントMCPサーバー

提供されたオブザーバブルに基づいてエンリッチメントを実行するためのモデルコンテキストプロトコル（MCP）サーバー。設定されたサービスと提供されたオブザーバブルの組み合わせによって、どのエンリッチメントサービスが使用されるかが決まります。

このツールは、一般的なサービス (VirusTotal、Hybrid Analysis など) を使用してサードパーティのエンリッチメントを実行するためのシンプルな実装を提供します。

このプロジェクトは、いかなる本番環境でも使用されていません。

特徴

enrichment-mcp MCP サーバーのこの実装では、次のツールが公開されます。

observable-lookup - 指定された observable を調べて適切なツールにルーティングする汎用エンドポイント。
lookup-ipaddress - 指定された IPv4 アドレスのエンリッチメントを実行します。
lookup-domain - 指定されたドメイン名のエンリッチメントを実行します。
lookup-url - 指定された URL (場合によってはドメイン名) のエンリッチメントを実行します。
lookup-email - 指定された電子メールアドレスのエンリッチメントを実行します。

決定された観測可能タイプで問題が発生した場合は、問題を作成してください。そうしないと、現在実装されている正規表現パターンを更新できます。

サポートされているサービス

現在、次のサービスと監視可能なタイプがサポートされています。

ご提案がある場合、または別のサービスを実装する必要があると思われる場合は、問題またはプルリクエストを作成してください。

名前	APIキーが必要です	IPをサポート	ドメインをサポート	URLをサポート	メールをサポート
ウイルストータル	はい	はい	はい	はい	いいえ
ハイブリッド分析	はい	はい	はい	はい	いいえ
エイリアンボールト	はい	はい	はい	はい	いいえ
初段	はい	はい	はい	はい	いいえ
Urlscan.io	はい	はい	はい	はい	いいえ
虐待IPDB	はい	はい	いいえ	いいえ	いいえ
いいね	はい	いいえ	いいえ	いいえ	はい

要件

この MCP サービスは、観測可能な検索に使用するサードパーティのエンリッチメントサービスを決定するために使用されるカスタム構成ファイルを実装します。

現時点ではこれは純粋に開発 / テスト用なので、これをローカル Mac / システムで実行する最も簡単な方法は次のとおりです。

uv run --env-file .env server.py

これには、提供されているテンプレート.env.exampleを使用して、シークレットを含む新しい.envファイルを作成する必要があります。

config.yaml

このプロジェクトはカスタム構成ファイルを提供しており、非常に簡単に理解できると思います。

まず、このサービスを使用する前に、提供されているconfig.yaml.example構成をコピーし、 .example拡張子を削除します。

この構成ファイルには、 serverとenrichmentsという 2 つの主要なデータセクションがあります。

デフォルトでは、サポートされているすべてのサービスは、現在実装されているエンリッチメントアクションタイプにマッピングされます。現在、真のエンリッチメントアクションタイプはlookupsのみですが、将来的には他のエンリッチメントアクションタイプも実装される可能性があります。

lookupsの下には、サポートされているさまざまなエンリッチメントタイプがあります。

そうは言っても、各個別のサービスにはapikeyという名前のキーとそのサービスの API キー値を設定できますが、これは設定しないことを検討してください。

このキーの値はconfig.yaml.exampleで直接設定できますが、 .envを使用することをお勧めします。

注: このサービスを実装する際は、シークレットを環境変数として設定することを強くお勧めします。シークレットを保存するのはやめてください。

このサービスがこれらの変数を検出するには、特定の形式でなければなりません。現在サポートされている変数のリストは以下のとおりです。

ENRICHMENT_MCP_VIRUSTOTAL_KEY
エンリッチメント_MCP_ハイブリッド分析_キー
エンリッチメント_MCP_エイリアンボールト_キー
エンリッチメント_MCP_SHODAN_KEY
ENRICHMENT_MCP_URLSCAN_KEY
ENRICHMENT_MCP_ABUSEIPDB_KEY
エンリッチメント_MCP_HIBP_キー

サーバー構成

これは主にサンドボックス化とテスト用であるため、ここでは最小限の設定しかありませんが、通常、このサービスを機能させるためにこれらの設定を変更する必要はありません。

server:
  host: 0.0.0.0 # the host address
  port: 8000 # the port
  debug: false # whether to enable debug logging
  log_level: INFO # the default logging level

エンリッチメント構成

設定ファイル内の各エンリッチメントは、 enrichmentsキーの下に記述されています。さらに、実行可能なエンリッチメントの種類を分類しました。つまり、現在の実装ではlookupsという単一のアクションタイプしかありませんが、将来的にはscansやqueriesなどにも拡張される可能性があります。

これらの高レベルアクションの下に、監視可能なタイプと、そのタイプをサポートするサービスのリストを示します。現在サポートされている監視可能なタイプは次のとおりです。

ipaddress - IPv4アドレス
ドメイン - ドメインまたはネットロック
url - スキーマなどを含む完全修飾 URL。
メール - 標準のメールアドレス

以下のタイプもサポートされていますが、現在は実装されていません。

md5 - ファイルのMD5ハッシュ
sha1 - ファイルのSHA1ハッシュ
sha256 - ファイルのSHA256ハッシュ

各サービスにはnameとtemplateが必要です。apikeyフィールドapikey指定することもできますが、環境変数を使用することをお勧めします。

プロンプトテンプレート

各サービスとオブザーバブルタイプは独自のテンプレートを持つことができます。これらのテンプレートはテンプレートディレクトリに保存され、すべてのテンプレートはここに存在するものと想定されます。

定義された各サービスには、jinja2テンプレートを使用したプロンプトテンプレートがあります。必要に応じて変更できますが、ファイル名の形式は変更しないでください。

これらのファイルのファイル名パターンは次のとおりです。

{service.name}.{enrichment.type}.jinja2

さらに、応答オブジェクトのテンプレート自体に正しいフィールドがあることを確認してください。そうしないと、エラーが発生します。

以下は、いくつかのエラーが混在するEnrich this IP 91.195.240.94プロンプトの出力例です。

{
    "virustotal": "error occurred looking up ip 91.195.240.94 in virustotal",
    "alienvault": "Service: alienvault\nIPAddress: \nReputation Score: 0\nTotal Votes: ",
    "shodan": "Service: shodan\nIPAddress: 91.195.240.94\nLast Analysis Results: 2025-04-25T21:02:52.644602\n\nTags\n\n\nAdditional information includes:\n\n* Latitude: 48.13743\n* Longitude: 11.57549\n* ASN: AS47846\n* Domains: ["servervps.net"]",
    "hybridanalysis": "error occurred looking up ip 91.195.240.94 in hybridanalysis",
    "urlscan": "Service: urlscan\nResult: https://urlscan.io/api/v1/result/01966efe-c8fa-74a4-bfc0-1ed479838e85/\n\nStats\n\n* uniqIPs - 6\n\n* uniqCountries - 2\n\n* dataLength - 432561\n\n* encodedDataLength - 218606\n\n* requests - 14\n\n\nPage\n* country - DE\n* server - Parking/1.0\n* ip - 91.195.240.94\n* mimeType - text/html\n* title - wearab.org\xa0-\xa0Informationen zum Thema wearab.\n* url - https://login.wearab.org/\n* tlsValidDays - 364\n* tlsAgeDays - 0\n* tlsValidFrom - 2025-04-25T00:00:00.000Z\n* domain - login.wearab.org\n* apexDomain - wearab.org\n* asnname - SEDO-AS SEDO GmbH, DE\n* asn - AS47846\n* tlsIssuer - Encryption Everywhere DV TLS CA - G2\n* status - 200\n",
    "abuseipdb": "Service: abuseripdb\nIPAddress: 91.195.240.94\nLast Analysis Result: 2025-03-30T14:04:45+00:00\nScore: 7\nUsage: Data Center/Web Hosting/Transit\nIs Tor: False\nIs Whitelisted: False\nISP: Sedo Domain Parking"
}

使用法

事前に構築されたサーバーの使用については、こちらの手順をご覧ください: https://modelcontextprotocol.io/quickstart/user

デスクトップ版Claudeをダウンロード
uvをインストールする

curl -LsSf https://astral.sh/uv/install.sh | sh

このリポジトリをダウンロードして、Claude for Desktop の設定に追加します。
- デスクトップ版Claude > 設定 > 開発者 > 設定の編集

これにより、次の場所に構成ファイルが作成されます。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

任意のテキストエディタで設定ファイルを開き、ファイルの内容を以下の内容に置き換えます。

{
	"mcpServers": {
		"enrichment-mcp": {
			"command": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/uv",
			"args": [
				"--directory",
				"/ABSOLUTE/PATH/TO/CLONED/REPOSITORY/enrichment-mcp",
				"run",
				"server.py"
			]
		}
    }
}

デスクトップ版Claudeの再起動

チャットバーに、使用可能なツールを示すハンマーと、定義されたプロンプトと必要な入力を示す接続アイコンの 2 つのアイコンが表示されます。

デザイン

このサーバーを構築しながら、Astral UVとMCPを学んでいました。確かにオーバーエンジニアリングしすぎた感はありましたが、楽しかったです。また、このコードの一部は将来的にも活用したいと思っていたので、その点も考慮して設計しました（これについては後ほど詳しく説明します）。

さらに、返されるプロンプト/結果をより適切に管理できるようになり、将来のユースケースにも対応できるため、特に Jinja2 テンプレートに移行しました。

フィードバック、改善点、機能のリクエストなどがありましたら、ぜひお寄せください。すべて喜んでお聞きします。

貢献

貢献を歓迎します！プルリクエストをお気軽に送信してください。

免責事項

このツールは教育および認可されたテスト目的のみに使用されます。

Enrichment MCP Server