osmcp

osmcp — AI エージェント向け OS 機能

Model Context Protocol（MCP）を介して、AI エージェントに型安全でポリシー制御された OS 機能レイヤーを提供します。

osmcp は、安全性を考慮して厳選されたファイルシステム、git、テキスト処理のツール群を AI エージェントに提供します。すべてのツールは、パス境界、ツールの許可リスト、出力制限、変更制御、不変の監査証跡を適用する厳格なポリシーエンジンによって管理されます。

📖 osmcp の理念、安全境界、設計上の判断について詳しく知りたい方は、包括的なアーキテクチャおよび設計ドキュメントをご覧ください。

機能

カテゴリ	ツール	フェーズ
🔍 検索	grep、find	1
📁 ファイル検査	ls、cat、stat、wc、head、tail	1
🌳 ファイルシステム	tree、du	1
🔀 Git インテリジェンス	git_status、git_diff、git_log	1
🔧 変換	jq、sed、diff	1
✍️ ファイル変更	write_file、append_file、mkdir、rm、mv、cp、patch	2
🚀 Git の変更	git_add、git_commit、git_checkout、git_branch、git_pull、git_push	2

アーキテクチャ

AI Agent (Claude, GPT, etc.)
    │  MCP JSON-RPC (stdio)
    ▼
osmcp binary
    ├── Policy Engine      ← enforces allowed_root, allowed_tools, limits
    ├── Audit Logger       ← append-only NDJSON log of every invocation
    ├── Tool Registry      ← self-registering tools via RegisterMCP()
    └── Envelope Builder   ← typed {ok, data, error, meta} responses

デモ

TOML ポリシーエンジンによって安全な範囲に制限された osmcp を介して、Claude Desktop がコードを安全に編集するデモです。

クイックスタート

1. Homebrew でインストール

brew tap KrushnaVardhanReddy/tap
brew install osmcp

または、ソースからビルドします。

make build
# Binary: bin/osmcp

2. ポリシーを設定

# policy.toml
[policy]
allowed_root   = "/home/user/myproject"
allowed_tools  = ["grep", "ls", "cat", "git_status", "git_log"]
allow_mutation = false

[limits]
timeout_ms       = 5000
max_output_bytes = 1048576
max_matches      = 100

[audit]
destination = "stderr"   # or "file"
path        = "/var/log/osmcp-audit.ndjson"

3. 実行

bin/osmcp --policy policy.toml

バイナリは、MCP JSON-RPC を使用して stdio 経由で通信します。MCP 互換のクライアントを接続してください。

クライアントとの連携

Claude Desktop

次の内容を claude_desktop_config.json に追加してください。

{
  "mcpServers": {
    "osmcp": {
      "command": "osmcp",
      "args": ["--policy", "/absolute/path/to/policy.toml"]
    }
  }
}

Smithery（npx）

Smithery を使って、Claude Desktop 用に osmcp を自動インストールするには：

npx @smithery/cli install osmcp

LiteLLM

LiteLLM MCP Gateway を使用して、osmcp をエンタープライズ LLM プロキシに統合します。

5. テスト

make test     # unit tests
make e2e      # end-to-end tests against real binary
make lint     # golangci-lint

ポリシーセキュリティモデル

• allowed_root — すべてのファイルシステムパスがこのルート内にあるか検証されます。ルート外への移動は POLICY_DENIED でブロックされます。
• allowed_tools — このリストに含まれるツールのみが MCP クライアントに表示されます。リストにないツールは tools/list に表示されません。
• allow_mutation — false の場合、変更を行うツール（書き込み、削除、git commit）はすべてブロックされます。
• 制限 — 呼び出しごとのタイムアウト、出力バイト数の上限、マッチ数の上限により、処理が際限なく実行されるのを防ぎます。

エンベロープ応答形式

すべてのツールの応答は、一貫した型付きエンベロープに従います。

{
  "ok": true,
  "tool": "grep",
  "data": { ... },
  "error": null,
  "meta": {
    "execution_time_ms": 12,
    "truncated": false
  }
}

ライセンス

MIT

謝辞

osmcp は、基盤として使用している素晴らしいオープンソースライブラリなしには実現できませんでした。

• mcp-go：Model Context Protocol の中核となる SDK。
• go-git：純粋な Go による git 操作。
• gojq：純粋な Go による JSON 処理。
• go-gitdiff：パッチの解析と適用。
• grep-go：正規表現検索。
• toml：設定の解析。