# asm-mcp-server

[`asm-agent`](https://github.com/kalala252/asm-agent)をMCPクライアントから利用するためのローカルサーバーです。接続したLLMは、公開情報の収集、保存済み結果の参照、根拠の確認をMCPツールとして実行できます。

このサーバー自体はLLM APIを呼びません。会話と要約には、MCPクライアント側のモデルを使用します。

## 必要なもの

- Python 3.12以上
- [uv](https://docs.astral.sh/uv/)
- 別途セットアップした`asm-agent`
- MCPに対応したLLMクライアント

## セットアップ

`asm-agent`と`asm-mcp-server`を同じ親フォルダへ取得します。

```bash
git clone https://github.com/kalala252/asm-agent.git
git clone https://github.com/kalala252/asm-mcp-server.git
```

それぞれの依存関係を準備します。

```bash
cd asm-agent
uv sync

cd ../asm-mcp-server
uv sync
```

Shodanを使う場合は、`asm-agent`側でAPIキーを保存します。

```bash
cd ../asm-agent
uv run asm-agent credentials set-shodan
```

## MCPクライアントへ登録する

この例は、`mcpServers`形式の設定に対応したMCPクライアント向けです。設定ファイルの場所や登録方法は、使用するクライアントの説明も確認してください。

macOSまたはLinuxでは、最初に`uv`の絶対パスを確認します。

```bash
command -v uv
```

表示されたパスを`command`へ指定してください。それ以外のパスもすべて絶対パスで記述します。

```json
{
  "mcpServers": {
    "passive-attack-surface": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/asm-mcp-server",
        "run",
        "asm-mcp-server"
      ],
      "env": {
        "ASM_AGENT_EXECUTABLE": "/absolute/path/to/asm-agent/.venv/bin/asm-agent",
        "ASM_MCP_REPORT_DIR": "/absolute/path/to/asm-mcp-server/reports"
      }
    }
  }
}
```

登録後、MCPクライアントを再起動または再接続します。

MCPクライアントへ接続すると、`asm-mcp-server`が標準入出力通信で起動します。LLMが`scan_domain`を呼び出した時点で`asm-agent scan`が開始され、調査終了後に`asm-agent`のプロセスは終了します。

Windowsでは、次のコマンドで`uv.exe`の場所を確認できます。

```powershell
where.exe uv
```

`ASM_AGENT_EXECUTABLE`は次の形式です。

```text
C:\absolute\path\to\asm-agent\.venv\Scripts\asm-agent.exe
```

JSON内のWindowsパスでは、`\`を`\\`と記述する必要があります。

## 会話例

```text
example.comをShodanありで調査して、見つかったホスト名、IPアドレス、公開ポート、CVE候補を根拠付きでまとめて。
```

## 利用できるツール

| ツール | 内容 |
|---|---|
| `scan_domain` | ドメインの公開情報を収集して保存します |
| `list_reports` | 保存済みレポートの一覧を返します |
| `get_report_summary` | 収集件数、警告、エラーを返します |
| `list_assets` | ホスト名、IPアドレス、公開サービスを返します |
| `get_evidence` | 情報源と観測日時を返します |
| `list_vulnerabilities` | ShodanのCVE候補、製品、バージョンを返します |

一覧を返すツールは`offset`と`limit`で分割取得できます。

## 設定

| 環境変数 | 既定値 | 内容 |
|---|---|---|
| `ASM_AGENT_EXECUTABLE` | PATH上の`asm-agent` | 実行する`asm-agent`の絶対パス |
| `ASM_MCP_REPORT_DIR` | `./reports` | レポート保存先 |
| `ASM_MCP_SCAN_TIMEOUT_SECONDS` | `600` | 1回の調査を待つ最大秒数 |

ShodanのCVEは過去の観測に基づく候補であり、現在も脆弱であることを証明するものではありません。

## 開発

```bash
uv run ruff check .
uv run mypy src
uv run pytest
```

## ライセンス

[MIT License](LICENSE)