# osmcp

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/KrushnaVardhanReddy/osmcp  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/osmcp

## Description
A typed, policy-controlled OS capability layer for AI agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "osmcp": {
    "command": "npx",
    "args": ["-y","osmcp"]
  }
}
```

## Documentation & 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](https://github.com/KrushnaVardhanReddy/osmcp/blob/HEAD/docs/ARCHITECTURE.md)** for a deep dive into the philosophy, safety boundaries, and design decisions behind osmcp.

[![LiteLLM Compatible](https://img.shields.io/badge/LiteLLM-Compatible-blue?style=flat-square)](docs/integrations/litellm.md)
[![Smithery Verified](https://img.shields.io/badge/Smithery-Verified-green?style=flat-square)](#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

![osmcp Demo Action](https://raw.githubusercontent.com/KrushnaVardhanReddy/osmcp/main/assets/demo.gif)
*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](https://github.com/KrushnaVardhanReddy/osmcp/blob/HEAD/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.