osmcp

osmcp — 面向 AI Agent 的操作系统能力

通过 Model Context Protocol（MCP）为 AI Agent 提供类型化、受策略控制的操作系统能力层。

osmcp 向 AI Agent 提供一组经过筛选的安全文件系统、git 和文本处理工具，所有工具均由严格的策略引擎管理，强制执行路径边界、工具允许列表、输出限制、变更控制和不可变审计轨迹。

📖 阅读全面的架构与设计文档，深入了解 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

演示

演示 Claude Desktop 如何通过 osmcp 安全地编辑代码，并由 TOML 策略引擎严格限制操作范围。

快速开始

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

二进制程序通过 stdio 使用 MCP JSON-RPC 进行通信。可连接任何兼容 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 提交）都会被全局阻止。
• 限制 — 每次调用的超时、输出字节数上限和匹配数量上限可防止操作失控。

信封响应格式

所有工具响应都遵循统一的类型化信封格式：

{
  "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，用于解析配置。