{
  "markdown": "# osmcp — OS Capabilities for AI Agents\n\n> **A typed, policy-controlled OS capability layer for AI agents via the Model Context Protocol (MCP).**\n\nosmcp 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.\n\n📖 **Read the comprehensive [Architecture & Design Document](docs/ARCHITECTURE.md)** for a deep dive into the philosophy, safety boundaries, and design decisions behind osmcp.\n\n[![LiteLLM Compatible](https://img.shields.io/badge/LiteLLM-Compatible-blue?style=flat-square)](docs/integrations/litellm.md)\n[![Smithery Verified](https://img.shields.io/badge/Smithery-Verified-green?style=flat-square)](#smithery-integration)\n\n## Features\n\n| Category | Tools | Phase |\n|---|---|---|\n| 🔍 **Search** | `grep`, `find` | 1 |\n| 📁 **File Inspection** | `ls`, `cat`, `stat`, `wc`, `head`, `tail` | 1 |\n| 🌳 **Filesystem** | `tree`, `du` | 1 |\n| 🔀 **Git Intelligence** | `git_status`, `git_diff`, `git_log` | 1 |\n| 🔧 **Transform** | `jq`, `sed`, `diff` | 1 |\n| ✍️ **File Mutation** | `write_file`, `append_file`, `mkdir`, `rm`, `mv`, `cp`, `patch` | 2 |\n| 🚀 **Git Mutation** | `git_add`, `git_commit`, `git_checkout`, `git_branch`, `git_pull`, `git_push` | 2 |\n\n## Architecture\n\n```\nAI Agent (Claude, GPT, etc.)\n    │  MCP JSON-RPC (stdio)\n    ▼\nosmcp binary\n    ├── Policy Engine      ← enforces allowed_root, allowed_tools, limits\n    ├── Audit Logger       ← append-only NDJSON log of every invocation\n    ├── Tool Registry      ← self-registering tools via RegisterMCP()\n    └── Envelope Builder   ← typed {ok, data, error, meta} responses\n```\n\n## Demo\n\n![osmcp Demo Action](https://raw.githubusercontent.com/KrushnaVardhanReddy/osmcp/main/assets/demo.gif)\n*A demonstration of Claude Desktop securely editing code via osmcp, safely bounded by a TOML policy engine.*\n\n## Quick Start\n\n### 1. Install via Homebrew\n\n```bash\nbrew tap KrushnaVardhanReddy/tap\nbrew install osmcp\n```\n\n*Alternatively, build from source:*\n```bash\nmake build\n# Binary: bin/osmcp\n```\n\n### 2. Configure a Policy\n\n```toml\n# policy.toml\n[policy]\nallowed_root   = \"/home/user/myproject\"\nallowed_tools  = [\"grep\", \"ls\", \"cat\", \"git_status\", \"git_log\"]\nallow_mutation = false\n\n[limits]\ntimeout_ms       = 5000\nmax_output_bytes = 1048576\nmax_matches      = 100\n\n[audit]\ndestination = \"stderr\"   # or \"file\"\npath        = \"/var/log/osmcp-audit.ndjson\"\n```\n\n### 3. Run\n\n```bash\nbin/osmcp --policy policy.toml\n```\n\nThe binary communicates over **stdio** using MCP JSON-RPC. Connect any MCP-compatible client.\n\n## Client Integrations\n\n### Claude Desktop\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"osmcp\": {\n      \"command\": \"osmcp\",\n      \"args\": [\"--policy\", \"/absolute/path/to/policy.toml\"]\n    }\n  }\n}\n```\n\n### Smithery (npx)\nTo install `osmcp` for Claude Desktop automatically via Smithery:\n\n```bash\nnpx @smithery/cli install osmcp\n```\n\n### LiteLLM\nIntegrate `osmcp` into your enterprise LLM proxy using the [LiteLLM MCP Gateway](docs/integrations/litellm.md).\n\n### 5. Test\n\n```bash\nmake test     # unit tests\nmake e2e      # end-to-end tests against real binary\nmake lint     # golangci-lint\n```\n\n## Policy Security Model\n\n- **`allowed_root`** — All filesystem paths are validated to be inside this root. Traversal outside is blocked with `POLICY_DENIED`.\n- **`allowed_tools`** — Only tools in this list are visible to the MCP client. Unlisted tools do not appear in `tools/list`.\n- **`allow_mutation`** — When `false`, mutating tools (write, delete, git commit) are globally blocked.\n- **Limits** — Per-invocation timeout, output byte cap, and match count cap prevent runaway operations.\n\n## Envelope Response Format\n\nAll tool responses follow a consistent typed envelope:\n\n```json\n{\n  \"ok\": true,\n  \"tool\": \"grep\",\n  \"data\": { ... },\n  \"error\": null,\n  \"meta\": {\n    \"execution_time_ms\": 12,\n    \"truncated\": false\n  }\n}\n```\n\n## License\n\nMIT\n\n## Acknowledgements\n\n`osmcp` would not be possible without the incredible open-source libraries it is built upon:\n- [mcp-go](https://github.com/mark3labs/mcp-go) for the core Model Context Protocol SDK.\n- [go-git](https://github.com/go-git/go-git) for pure Go git manipulation.\n- [gojq](https://github.com/itchyny/gojq) for pure Go JSON processing.\n- [go-gitdiff](https://github.com/bluekeyes/go-gitdiff) for parsing and applying patches.\n- [grep-go](https://github.com/tanqiangyes/grep-go) for regular expression searching.\n- [toml](https://github.com/BurntSushi/toml) for configuration parsing.\n",
  "bytes": 4648,
  "sha": "6a739340ab47b1ac36cc500269826825e3981f2fafd7b28235a6e826389a1dd2",
  "repo_slug": "krushnavardhanreddy/osmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_krushnavardhanreddy_osmcp_97f78473/readme"
}