io.github.KrushnaVardhanReddy/osmcp
A typed, policy-controlled OS capability layer for AI agents.
Open source Open in the app JSON README (API)
About
A typed, policy-controlled OS capability layer for AI agents.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- krushnavardhanreddy
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.5
- Open pull requests
- 1
- Last push
- 2026-08-16T01:16:27Z
- Repository state
- ativo
- Language
- Go
- License
- MIT
- Added
- 2026-08-29 03:02:01
- Updated
- 2026-08-29 03:02:01
- Origin id
io.github.KrushnaVardhanReddy/osmcp
README
# osmcp — OS Capabilities for AI Agents
> **A typed, policy-controlled OS capability layer for AI agents via the Model Context Protocol (MCP).**
osmcp exposes a curated set of safe filesystem, git, and text-processing tools to AI agents — all governed by a strict **Policy Engine** that enforces path boundaries, tool allowlists, output limits, mutation controls, and an immutable audit trail.
📖 **Read the comprehensive [Architecture & Design Document](docs/ARCHITECTURE.md)** for a deep dive into the philosophy, safety boundaries, and design decisions behind osmcp.
[](docs/integrations/litellm.md)
[](#smithery-integration)
## Features
| Category | Tools | Phase |
|---|---|---|
| 🔍 **Search** | `grep`, `find` | 1 |
| 📁 **File Inspection** | `ls`, `cat`, `stat`, `wc`, `head`, `tail` | 1 |
| 🌳 **Filesystem** | `tree`, `du` | 1 |
| 🔀 **Git Intelligence** | `git_status`, `git_diff`, `git_log` | 1 |
| 🔧 **Transform** | `jq`, `sed`, `diff` | 1 |
| ✍️ **File Mutation** | `write_file`, `append_file`, `mkdir`, `rm`, `mv`, `cp`, `patch` | 2 |
| 🚀 **Git Mutation** | `git_add`, `git_commit`, `git_checkout`, `git_branch`, `git_pull`, `git_push` | 2 |
## Architecture
```
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
```
## Demo
*A demonstration of Claude Desktop securely editing code via osmcp, safely bounded by a TOML policy engine.*
## Quick Start
### 1. Install via Homebrew
```bash
brew tap KrushnaVardhanReddy/tap
brew install osmcp
```
*Alternatively, build from source:*
```bash
make build
# Binary: bin/osmcp
```
### 2. Configure a Policy
```toml
# 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. Run
```bash
bin/osmcp --policy policy.toml
```
The binary communicates over **stdio** using MCP JSON-RPC. Connect any MCP-compatible client.
## Client Integrations
### Claude Desktop
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"osmcp": {
"command": "osmcp",
"args": ["--policy", "/absolute/path/to/policy.toml"]
}
}
}
```
### Smithery (npx)
To install `osmcp` for Claude Desktop automatically via Smithery:
```bash
npx @smithery/cli install osmcp
```
### LiteLLM
Integrate `osmcp` into your enterprise LLM proxy using the [LiteLLM MCP Gateway](docs/integrations/litellm.md).
### 5. Test
```bash
make test # unit tests
make e2e # end-to-end tests against real binary
make lint # golangci-lint
```
## Policy Security Model
- **`allowed_root`** — All filesystem paths are validated to be inside this root. Traversal outside is blocked with `POLICY_DENIED`.
- **`allowed_tools`** — Only tools in this list are visible to the MCP client. Unlisted tools do not appear in `tools/list`.
- **`allow_mutation`** — When `false`, mutating tools (write, delete, git commit) are globally blocked.
- **Limits** — Per-invocation timeout, output byte cap, and match count cap prevent runaway operations.
## Envelope Response Format
All tool responses follow a consistent typed envelope:
```json
{
"ok": true,
"tool": "grep",
"data": { ... },
"error": null,
"meta": {
"execution_time_ms": 12,
"truncated": false
}
}
```
## License
MIT
## Acknowledgements
`osmcp` would not be possible without the incredible open-source libraries it is built upon:
- [mcp-go](https://github.com/mark3labs/mcp-go) for the core Model Context Protocol SDK.
- [go-git](https://github.com/go-git/go-git) for pure Go git manipulation.
- [gojq](https://github.com/itchyny/gojq) for pure Go JSON processing.
- [go-gitdiff](https://github.com/bluekeyes/go-gitdiff) for parsing and applying patches.
- [grep-go](https://github.com/tanqiangyes/grep-go) for regular expression searching.
- [toml](https://github.com/BurntSushi/toml) for configuration parsing.