path: root/README.md

# AI Agent Sandbox MCP Server v1

Windows 11上でlocal Ollamaを利用し、明示的に承認したFilesystem、Process、Network操作だけをAppContainer内で実行するMCP Serverです。MCP `2026-07-28`のstateless HTTPと公式Tasks Extensionに対応し、MCP公開Toolは `agent_run` と `agent_status` の2つです。

## 動作要件

- Windows 11 x64
- 管理者権限（TaskごとのWFP filter追加・削除に必要）
- Base Filtering Engine (BFE)が実行中
- Ollama。tested versionは実測した `0.32.6`。minimum supported versionは未確定です。
- Release既定local model: `hf.co/TrevorJS/gemma-4-E4B-it-uncensored-GGUF:Q4_K_M`（native Tool calling対応）

サービス、常駐helper、恒久Firewall ruleは使用しません。WFP objectはdynamic sessionだけに作成されます。AppContainerからlocalhostへ接続するTaskでは、固定AppContainer SIDのloopback exemptionをTask中だけ追加し、終了時または次回起動Recoveryで削除します。

## 初回セットアップ

管理者としてPowerShellを起動し、Release Bundleへ移動します。

```powershell
ollama --version
ollama pull hf.co/TrevorJS/gemma-4-E4B-it-uncensored-GGUF:Q4_K_M
ollama serve
```

別の管理者PowerShellで診断します。

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

`administrator=true`、`bfe_engine_open=true`、`wfp_write_transaction=true`、`wfp_filter_add_delete=true` が必要です。probeはdynamic WFP filterを追加後すぐ削除し、残留させません。

`serve`も待受開始前に同じprobeを必ず実行します。失敗時はendpointをbindせず、失敗項目・Win32 error・対処方法をstderrと`logs/application.log`へ出してexit code 2で終了します。

## agent.yaml

Filesystem pathは能力ごとに指定します。未指定能力はdenyです。

MCP Taskの保持とlog出力は次のtyped settingで変更できます。

```yaml
mcp:
  tasks:
    time_to_live_hours: 24
    poll_interval_ms: 1000
logging:
  directory: logs
  level: information       # information / warning / error / fatal
  http_requests: true
  max_file_bytes: 10485760
  retained_files: 5
```

配布された`agent.yaml`と同じdirectoryに任意の`agent.local.yaml`を置くと、環境固有値だけを上書きできます。mapは再帰merge、scalarと配列はlocal側で置換され、merge後の全設定を通常どおり検証します。相対pathは`agent.yaml`のdirectory基準です。local設定から利用者固有のSystem PromptやSkill directoryを指定できます。`agent.local.yaml`と、その参照先prompt／SkillはRelease Bundleへ含まれず、publishでも上書きされません。雛形は`config/agent.local.example.yaml`です。

引数なし、または最初の引数がoptionの場合は`serve`として扱われます。次の2つは同じです。

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

Task状態は`state/mcp-tasks/`へatomic保存されます。再起動時の未完了Taskは`failed/server_restarted`となり、自動再実行されません。

```yaml
sandbox:
  filesystem:
    read: [C:/work/fixture]
    write: [C:/work/fixture]
    execute:
      - C:/Program Files/dotnet/dotnet.exe
    delete: [C:/work/fixture]
```

実行ファイルはcanonical absolute pathとSHA-256の両方を承認します。

```powershell
(Get-FileHash -Algorithm SHA256 -LiteralPath 'C:\Program Files\dotnet\dotnet.exe').Hash
```

```yaml
sandbox:
  process:
    allow_shell: false
    approvals:
      - path: C:/Program Files/dotnet/dotnet.exe
        sha256: <64桁の実測値>
```

Sandbox processからの子process生成は、承認済みpathであってもOSのchild-process restrictionで拒否されます。build/testで必要な各実行ファイルは事前にpath/hash承認し、個別の `process_run` としてBrokerから起動してください。E2Eではbuild server、node reuse、shared compilationを無効化し、in-process buildまたはBrokerから直接起動できるself-testを使用します。Networkは既定でlocalhostを含めdenyです。allow時はTask開始時にhostをIPへsnapshot化します。

```yaml
sandbox:
  network:
    mode: allow
    allow:
      - host: 127.0.0.1
        ports: [11434]
```

Ollama通信は管理Broker側から行うため、Sandbox processのnetwork許可とは独立です。

## Agent Skills

`skills/<skill-name>/SKILL.md`形式だけを読み込みます。legacyの`skills/*.md`は読み込みません。SkillはLLMへの補助指示であり、Filesystem/Process/Network権限は付与しません。Skillが使用する実行ファイルは、別途`agent.yaml`でabsolute pathとSHA-256を承認してください。

## stdio

WFP操作のため、stdioではMCP Client自体を管理者PowerShellから起動します。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"]
    }
  }
}
```

`agent_run`へ自然言語の依頼を送り、返却されたUUIDを `agent_status` でterminal stateまでpollします。複数Taskはqueuedで受理しますが、planning/runningおよびTask Resource適用は全体で1件です。

## Streamable HTTP

管理者PowerShellでserverを起動します。`MCPリクエストを受け付けられます`とendpointが表示されてから接続してください。

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

Client endpointは `http://127.0.0.1:8080/mcp` です。設定できるbindは `127.0.0.1` または `::1` だけです。HTTPはMCP `2026-07-28` statelessで`Mcp-Session-Id`を使用しません。SDKの旧initialize fallbackは維持しますが、GET SSE、`/sse`、`/message` Legacy SSEは利用できません。

Tasks対応clientは`agent_run`を公式MCP Taskとして受け取り、`tasks/get`と`tasks/cancel`を使用できます。非対応clientは従来どおりqueued textから`task_id`を取得し、`agent_status`でpollします。`session_id`はAgent会話IDでありHTTP transport sessionではありません。

## LogとRecovery

- `logs/application.log`: 起動・診断・管理event
- `logs/llm.jsonl`: LLM request/response、token usage、tool result
- `logs/audit.jsonl`: Task ID付きfile/process/policy/ACL/WFP/recovery event
- `logs/http.jsonl`: connection/trace ID、実socketの接続元IP/port、method/path/status/duration、MCP routing header
- `state/journals/`: crash recovery journal。正常終了後は空
- `state/backups/`: 大容量file transaction backup。正常終了後は空

log directoryは起動ユーザーだけがアクセスできるprotected DACLへ設定されます。起動時はMCP受付前にRecoveryを実行し、復旧不能なhash競合があれば起動しません。

HTTP logは`X-Forwarded-For`を接続元として信用せず、Authorization、Cookie、query、body、prompt、画像、Base64を保存しません。stateless HTTPでは永続接続を主張せず、request started/completedとして記録します。

HTTP request処理はconsole/file出力と同期しません。運用logはbounded queue経由でbackground出力し、consoleが一時停止してもHTTP requestを停止させません。queue飽和時はrequest継続を優先し、drop件数をapplication logへ警告します。

LLM/Audit JSONLはtask、session、event、call単位で絞り込めます。

```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
```

正常停止後、`agent-mcp.exe` descendant、追加ACL、WFP filter、loopback exemption、`state/backups`、`state/journals` が残っていないことを確認してください。loopback exemptionは `CheckNetIsolation.exe LoopbackExempt -s` で確認できます。

## よくあるエラー

- `error 5` / administrator=false: 管理者PowerShellから起動してください。
- BFE open失敗: `Get-Service BFE` でBase Filtering Engineを確認してください。
- Ollama接続失敗: `ollama list`、endpoint、model名を確認してください。
- executable deny: pathをabsolute/canonicalにし、更新後のSHA-256を再取得してください。
- file deny: 対象pathを必要なread/write/execute/delete能力へ追加し、再起動してください。
- rollback拒否: Task中に外部processが同じfileを変更しています。Audit Logとjournalを確認し、手動reviewしてください。

## ソースからのbuild／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\Acquire-McpConformance.ps1
# 管理者権限でserverを起動後:
.\scripts\Run-McpConformance.ps1 -Url http://127.0.0.1:8080/mcp
.\scripts\Publish-Release.ps1
```

生成物はすべてrepository rootの `build/` に集約されます。

- `build/Debug/<ProjectName>/`: Debug build
- `build/Release/<ProjectName>/`: Release build
- `build/obj/<ProjectName>/`: restoreおよびcompiler中間生成物
- `build/Release/publish/`: win-x64 self-contained Bundle、version付きZIP、checksum

`artifacts/` はローカルの試験証跡・デバッグログ用です。`artifacts/` と `build/` はどちらもGit管理外です。

Release scriptはwin-x64 self-contained directory、version付きZIP、ZIP checksum、publish manifestを生成し、ソースツリー外のfresh temporary directoryでBundleを検査します。完全な `agent-mcp check` は管理者PowerShellで実行してください。