{"id":"2ac06ae5-17d7-4532-832a-a976071173ae","slug":"agent-workstation","kind":"mcp","name":"agent-workstation","summary":"API/CLI-first MCP workstation adapter: explicit host trust, on-demand skills and bounded context.","owner":"zix-chen","repoUrl":"https://github.com/zix-chen/agent-workstation","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-13T04:11:20.000Z","addedAt":"2026-10-21T09:41:08.828Z","logoUrl":"https://avatars.githubusercontent.com/u/39701873?u=5c0c61826345dd3962acd5c457e4337e3b69d557&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":["ai-agents","developer-tools","python"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:01:11.009Z","sample":false,"url":"https://conduits.dev/tools/agent-workstation","language":"Python","transports":["stdio"],"install":{"pypi":"agent-workstation"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Agent Workstation\n\n[简体中文](README.zh-CN.md) · [Security](SECURITY.md) · [Architecture](docs/architecture.md) · [Client setup](docs/clients.md)\n\n**Bring an MCP client into your developer workflow. Prefer APIs and CLIs over clicking screens.**\n\nA small, opinionated adapter built on [Coding Tools MCP](https://github.com/xyTom/coding-tools-mcp).\nIt adds explicit workstation trust, multi-repository context discovery, a lazy rules/skills/recipes\nentry point, and bounded command previews. It does **not** implement a new model, agent loop,\nSQL engine, browser driver, or secret vault.\n\n## What is actually new?\n\n| Inherited from Coding Tools MCP | Added here |\n| --- | --- |\n| Files, patches, search, Git, process lifecycle, MCP transport | Explicit `workspace` / `trusted-workstation` launch modes |\n| Output retention, references, pagination | 8 KiB default head/tail preview with stderr budgeting |\n| Root instruction loading | Bounded multi-repo discovery and target-path rule lookup |\n| Generic command execution | `workspace_guide`: on-demand skill metadata and opt-in recipe routing |\n\nThe adapter pins upstream commit `bedb632e1afd2e9ec9b268a50fe0b04695c22c64`.\nIts package metadata says 0.3.0; this is **not** a claimed upstream 0.5 release.\nUpstream-private imports/hooks are isolated in `agent_workstation/compat/coding_tools.py`.\nA mismatched upstream build fails at startup rather than silently running an untested adapter.\n\n## Install and try\n\nRequirements: Python 3.11+, Git; macOS or Linux. Your own MCP client supplies the model.\nNo Codex installation or model API key is required by this server.\nThe package is installed from GitHub; it is not published to PyPI in this release.\n\n```bash\n# An isolated environment; does not alter another MCP installation.\npython3 -m venv .venv\n. .venv/bin/activate\npython -m pip install \"git+https://github.com/zix-chen/agent-workstation.git@v0.1.1\"\nagent-workstation --workspace /path/to/repository --doctor\nagent-workstation --workspace /path/to/repository --stdio\n```\n\nGeneric stdio MCP configuration (use an absolute executable path):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-workstation\": {\n      \"command\": \"/absolute/path/to/.venv/bin/agent-workstation\",\n      \"args\": [\"--workspace\", \"/absolute/path/to/work\", \"--mode\", \"workspace\", \"--stdio\"]\n    }\n  }\n}\n```\n\nAsk the client: **“Call workspace_guide for this repository, read the relevant rules/skill,\nthen review this change. Report evidence and what you did not verify.”**\n\n### Explicit workstation access\n\n```bash\nagent-workstation --workspace \"$HOME/work\" --mode trusted-workstation --stdio\n```\n\n**This gives commands your real HOME, local developer configuration, network access and\naccess outside the workspace. Commands can read secrets, modify files and operate services\nwith your user privileges. It is NOT secret isolation or protection from prompt injection.**\nUse trusted code and a trusted agent, or a disposable account/VM with reduced credentials.\n\nDefault `workspace` mode retains upstream safe command gates, isolated HOME and structured\npath validation. **It is not a complete OS sandbox**, especially on macOS. Repository rules\nare workflow guidance, not permission enforcement. See [SECURITY.md](SECURITY.md).\n\n### Rules, skills and recipes\n\n```text\nwork/\n  AGENTS.md\n  repo-a/\n    AGENTS.md\n    .agents/skills/review/SKILL.md\n  repo-b/\n    src/AGENTS.md\n```\n\n`workspace_guide(path=\"repo-a\")` returns applicable rule paths and skill name/description/hash.\nIt does **not** inject every skill's full body. The agent selects and fully reads the smallest\nrelevant skill. Same-name skills retain their source paths. Startup avoids recursive workspace\nwalks, skips generated/worktree directories and uses Git metadata at actual repository roots.\nTarget-path lookup can still find rules under a skipped tree when explicitly selected.\n\nRecipes are explicitly loaded TOML, never auto-executed:\n\n```bash\nagent-workstation --workspace \"$PWD/examples/demo-service\"   --config \"$PWD/examples/demo-service/workstation.toml\" --stdio\n```\n\nSee the [runnable example](examples/demo-service) and [configuration contract](docs/configuration.md).\nExternal skill roots require explicit config **and** trusted-workstation mode.\n`kubectl`, `mysql`, `redis-cli`, cloud CLIs and their credentials are user-managed, not bundled integrations.\n\n## Reproduce the demo and benchmark\n\n```bash\ngit clone https://github.com/zix-chen/agent-workstation.git\ncd agent-workstation\npython3 -m venv .venv\n. .venv/bin/activate\npython -m pip install -e '.[dev]'\npython -m unittest discover -s tests -v\npython scripts/demo.py\npython scripts/benchmark_output.py\npython scripts/check_release.py\n```\n\nThe demo uses a **temporary copy** of a fake backend, calls real MCP tools, checks a local HTTP\nhealth endpoint, diagnoses a missing demo configuration, and verifies the corrected process.\nIt uses no private infrastructure or model credentials. It is a deterministic integration demo,\n**not** a claim of autonomous model task success.\n\nThe benchmark reports output bytes and serialized response bytes. It does not measure model\ntokens, subscription quotas, speedups, or dollars saved. Explicit output arguments override\ndefaults. Follow `read_output` references when previews truncate; retained output can expire\nor lose its middle segment. Save an authorized log file for durable/full logs.\n\n## HTTP and remote clients\n\nAn optional loopback HTTP listener requires a bearer token even on localhost:\n\n```bash\n# Supply a random 32+ character secret through your process supervisor/secret manager.\n# Never put the real value in this repo, the README, or a model prompt.\nagent-workstation --workspace /path/to/work --transport http --port 8765\n# Reads AGENT_WORKSTATION_HTTP_TOKEN; startup refuses an absent/short token.\n```\n\nRemote access requires your own authenticated HTTPS transport and a compatible client.\nOAuth registration and tunnels are **not** implemented by this V1. A generic stdio configuration\nis not a ChatGPT web connection. See [client setup and verification boundaries](docs/clients.md).\nNo public listener or tunnel is installed automatically.\n\nA real run transcript is available in [docs/demo-output.txt](docs/demo-output.txt).\n\n## Scope and status\n\nV0.1 is a small developer-tool release, not an enterprise platform. Computer/browser automation,\nGUI secret filling, company-specific integrations, production deployment automation and a plugin\nmarketplace are intentionally excluded. See [validation](docs/validation.md) for actual test results.\n\n[Design decisions](docs/architecture.md) cover the adapter architecture, trust model, and verification boundaries.\n\n## License and attribution\n\nApache-2.0. Built on Coding Tools MCP, Copyright 2026 Coding Tools MCP Contributors.\nSee [NOTICE](NOTICE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). No private\nrepository history, employee accounts, business code or production configuration is distributed.\n\nThe pinned upstream read_file also caps a page at 2,000 lines. Raising max_bytes does not\nremove that cap; use next_start_line to read the remaining pages.\n"}