portage-mcp 0.1.0

Turn any command-line tool into an MCP server — by reading its own --help. No per-tool code.

Quick start · How it works · Security · CLI · Config · Remote · Roadmap

What is this?

There are thousands of command-line tools — ffmpeg, jq, ripgrep, git, curl, your own scripts — and almost none of them have a Model Context Protocol server, so an AI assistant can't use them. Writing one by hand for every CLI is repetitive busywork.

Portage does it automatically. Point it at a CLI, and it:

<tool> --help  ──▶  parse (sections · usage · options · commands · type inference)
               ──▶  normalized CLI IR  ──▶  JSON Schema / MCP tool definitions
               ──▶  stdio (or HTTP) MCP server  ──▶  your AI assistant
                                              └──▶  safe, allow-listed execution

One generic pipeline handles every CLI. There is no if tool == "git" anywhere — a test enforces it.

Status — local MVP complete. Discovery, --help and man-page parsing, schema generation, the stdio/HTTP MCP server, the execution engine, and the full safety layer are implemented and tested (360 unit tests, 16 integration against real jq / ripgrep / curl / git / ffmpeg, ~91 % coverage, ruff + mypy --strict clean). The remote front door is scaffolded and verified locally; edge deploy is a manual one-liner.

⚡ Quick start

git clone https://github.com/jayaprakash2207/Portage-_MCP.git
cd Portage-_MCP
python -m venv .venv && . .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

portage doctor                     # environment check
portage inspect jq                 # discovery + parsed IR + generated tools, as JSON

Connect it to Claude

Claude Code

claude mcp add portage -- portage serve jq ripgrep curl git

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "portage": { "command": "portage", "args": ["serve", "jq", "ripgrep", "curl", "git"] }
  }
}

Restart the client. The generated tools appear in the tool list. With the default config a tool call returns a structured preview (validation + authorization + the exact argv) and runs nothing — enabling real execution is a deliberate, per-CLI opt-in (see Configuration).

🧭 How it works

flowchart TD
    A["CLI on your machine"] -->|"help capture"| B["discovery"]
    A -.->|"man tool"| B
    B --> C["parser<br/>sections · usage · options<br/>commands · type inference"]
    C --> D["normalized CLI IR (CliProgram)"]
    D --> E["schema generator"]
    E --> F["MCP tool defs<br/>JSON Schema + arg_specs"]
    F --> G["stdio / HTTP MCP server"]
    G <--> H["AI assistant"]
    H -->|"tools/call"| I["safety pipeline"]
    I --> J["schema validation"]
    J --> K["per-value policy"]
    K --> L["allow-list — default deny"]
    L --> M["safe argv build — no shell"]
    M --> N["sandbox + rlimits + timeout"]
    N --> O["subprocess"]
    O --> P["structured result + audit event"]

Each stage is its own module and depends only on the shared data model — parsing, schema generation, protocol handling and execution never import one another.

✨ Features

🔒 Security model

Portage lets an AI assistant run real commands, so the execution path is the product. Every tools/call goes through, in order:

The executable is chosen by Portage from the tool definition and passed to the engine as an absolute path — an MCP caller cannot select or redirect it.

🖥 CLI

$ portage inspect jq --no-man
{
  "discovery": { "status": "ok", "help": { "command_display": "jq --help", ... } },
  "ir": { "name": "jq", "confidence": "high", "global_options": [ ... ], "positionals": [{ "name": "filter", "required": true }] },
  "tools": [ { "name": "jq", "input_schema": { "type": "object", "additionalProperties": false, ... } } ]
}

⚙ Configuration

portage serve --config portage.json. Everything not listed stays denied.

{
  "server_name": "portage",
  "clis": [
    {
      "name": "git",
      "use_man_page": true,
      "discover_subcommands": true,
      "subcommand_depth": 2,
      "policy": {
        "execution_enabled": true,
        "allowed_commands": [["git", "status"], ["git", "log"], ["git", "show"]],
        "allowed_options": ["--oneline", "--stat", "--short", "-n"],
        "timeout_seconds": 20,
        "value_rules": [{ "json_name": "max_count", "pattern": "\\d{1,4}" }],
        "resource_limits": { "cpu_seconds": 15, "memory_mb": 512, "max_processes": 64 },
        "sandbox": { "mode": "auto", "backend": "bubblewrap", "allow_network": false }
      }
    },
    { "name": "jq", "policy": { "execution_enabled": false } }
  ]
}

A ready-to-adapt version is in deploy/portage.example.json.

🌐 Remote deployment

Cloudflare Workers can't run native binaries, so the design is two parts:

MCP client ──HTTP──▶ Portage-Protocol (Cloudflare Worker: auth + reverse proxy)
                          │
                          ▼  HTTPS
                     Portage-Engine (this package: portage serve --http)
                          │
                          ▼
                     the real CLI

• Engine: anywhere that runs Python 3.10+ and the CLIs — portage serve --config … --http --host 0.0.0.0 --port 8080.
• Worker: deploy/cloudflare-worker/ — type-checks with tsc, and the whole chain is verified locally (test-local.ps1 / test-local.sh): health route, 401 without the bearer token, a real MCP initialize proxied through. Edge deploy: npx wrangler secret put PORTAGE_ENGINE_TOKEN && npx wrangler deploy.

Details in deploy/README.md.

🧪 Development

ruff check .                     # lint
mypy                             # type-check (strict)
pytest -q                        # 360 unit tests — no network, no CLIs needed
pytest -q --run-integration -m integration   # + real jq/rg/curl/git/ffmpeg (+ bubblewrap)
pytest -q --cov=portage          # coverage

🗺 Roadmap

• CLI discovery + --help capture
• Layered --help parser → normalized IR
• JSON Schema / MCP tool generation
• stdio MCP server + tool discovery
• Execution engine — structured argv, no shell
• Safety layer — validation · value policy · default-deny allow-list · audit · dry-run
• Man-page parsing + deterministic merge
• End-to-end against 5 real CLIs, no per-tool code
• POSIX resource limits + bubblewrap/firejail/docker sandbox (fail-closed)
• Recursive subcommand discovery (git remote add → git_remote_add)
• Streamable HTTP transport + Cloudflare Worker front door (verified locally)
• Usage-line alternation decomposition ([-p | --paginate | -P] → options)
• PyPI packaging (python -m build + twine check pass; trusted-publishing release workflow)
• wrangler deploy to the edge (needs a hosted Engine URL)
• Container / restricted-user isolation actually exercised on a Linux host
• tbl-formatted man tables; a live docker-backend sandbox test
• Cut the first GitHub Release → auto-publish to PyPI · submit to MCP registries

Why "Portage"?

A portage is carrying a boat overland between two waterways — bridging things that don't otherwise connect. Portage carries CLI functionality across into the MCP waterway so AI assistants can use it.

License

MIT — see LICENSE. Contributions welcome; see CONTRIBUTING.md.