path: root/README.md

# AI Agent Sandbox MCP Server

Windows上でローカルのOllamaを利用し、AIエージェントのファイル操作とプロセス実行を、利用者が確認した範囲に閉じ込めるMCP Serverです。

MCP Clientには `agent_run` と `agent_status` だけを公開します。エージェントが内部で行うファイル操作・プロセス実行は、Workspace、Mount、承認済みExecutable、Network、Resourceの設定とWindowsの強制機構によって制限されます。

## 主な機能

- Ollamaモデルによる、計画・コード作成・ファイル編集・コマンド実行の自動化
- MCPのstdioとStreamable HTTP（stateless）への対応
- MCP Tasks Extensionによる非同期Taskの取得・キャンセル
- WorkspaceとMountを分けた、読み取り・書き込み・削除・実行の権限設定
- 実行前に人間が確認するExecutable AliasとSHA-256承認
- LPAC、NTFS ACL、Job Object、WFPによるSandbox Process Treeの制限
- 日本語・英語のメッセージ、監査ログ、異常終了後の自動Recovery
- `agent.yaml`と、環境ごとの差分を置ける`agent.local.yaml`のマージ

## 動作環境

| 項目 | 要件 |
| --- | --- |
| OS | Windows 11 x64 |
| 権限 | 管理者権限のPowerShell。TaskごとのWFP設定に必要です。 |
| Windowsサービス | Base Filtering Engine（BFE）が起動していること |
| LLM | Ollama。Release既定モデルは`deepseek-v4-flash:cloud`です。 |
| MCP Client | stdioまたはStreamable HTTPを利用できるClient |

Ollamaへの通信はBroker側で行われます。Sandbox内プロセスのNetwork許可とは別に設定されます。

## インストール

Release Bundleを任意のディレクトリへ展開します。以降の例では、展開先を`<install-dir>`と表記します。

```text
<install-dir>/
  agent-mcp.exe
  agent.yaml
  prompts/
  skills/
```

`agent.yaml`は配布時の共通設定です。利用者固有の設定は、同じディレクトリに`agent.local.yaml`を作成して記載してください。publishやupgradeは`agent.local.yaml`、`local/`、`logs/`、`state/`、ユーザーごとの承認・確認情報を上書きしません。

## 初回セットアップ

### 1. Ollamaを準備する

Ollamaをインストール後、モデルを取得して起動します。

```powershell
ollama pull deepseek-v4-flash:cloud
ollama serve
```

既にOllama Serviceまたは`ollama serve`が起動している場合、重複して起動する必要はありません。

### 2. ローカル設定を作成する

`agent.yaml`と同じディレクトリへ`agent.local.yaml`を作成します。最小例は次のとおりです。

```yaml
application:
  language: ja

agent:
  user_system_prompt: local/prompts/user-system.md

skills:
  directory: local/skills

sandbox:
  profile: development
  workspaces:
    - C:/work/project
  mounts: []
  execution:
    executables: [python]
    shells: []
```

`agent.local.yaml`は、共通設定から変更したい項目だけを書きます。mapは再帰的にマージされ、scalarと配列はlocal側で置換されます。そのため、`workspaces`や`mounts`をlocal側に書く場合は、最終的に必要な要素をすべて列挙してください。

相対パスは`agent.yaml`のあるディレクトリを基準に解決されます。マージ後の設定全体に対して検証が行われるため、未知のキーや矛盾した設定は起動前にエラーになります。

### 3. Sandboxの対象を確認する

管理者としてPowerShellを起動し、展開先へ移動します。

```powershell
cd <install-dir>
.\agent-mcp.exe sandbox resolve --config .\agent.yaml
.\agent-mcp.exe sandbox confirm --config .\agent.yaml
.\agent-mcp.exe sandbox show --format text --config .\agent.yaml
```

`resolve`は設定されたパスを実体パスへ解決して表示するだけです。内容を確認した後、`confirm`で確認済み結果をユーザーごとのStoreへ保存します。Workspace、Mount、設定内容またはリンクの解決先が変わると、再確認するまで起動はfail-closedになります。

### 4. 使用するExecutableを承認する

設定したAliasごとに、実行ファイルの候補を確認し、使用する実体を明示して承認します。

```powershell
.\agent-mcp.exe executable resolve python --config .\agent.yaml
.\agent-mcp.exe executable approve python `
  --path C:\Python314\python.exe `
  --runtime-root C:\Python314 `
  --config .\agent.yaml
.\agent-mcp.exe executable list --config .\agent.yaml
```

承認時にはResolved PathとSHA-256が保存されます。実行ファイルのパスまたはハッシュが変わった場合は、自動では更新されず、再承認が必要です。

最後に起動前診断を実行します。

```powershell
.\agent-mcp.exe check --config .\agent.yaml --lang ja
```

## Sandbox設定

`schema_version: 1`の設定では、Sandboxを利用者が理解できる単位で指定します。未指定の権限は許可されません。

```yaml
sandbox:
  profile: development

  workspaces:
    - C:/work/project

  mounts:
    - path: C:/data/reference
      access: read_only

  execution:
    executables: [python, git]
    shells: [powershell]

  network:
    access: local
    local_endpoints:
      - port: 11434
    restricted_endpoints: []

  resources:
    profile: normal
    # memory_mb: 4096
    # process_limit: 16
    # execution_timeout_seconds: 1800
```

### WorkspaceとMount

| 設定 | 用途 | 実行 |
| --- | --- | --- |
| `workspaces` | エージェントが作業するプロジェクト領域 | `development`ではWorkspace内の成果物をEntry Processとして実行できます。 |
| `mounts` | 参照データや追加の入出力領域 | Mount上のExecutableは直接起動できません。 |

`profile`には次を指定します。

| Profile | Workspaceの権限 | Workspace ArtifactのEntry実行 |
| --- | --- | --- |
| `readonly` | read | 不可 |
| `development` | read / write / delete | 可 |

Mountの`access`には`read_only`、`read_write`、`read_write_delete`を指定します。`readonly` Profileでは`read_only`だけが使用できます。

### ExecutableとShell

`execution.executables`と`execution.shells`には、実行を許可したいAliasを記載します。Aliasを設定しただけでは実行できず、前節の`executable approve`で実体パスとハッシュを承認する必要があります。

- Executable: 例 `python`、`git`
- Shell: `cmd.exe`、`powershell.exe`、`pwsh.exe`に対応するAlias

承認は最初にBrokerが直接起動するEntry Processにだけ適用されます。Entry Processから生成される子孫Processには個別承認を要求しませんが、同じLPAC、ACL、WFP、Job Objectの制限を継承します。未知の外部ExecutableやMount上のExecutableは、Brokerから直接起動できません。

#### cmd.exeを有効にする例

`agent.local.yaml`のShell一覧へAliasを追加します。配列はlocal側で置換されるため、ほかのShellも使う場合はすべて列挙してください。

```yaml
sandbox:
  profile: development
  workspaces:
    - C:/tmp
  execution:
    executables:
      - python
    shells:
      - cmd
```

管理者として起動したPowerShellで、cmdの実体を確認して承認します。cmdはWindowsのOS Runtime Rootを利用するため、追加Runtime Rootを登録しない`--no-runtime`を指定します。

```powershell
cd <install-dir>
.\agent-mcp.exe executable resolve cmd `
  --path C:\Windows\System32\cmd.exe `
  --config .\agent.yaml
.\agent-mcp.exe executable approve cmd `
  --path C:\Windows\System32\cmd.exe `
  --no-runtime `
  --config .\agent.yaml
.\agent-mcp.exe executable list --config .\agent.yaml
.\agent-mcp.exe check --config .\agent.yaml --lang ja
```

非対話で承認する場合だけ`approve`へ`--yes`を付けます。この操作はAuditへ記録されます。

cmdから子Processを呼ぶ場合は、`cmd.exe`、`curl.exe`、`.venv\Scripts\python.exe`のようにPATHで解決できる名前またはWorkspace相対パスを使います。`%ComSpec%`や`%SystemRoot%\System32\curl.exe`のようなドライブ修飾絶対パスは、cmd自身が事前にvolume情報へアクセスするため、LPACではOSに拒否されることがあります。これは子Process生成の禁止ではありません。

### Network

| `access` | 許可内容 |
| --- | --- |
| `none` | localhostを含むすべてのネットワーク通信を拒否します。 |
| `local` | `local_endpoints`に列挙したportへの`127.0.0.1`および`::1`だけを許可します。 |
| `restricted` | `restricted_endpoints`に列挙したhost/portをTask開始時にIPへ固定して許可します。 |

空のendpoint設定やmodeと矛盾する設定は拒否されます。

### Resource

`resources.profile`の既定値は以下です。個別の正数指定で上書きできます。

| Profile | メモリ | Process数 | 実行時間 |
| --- | ---: | ---: | ---: |
| `constrained` | 1024 MiB | 4 | 300秒 |
| `normal` | 4096 MiB | 16 | 1800秒 |
| `extended` | 8192 MiB | 32 | 3600秒 |

## CLIリファレンス

すべてのCLI commandは`agent-mcp.exe`から実行します。`serve`と`check`では`--config`を省略でき、その場合は実行ファイルと同じディレクトリの`agent.yaml`を使用します。`executable`および`sandbox`の管理commandでは`--config`が必須です。

| Command | 必須の位置引数 | 使用できるoption | 用途 | 設定・Storeの変更 |
| --- | --- | --- | --- | --- |
| `[serve]` | なし | `--config <file>`、`--lang <locale>`、`--transport <stdio\|http>` | MCP Serverを起動します。commandを省略した場合、または最初の引数がoptionの場合も`serve`として扱います。 | なし。ただしTask実行中には一時的なSandbox Resourceを適用します。 |
| `check` | なし | `--config <file>`、`--lang <locale>` | 設定、Resolution、Approval、管理者権限、BFE、WFP操作を診断します。 | なし |
| `executable resolve` | `<alias>` | `--path <path>`、`--config <file>`、`--lang <locale>` | Aliasに対応するPATH候補、または指定pathを解決して表示します。 | なし |
| `executable approve` | `<alias>` | `--path <path>`、`--runtime-root <path>`または`--no-runtime`、`--yes`、`--config <file>`、`--lang <locale>` | ExecutableまたはShellの実体パスとSHA-256を承認します。 | Approval Storeを更新 |
| `executable list` | なし | `--config <file>`、`--lang <locale>` | 承認済みExecutableを一覧表示します。 | なし |
| `executable revoke` | `<alias>` | `--yes`、`--config <file>`、`--lang <locale>` | AliasのExecutable Approvalを取り消します。 | Approval Storeを更新 |
| `sandbox resolve` | なし | `--config <file>`、`--lang <locale>` | WorkspaceとMountのLogical Pathを実体パスへ解決し、確認候補を表示します。 | なし |
| `sandbox confirm` | なし | `--yes`、`--config <file>`、`--lang <locale>` | 現在のSandbox Environment Resolutionを確認済みとして保存します。 | Resolution Storeを更新 |
| `sandbox show` | なし | `--format <text\|json>`、`--config <file>`、`--lang <locale>` | 現在のResolution、確認状態、Effective Sandbox Policyを表示します。 | なし |

### 引数とoptionの意味

| 引数・option | 値 | 説明 |
| --- | --- | --- |
| `<alias>` | 設定したAlias名 | `sandbox.execution.executables`または`sandbox.execution.shells`に宣言した名前です。Alias自体は承認を意味しません。 |
| `--config <file>` | YAMLファイルのpath | base設定ファイルを指定します。同じディレクトリの`agent.local.yaml`は自動的にマージされます。 |
| `--lang <locale>` | 例: `ja`、`en` | CLIおよび起動時の利用者向けメッセージの言語を、その実行に限って上書きします。 |
| `--transport <stdio\|http>` | `stdio`または`http` | `serve`時だけ使用できます。設定ファイルの`mcp.transport`をその起動に限って上書きします。 |
| `--path <path>` | Executable fileのpath | `executable resolve`では候補検索対象、`executable approve`では承認対象を明示します。候補が曖昧な場合は必須です。 |
| `--runtime-root <path>` | Runtime directoryのpath | 承認するEntry ExecutableのRuntime Rootを明示します。存在するディレクトリでなければなりません。 |
| `--no-runtime` | 値なし | Runtime Rootを登録しないことを明示します。`executable approve`では`--runtime-root`とのどちらか一方が必要です。 |
| `--yes` | 値なし | `approve`、`revoke`、`confirm`の対話確認を省略します。非対話操作としてAudit Logに記録されます。 |
| `--format <text\|json>` | `text`または`json` | `sandbox show`の出力形式です。既定値は`text`です。 |

`resolve`、`list`、`show`、`check`はread-onlyです。`approve`、`revoke`、`confirm`は差分表示後に確認を求めます。標準入力が対話的でない場合は、内容を確認したうえで明示的に`--yes`を指定してください。

## 起動と接続

`serve`は起動前に管理者権限、BFE、WFP、設定、Resolution、Executable Approvalを検査します。いずれかが失敗すると待受を開始せず、エラーと対処方法を表示します。

### stdio

stdioを使う場合は、MCP Client自体を管理者権限で起動してください。

```json
{
  "mcpServers": {
    "agent-sandbox": {
      "command": "C:\\tools\\agent-sandbox-mcp\\agent-mcp.exe",
      "args": [
        "serve",
        "--config", "C:\\tools\\agent-sandbox-mcp\\agent.yaml",
        "--lang", "ja",
        "--transport", "stdio"
      ]
    }
  }
}
```

### Streamable HTTP

管理者PowerShellでServerを起動します。

```powershell
.\agent-mcp.exe serve --config .\agent.yaml --lang ja --transport http
```

既定endpointは`http://127.0.0.1:8080/mcp`です。bind先には`127.0.0.1`または`::1`だけを設定できます。HTTPはstatelessであり、`Mcp-Session-Id`や旧SSE endpoint（`/sse`、`/message`）は使用しません。

`serve`は既定commandなので、次も同じです。

```powershell
.\agent-mcp.exe --config .\agent.yaml
```

## MCPでの利用

公開されるMCP Toolは次の2つです。

| Tool | 用途 |
| --- | --- |
| `agent_run` | 自然言語の依頼を新規または既存のAgent Sessionへ登録します。非同期でTask IDとSession IDを返します。 |
| `agent_status` | Taskの状態、進捗、token実績、最終結果または利用者向けエラーを取得します。 |

例えば、`agent_run`には「Workspace内にPythonプログラムとテストを作成し、実行して検証して」のような依頼を渡します。複数Taskは受付順にqueuedとなり、planning/runningとSandbox Resourceの適用は一度に1件だけです。

Tasks Extension対応Clientでは、`agent_run`の結果をMCP Taskとして受け取り、`tasks/get`と`tasks/cancel`で追跡できます。非対応Clientでは、返された`task_id`を指定して`agent_status`を呼び出します。

## PromptとSkill

System Promptは`agent.user_system_prompt`、Skill directoryは`skills.directory`で指定します。Skillは次の形式で配置します。

```text
skills/
  <skill-name>/
    SKILL.md
```

SkillはLLMに与える補助指示であり、Sandboxの権限を増やしません。Skillの記述に実行コマンドが含まれていても、Executable Alias、Approval、Filesystem権限、Network権限は通常どおり必要です。

## ログ、監査、復旧

| 場所 | 内容 |
| --- | --- |
| `logs/application.log` | 起動、診断、アプリケーションイベント |
| `logs/llm.jsonl` | Ollama call、token使用量、Internal Tool結果 |
| `logs/audit.jsonl` | ファイル・プロセス・Policy・ACL・WFP・Recoveryの監査イベント |
| `logs/http.jsonl` | HTTPリクエストの接続情報と処理結果 |
| `state/journals/` | 異常終了からの復旧用Journal |
| `state/backups/` | 大容量ファイル編集のtransaction backup |

ログは起動ユーザーだけがアクセスできるDACLで保護されます。HTTPログにはAuthorization、Cookie、request body、prompt、画像、Base64を記録しません。

LLM/Audit JSONLを絞り込むには、付属のread-only scriptを使えます。

```powershell
.\scripts\Read-AgentLog.ps1 -Path .\logs\llm.jsonl -TaskId <task-id> -Tail 100
.\scripts\Read-AgentLog.ps1 -Path .\logs\audit.jsonl -Event policy.deny -Tail 100
```

起動時には未完了のJournalを復旧してからMCP受付を開始します。再起動時に未完了だったTaskは自動再実行されず、`failed/server_restarted`になります。

## よくある問題

| 状況 | 対処 |
| --- | --- |
| 管理者権限またはWFP probeの失敗 | 管理者PowerShellから起動し、`Get-Service BFE`でBFEを確認します。 |
| Ollama接続失敗 | `ollama list`、Ollama endpoint、model名を確認します。 |
| Resolution未確認または変更 | `sandbox resolve`で差分を確認し、`sandbox confirm`を実行します。 |
| Alias不明、Approval不足、hash変更 | `executable resolve`で候補を確認してから`executable approve`を実行します。 |
| Filesystem拒否 | 対象を適切なWorkspaceまたはMountとして設定し、Resolutionを再確認します。 |
| rollback拒否 | 外部Processが同じファイルを変更している可能性があります。Audit LogとJournalを確認し、手動で内容を確認します。 |

## 開発者向け

ソースからbuild・test・releaseする場合は以下を実行します。

```powershell
dotnet restore AgentSandboxMcp.slnx
dotnet build AgentSandboxMcp.slnx -c Release --no-restore
dotnet test AgentSandboxMcp.slnx -c Release --no-build --no-restore
.\scripts\Publish-Release.ps1
```

build成果物は`build/`、ローカル試験の証跡は`artifacts/`に作成されます。どちらもGit管理外です。

詳細な仕様と設計は[仕様書](doc/Specifications.md)、[設計書](doc/Design.md)を参照してください。

## ライセンス

MIT