{
  "markdown": "# MCP Shell Aliases Server\n\nA Model Context Protocol (MCP) server that exposes your shell aliases as safe, discoverable tools. It parses configured alias files (e.g. `~/.bash_aliases`) and surfaces them to MCP hosts such as the Gemini CLI.\n\n## Features\n\n- Discovers aliases from explicitly configured files.\n- Emits MCP tools/resources for dry-run and real execution.\n- Enforces allowlist-only safety rules and dry-run by default.\n- Sandboxes execution with constrained environment, cwd policy, and timeouts.\n- Writes structured audit logs for every invocation.\n\n## Quick Start\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\n\n# copy and edit a config\ncp examples/sample_config.yaml config.yaml\n\n# run the server over stdio\nmcp-shell-aliases --config config.yaml --verbose\n```\n\nPoint your MCP host at the `mcp-shell-aliases` executable (or `python3 -m mcp_shell_aliases`) with the same config file.\n\n## Configuration\n\nThe server loads settings from `config.yaml`, environment variables (`MCP_SHELL_ALIASES_*`), and CLI flags. See `docs/CONFIGURATION.md` for the full reference. A minimal config:\n\n```yaml\nalias_files:\n  - ~/.bash_aliases\nallow_patterns:\n  - '^ls\\b'\n```\n\n## Safety Model\n\n- Aliases are classified using allowlist regexes. Anything that fails to match stays in dry-run mode.\n- Real execution requires `dry_run=false` and `confirm=true` tool arguments.\n- Commands execute via `/bin/bash -lc` with a scrubbed environment, bounded output, and timeouts.\n- Audit logs capture every call. See `docs/SECURITY.md` for details.\n\n## Host Integration\n\nUpdate your MCP host configuration to use the new server, for example in `gemini-extension.json`:\n\n```json\n{\n  \"mcp_server\": {\n    \"command\": [\n      \"python3\",\n      \"-m\",\n      \"mcp_shell_aliases\",\n      \"--config\",\n      \"${extensionPath}/config.yaml\"\n    ]\n  }\n}\n```\n\nVerify by listing the `alias.catalog` tool, reading the `alias://catalog` resource, and executing a safe alias with `dry_run`.\n\n### HTTP/SSE Transports\n\nSome agentic tools prefer to talk over HTTP instead of stdio. You can start the\nserver on a local port with:\n\n```bash\nmcp-shell-aliases \\\n  --config config.yaml \\\n  --transport http \\\n  --http-host 127.0.0.1 \\\n  --http-port 3921 \\\n  --http-path /mcp\n```\n\nThen point your host at `http://127.0.0.1:3921/mcp`. Use `--transport sse` or\n`--transport streamable-http` for alternative FastMCP transports.\n\nIf using the Gemini CLI, ensure your project’s `.gemini/settings.json` has an\n`mcpServers` entry with `httpUrl` (not `command`) for HTTP transports:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-shell-aliases\": {\n      \"httpUrl\": \"http://127.0.0.1:3921/mcp\"\n    }\n  }\n}\n```\n\nTo add an HTTP server to the Gemini CLI, you must explicitly use the `--transport http` flag:\n\n## Gemini Extensions (Stdio)\n\nThis repository includes a `gemini-extension.json` manifest so it can be installed directly with the Gemini CLI:\n\n```bash\ngemini extensions install https://github.com/<you>/mcp-shell-aliases\n```\n\nThe manifest configures the MCP server as a stdio server. It launches a small `bootstrap.py` that creates a local virtual environment under the extension folder, installs minimal runtime dependencies, and then starts the server via `-m mcp_shell_aliases` with the bundled `config.yaml`.\n\nAfter installation, the server appears in the Gemini CLI under the extension’s name. You can override the config path by editing the installed extension’s manifest or by copying `config.yaml` into your project and updating your `.gemini/settings.json` entry.\n\n### Minimal Docker Smoke Test\n\nYou can sanity-check that the bootstrap and dependencies work in a clean environment using Docker (no Gemini CLI required):\n\n```bash\nbash scripts/docker-smoke.sh\n```\n\nThis builds a tiny image, provisions the venv inside the container, and starts the server in HTTP mode on `localhost:3921` so you can hit it with `curl` while confirming the package installs cleanly. For stdio, override the `CMD` when running the container and attach a client.\n\n### Full Gemini Install Test (Docker)\n\nRun a full install test that boots a fresh container, installs the Gemini CLI, installs this extension from a Git URL, and verifies it appears in `gemini extensions list`:\n\n```bash\n# Provide the Git URL for your repo and the Gemini CLI install command.\nEXT_URL=https://github.com/<you>/mcp-shell-aliases \\\nGEMINI_INSTALL=\"npm i -g @google/gemini-cli\" \\\nbash scripts/docker-gemini-extensions-test.sh\n\n# Or pass the URL as an arg (EXT_URL is optional if repo has a remote):\nbash scripts/docker-gemini-extensions-test.sh https://github.com/<you>/mcp-shell-aliases\n```\n\nNotes:\n- The script uses `node:20-bookworm-slim` and installs Python 3. It requires network access to fetch the CLI and your repo.\n- If the Gemini CLI package name differs in your environment, set `GEMINI_INSTALL` to the correct install command (e.g., `npm i -g <pkg>`).\n\n```bash\ngemini mcp add mcp-shell-aliases http://127.0.0.1:3921/mcp --transport http\n```\n\n**Note:** For HTTP and SSE transports, the `mcp-shell-aliases` server must be running independently before you add it to the Gemini CLI. The CLI will not automatically start HTTP/SSE servers.\n\nIf the CLI still can’t connect, switch the server to `--transport sse` and reuse\nthe same URL.\n\n## Project Status\n\n- ✅ Python/FastMCP implementation exposes `alias.exec` and browseable resources.\n- ✅ Safety rails enforced: dry-run default, allowlist patterns, timeouts, cwd policy, audit logs.\n- ✅ Hot reload is available via on-demand catalog refresh (no file watcher yet).\n- 🚧 Prompt helpers, inotify-style hot reload, and advanced hardening are still on the roadmap (see `TODO.md`).\n\n## Testing & Quality\n\n```bash\n# lint\nruff check mcp_shell_aliases tests\n\n# unit + contract suite (includes in-process MCP smoke tests)\npytest --cov=mcp_shell_aliases --cov-report=term-missing\n\n# type checking (requires stub package: python -m pip install types-PyYAML)\nmypy mcp_shell_aliases\n```\n\nThe test suite exercises alias parsing, sandbox execution, CLI entry points, and\nthe FastMCP server itself via the official Python client. See\n`docs/Testing.md` for the complete breakdown and troubleshooting tips.\n\n## Tool Usage Example\n\n```json\n{\n  \"tool\": \"alias.exec\",\n  \"arguments\": {\n    \"name\": \"ll\",\n    \"args\": \"~/projects\",\n    \"dry_run\": true\n  }\n}\n```\n\nUnsafe aliases will always return dry-run results unless they match the configured allowlist patterns.\n\n## Tool API and CWD Guidance\n\nUse these parameters with `alias.exec` to control execution and working directory.\n\n- name: alias name to run.\n- args: optional string appended to the alias expansion.\n- dry_run: true by default; set to false to execute.\n- confirm: required when `dry_run` is false. Acts as a safety gate.\n- cwd: working directory to run in; defaults to `default_cwd` (usually `~`). Must be inside `allow_cwd_roots`.\n- timeout_seconds: optional positive integer; must be ≤ 5× `execution.default_timeout_seconds`.\n\nResponse fields include `command`, `cwd`, `exitCode`, `stdout`, `stderr`, `truncated`, `timedOut`, `dryRun`, plus `aliasSafe` and `sourceFile` for context.\n\n### Running in the right directory (cwd)\n\n- Default behavior: If you do not pass `cwd`, commands run in `default_cwd` (home by default).\n- For repo‑specific aliases (e.g., git), pass a project path explicitly:\n  - `alias.exec {\"name\":\"gst\",\"dry_run\": false, \"confirm\": true, \"cwd\": \"/path/to/repo\"}`\n- With agents: Ask the agent to include a `cwd` that points at your project root when calling tools. Example instruction: “When running git aliases, set `cwd` to the current project directory.”\n\n### Safety and allowlist\n\n- An alias is “safe” only if its expansion matches `allow_patterns`.\n- Unsafe aliases can still be previewed with `dry_run: true`.\n- Real execution requires both `dry_run: false` and `confirm: true`.\n\n### Hot reload vs. config changes\n\n- The server re-parses alias files and re-applies the in-memory allowlist on each request (hot reload).\n- Editing `config.yaml` itself (e.g., changing `allow_patterns`, `default_cwd`, or `alias_files`) requires restarting the server for changes to take effect.\n\n## Contributing\n\nSee `gemini-shell-aliases/CONTRIBUTING.md` for development workflow and coding standards.\n",
  "bytes": 8247,
  "sha": "ba730d446359fb60235e4d66baf1332278a93e5152c94c183559df1c718367fb",
  "repo_slug": "hestonhamilton/mcp-shell-aliases",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hestonhamilton_mcp_shell_aliases_c315a200/readme"
}